virt 0.1.0

data/README.rdoc

@@ -0,0 +1,82 @@
+= virt
+
+Simple to use ruby interface to libvirt.
+
+Libvirt is located at http://libvirt.org/ruby
+
+== Contributing
+
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== RDOC
+
+for full API please visit http://rdoc.info/github/ohadlevy/virt
+
+== Examples
+
+=== Connectivity Options
+  uri = "qemu:///system"              # libvirt running locally
+  uri = "qemu:/fqdn//system"          # used for QEMU+TLS connection
+  uri = "qemu+ssh:/user@fqdn//system" # used for SSH connection
+  uri = "qemu+tcp:/fqdn//system"      # used for non secured tcp connection
+
+==== Establish the connection
+  conn = Virt.connect(uri)
+
+==== get the hypervisor
+  host = conn.host
+
+==== get the list of running guests
+  host.running_guests
+
+==== get the list of stopped guests
+  host.defined_guests
+
+====or a simple hash of both
+  host.guests
+
+==== create a new guest
+
+  guest=Virt::Guest.new({:name => "test123"})
+  guest.vcpu = 2
+  guest.volume.size = 10 # in GB
+
+  guest.save
+  guest.start
+
+  puts guest.mac
+
+  guest.stop
+Many more options exists, make sure checkout the api/tests
+
+==== list of host bridges
+  host.interfaces # physical interfaces
+  host.networks   # virtual / NAT interfaces
+
+==== Storage
+
+  host.storage_pools
+
+  host.volumes
+
+
+
+== Copyright
+Copyright (c) 2011 Ohad Levy
+
+This program and entire repository is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # Gem::Specification... see http://docs.rubygems.org/read/chapter/20
+  gem.name = "virt"
+  gem.homepage = "https://github.com/ohadlevy/virt"
+  gem.license = "GPLv3"
+  gem.summary = %Q{Simple to use ruby interface to libvirt}
+  gem.description = %Q{Simplied interface to use ruby the libvirt ruby library}
+  gem.email = "ohadlevy@gmail.com"
+  gem.authors = ["Ohad Levy"]
+
+  #gem.add_runtime_dependency 'libvirt', '> 0.2.0'
+  #gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/*test*.rb'
+  test.verbose = true
+  test.warning = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "hello-gem #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/virt/connection.rb

@@ -0,0 +1,32 @@
+require 'libvirt'
+module Virt
+  class Connection
+    attr_reader :connection
+
+    def initialize uri
+      raise("Must provide a guest to connect to") unless uri
+      @connection = Libvirt::open uri
+    end
+
+    def closed?
+      connection.closed?
+    end
+
+    def secure?
+      connection.encrypted?
+    end
+
+    def version
+      connection.libversion
+    end
+
+    def disconnect
+      connection.close
+    end
+
+    def host
+      Host.new
+    end
+
+  end
+end

data/lib/virt/guest.rb

@@ -0,0 +1,102 @@
+module Virt
+  class Guest
+    include Virt::Util
+    attr_reader :name, :xml_desc
+    attr_accessor :memory, :vcpu, :arch, :volume, :interface, :template_path
+
+    def initialize options = {}
+    @connection = Virt.connection
+    @name       = options[:name]   || raise("Must provide a name")
+    # If our domain exists, we ignore the provided options and defaults
+    fetch_guest
+    @memory ||= options[:memory] || default_memory_size
+    @vcpu   ||= options[:vcpu]   || default_vcpu_count
+    @arch   ||= options[:arch]   || default_arch
+
+    @template_path = options[:template_path] || default_template_path
+    @volume        = Volume.new options
+    @interface     = Interface.new options.merge({:mac => @mac})
+    end
+
+    def new?
+      @domain.nil?
+    end
+
+    def save
+      @domain = @connection.connection.define_domain_xml(xml)
+      fetch_info
+      !new?
+    end
+
+    def start
+      raise "Guest not created, can't start" if new?
+      @domain.create unless running?
+      running?
+    end
+
+    def running?
+      return false if new?
+      @domain.active?
+    rescue 
+      # some versions of libvirt do not support checking for active state
+      @connection.connection.list_domains.each do |did|
+        return true if @connection.connection.lookup_domain_by_id(did).name == name
+      end
+      false
+    end
+
+    def stop
+      raise "Guest not created, can't stop" if new?
+      @domain.destroy
+      !running?
+    rescue Libvirt::Error
+      # domain is not running
+      true
+    end
+
+    def destroy
+      return true if new?
+      stop if running?
+      @domain = @domain.undefine
+      new?
+    end
+
+    def uuid
+      @domain.uuid unless new?
+    end
+
+    private
+
+    def fetch_guest
+      @domain = @connection.connection.lookup_domain_by_name(name)
+      fetch_info
+    rescue Libvirt::RetrieveError
+    end
+
+    def fetch_info
+      return if @domain.nil?
+      @xml_desc = @domain.xml_desc
+      @memory   = @domain.max_memory
+      @vcpu     = document("domain/vcpu")
+      @arch     = document("domain/os/type", "arch")
+      @mac      = document("domain/devices/interface/mac", "address")
+      @interface.mac = @mac if @interface
+    end
+
+    def default_memory_size
+      1048576
+    end
+
+    def default_vcpu_count
+      1
+    end
+
+    def default_arch
+      "x86_64"
+    end
+
+    def default_template_path
+      "guest.xml.erb"
+    end
+  end
+end

data/lib/virt/host.rb

@@ -0,0 +1,80 @@
+module Virt
+  class Host < Virt::Connection
+    # Represents a Physical host which runs the libvirt daemon
+
+    attr_reader :connection
+    def initialize
+      @connection = Virt.connection.connection
+    end
+
+    def name
+      connection.hostname
+    end
+
+    def guests
+      {:running => running_guests, :defined => defined_guests}
+    end
+
+    def running_guests
+      connection.list_domains.map do |domain|
+        find_guest_by_id(domain)
+      end
+    end
+
+    def defined_guests
+      connection.list_defined_domains.map do |domain|
+        find_guest_by_name domain
+      end
+    end
+
+    # Available libvirt interfaces, excluding lo
+    def interfaces
+      connection.list_interfaces.delete_if{|i| i == "lo"}.sort
+    rescue => e
+      raise "This function is not supported by the hypervisor: #{e}"
+    end
+
+    def interface iface
+      connection.lookup_interface_by_name(iface)
+    end
+
+    # libvirt internal networks
+    def networks
+      connection.list_networks.map do |network|
+        connection.lookup_network_by_name(network).bridge_name
+      end
+    end
+
+    def storage_pools
+      connection.list_storage_pools.map {|p| Pool.new({:name => p})}
+    end
+
+    # Returns a Virt::Pool object based on the pool name
+    def storage_pool pool
+      Pool.new({:name => pool.is_a?(Libvirt::StoragePool) ? pool.name : pool })
+    rescue Libvirt::RetrieveError
+    end
+
+    # Returns a hash of pools and their volumes objects.
+    def volumes
+      pools = {}
+      storage_pools.each do |storage|
+        pools[storage.name] = storage.volumes
+      end
+      pools
+    end
+
+    def find_guest_by_name name
+      if connection.lookup_domain_by_name name
+        return Guest.new({:name => name})
+      end
+    end
+
+    def find_guest_by_id id
+      id.to_a.map do |did|
+        return Guest.new({:name => connection.lookup_domain_by_id(did).name})
+      end
+    end
+
+  end
+end

data/lib/virt/interface.rb

@@ -0,0 +1,34 @@
+module Virt
+  class Interface
+    attr_accessor  :mac, :model, :type, :device
+
+    def initialize options = {}
+      @connection = Virt.connection
+      @device     = options[:device] || default_device
+      @type       = options[:type]   || default_type
+      @model      = options[:model]  || default_model
+      @mac        = options[:mac]
+    end
+
+    def new?
+      mac.nil?
+    end
+
+    private
+
+    def default_device
+      @connection.host.interfaces.first
+    rescue
+      "br0"
+    end
+
+    def default_type
+      "bridge"
+    end
+
+    def default_model
+      "virtio"
+    end
+
+  end
+end

data/lib/virt/pool.rb

@@ -0,0 +1,53 @@
+module Virt
+# implements Libvirt pool, at the moment it is assumed to be a file based pool.
+  class Pool
+    include Virt::Util
+    attr_reader :name
+    def initialize options = {}
+      @name = options[:name] || raise("Must Provide a pool name")
+      @connection = Virt.connection
+      fetch_pool
+    end
+
+    alias :to_s :name
+
+    def save
+      raise "not implemented"
+    end
+
+    def new?
+      @pool.nil?
+    end
+
+    def volumes
+      @pool.list_volumes
+    end
+
+    %w{name key path}.each do |method|
+      define_method "find_volume_by_#{method}" do |value|
+        begin
+          @pool.send("lookup_volume_by_#{method}", value)
+        rescue Libvirt::RetrieveError
+        end
+      end
+    end
+
+    def path
+      document "pool/target/path"
+    end
+
+    def create_vol vol
+      raise "Must provide a Virt::Volume object" unless vol.is_a?(Virt::Volume)
+      raise "Pool not saved, cant create volume" if new?
+      @pool.create_vol_xml vol.xml
+    end
+
+    private
+
+    def fetch_pool
+      if @pool = @connection.connection.lookup_storage_pool_by_name(name)
+        @xml_desc = @pool.xml_desc
+      end
+    end
+  end
+end

data/lib/virt/util.rb

@@ -0,0 +1,26 @@
+require "rexml/document"
+require 'erb'
+
+module Virt
+  module Util
+    # return templated xml to be used by libvirt
+    def xml
+      ERB.new(template, nil, '-').result(binding)
+    end
+
+    private
+    # template file that contain our xml template
+    def template
+      File.read("#{File.dirname(__FILE__)}/../../templates/#{template_path}")
+    rescue => e
+      warn "failed to read template #{template_path}: #{e}"
+    end
+
+    # finds a value from xml
+    def document path, attribute=nil
+      return nil if new?
+      xml = REXML::Document.new(@xml_desc)
+      attribute.nil? ? xml.elements[path].text : xml.elements[path].attributes[attribute]
+    end
+  end
+end

data/lib/virt/volume.rb

@@ -0,0 +1,69 @@
+module Virt
+  class Volume
+    include Virt::Util
+    attr_reader :name, :pool, :path, :type, :allocated_size, :size, :template_path, :key
+
+    def initialize options = {}
+      @connection     = Virt.connection
+      self.name       = options[:name]           || raise("Volume requires a name")
+      @type           = options[:type]           || default_type
+      @allocated_size = options[:allocated_size] || default_allocated_size
+      @template_path  = options[:template_path]  || default_template_path
+      @size           = options[:size]           || default_size
+      @pool           = @connection.host.storage_pool(options[:pool] || "default")
+      fetch_volume
+    end
+
+    def new?
+      @vol.nil?
+    end
+
+    def save
+      raise "volume already exists, can't save" unless new?
+      #validations
+      #update?
+      @vol=pool.create_vol(self)
+      !new?
+    end
+
+    def destroy
+      return true if new?
+      @vol.delete
+      fetch_volume
+      new?
+    end
+
+    def path
+      "#{pool.path}/#{name}"
+    end
+
+    private
+
+    def name= name
+      raise "invalid name" if name.nil?
+      @name = name
+      @name += ".img" unless name.match(/.*\.img$/)
+    end
+
+    def default_type
+      "raw"
+    end
+
+    def default_allocated_size
+      0
+    end
+
+    # default image size in GB
+    def default_size
+      8
+    end
+
+    def default_template_path
+      "volume.xml.erb"
+    end
+
+    def fetch_volume
+      @vol = pool.find_volume_by_name(name)
+    end
+  end
+end

data/lib/virt.rb

@@ -0,0 +1,23 @@
+require 'virt/util'
+require 'virt/connection'
+require 'virt/host'
+require 'virt/guest'
+require 'virt/pool'
+require 'virt/volume'
+require 'virt/interface'
+module Virt
+
+  class << self
+
+    def connect uri
+      @connection = Virt::Connection.new uri
+    end
+
+    def connection
+      return @connection if @connection and !@connection.closed?
+      raise "No Connection or connection has been closed"
+    end
+
+  end
+
+end

data/templates/guest.xml.erb

@@ -0,0 +1,54 @@
+<domain type='kvm'>
+  <name><%= name %></name>
+  <%- if uuid -%>
+  <uuid><%= uuid %></uuid>
+  <%- end -%>
+  <memory><%= memory %></memory>
+  <currentMemory><%= memory %></currentMemory>
+  <vcpu><%= vcpu %></vcpu>
+  <os>
+    <type arch='<%= arch %>'>hvm</type>
+    <boot dev='network'/>
+    <%- if volume -%>
+    <boot dev='hd'/>
+    <%- end -%>
+  </os>
+  <features>
+    <acpi/>
+    <apic/>
+    <pae/>
+  </features>
+  <clock offset='utc'/>
+  <on_poweroff>destroy</on_poweroff>
+  <on_reboot>restart</on_reboot>
+  <on_crash>restart</on_crash>
+  <devices>
+    <%- if volume -%>
+    <disk type='file' device='disk'>
+      <driver name='qemu' type='raw'/>
+      <source file='<%= volume.path %>'/>
+      <target dev='vda' bus='virtio'/>
+    </disk>
+    <%- end -%>
+    <%- if interface -%>
+    <interface type='<%= interface.type %>'>
+      <%- if interface.mac -%>
+      <mac address='<%= interface.mac %>'/>
+      <%- end -%>
+      <source <%= interface.type %>='<%= interface.device %>'/>
+      <model type='<%= interface.model %>'/>
+    </interface>
+    <%- end -%>
+    <serial type='pty'>
+      <target port='0'/>
+    </serial>
+    <console type='pty'>
+      <target port='0'/>
+    </console>
+    <input type='mouse' bus='ps2'/>
+    <graphics type='vnc' port='-1' autoport='yes' keymap='en-us'/>
+    <video>
+      <model type='cirrus' vram='9216' heads='1'/>
+    </video>
+  </devices>
+</domain>

data/templates/volume.xml.erb

@@ -0,0 +1,8 @@
+<volume>
+  <name><%= name %></name>
+  <allocation><%= allocated_size %></allocation>
+  <capacity unit="G"><%= size %></capacity>
+  <target>
+    <path><%= path %></path>
+  </target>
+</volume>

data/test/connection_test.rb

@@ -0,0 +1,24 @@
+require 'test/test_helper'
+
+class Virt::ConnectionTest < Test::Unit::TestCase
+
+  def setup
+    hostname = "h01.sat.lab"
+    uri = "qemu+ssh://root@#{hostname}/system"
+    @conn = Virt.connect uri
+  end
+
+  def test_should_be_able_to_connect
+    assert !@conn.closed?
+  end
+
+  def test_should_be_able_to_disconnect
+    @conn.disconnect
+    assert @conn.closed?
+  end
+
+  def test_should_return_a_version
+    assert @conn.version
+  end
+
+end

data/test/guest_test.rb

@@ -0,0 +1,40 @@
+require 'test/test_helper'
+
+class Virt::GuestTest < Test::Unit::TestCase
+
+  def setup
+    hostname = "h01.sat.lab"
+    uri = "qemu+ssh://root@#{hostname}/system"
+    Virt.connect(uri)
+    @guest = Virt::Guest.new({:name => "test-host-#{Time.now.to_i}"})
+  end
+
+  def test_should_be_new
+    assert @guest.new?
+    assert @guest.interface.new?
+    assert_nil @guest.interface.mac
+  end
+
+  def test_should_be_able_to_save
+    assert @guest.save
+    assert !@guest.interface.new?
+    assert_not_nil @guest.interface.mac
+    @guest.destroy
+  end
+
+  def test_should_be_able_to_destroy
+    assert @guest.save
+    assert @guest.destroy
+  end
+
+  def test_should_be_able_to_save_and_start
+    @guest = Virt::Guest.new({:name => "test-host-#{Time.now.to_i}", :device => "br180"})
+    assert @guest.volume.save
+    assert @guest.save
+    assert @guest.start
+    assert @guest.stop
+    assert @guest.volume.destroy
+    assert @guest.destroy
+  end
+
+end