libvirt 0.1.0

data/lib/ffi/libvirt.rb

@@ -0,0 +1,29 @@
+require 'ffi'
+
+module FFI
+  # The FFI Libvirt module contains the raw access to the Libvirt C
+  # API. This module contains no fluff or nice abstractions above the API,
+  # and is actually a way to access the C API directly. This also means
+  # that it is up to you to manage all the pointers and so on that come
+  # with this power.
+  module Libvirt
+    extend FFI::Library
+    ffi_lib "libvirt"
+
+    autoload :Util, 'ffi/libvirt/util'
+  end
+end
+
+# The order matters here, sadly. If you muck with the ordering and
+# no exceptions are raised while running tests, you're probably okay.
+# But, still, be careful.
+require 'ffi/libvirt/types'
+require 'ffi/libvirt/version'
+require 'ffi/libvirt/functions'
+require 'ffi/libvirt/error_types'
+require 'ffi/libvirt/error_functions'
+require 'ffi/libvirt/domain_info'
+require 'ffi/libvirt/error'
+require 'ffi/libvirt/node_info'
+require 'ffi/libvirt/storage_pool_info'
+require 'ffi/libvirt/storage_volume_info'

data/lib/libvirt/collection/abstract_collection.rb

@@ -0,0 +1,49 @@
+require 'forwardable'
+
+module Libvirt
+  module Collection
+    # Abstract parent class for all collections within libvirt.
+    #
+    # Subclasses of any collection are expected to implement the function
+    # `all` which returns all results of a collection. This will automatically
+    # make the enumerability work as well as some methods such as
+    # `first` and `length`.
+    class AbstractCollection
+      include Enumerable
+      extend Forwardable
+      def_delegators :all, :first, :last, :each, :length, :[], :inspect, :to_s
+
+      attr_reader :interface
+
+      # Initializes a new collection. All collections belong to a parent
+      # structure in some way, which is expected to be passed in here.
+      #
+      # @param [Object] Parent object
+      def initialize(interface)
+        @interface = interface
+      end
+
+      protected
+
+      # A helper method to follow libvirt's API conventions to get the
+      # values of an array.
+      #
+      # @param [Symbol] getter Getter for the array
+      # @param [Symbol] count Method for getting the size of the array
+      # @param [Symbol] type Type of value returned
+      # @return [Array]
+      def read_array(getter, counter, type)
+        count_max = FFI::Libvirt.send(counter, interface)
+        output_ptr = FFI::MemoryPointer.new(:pointer, count_max)
+        count_returned = FFI::Libvirt.send(getter, interface, output_ptr, count_max)
+        output_ptr.send("get_array_of_#{type}", 0, count_returned)
+      end
+
+      # A helper method to wrap the resulting method call in an object
+      # if the pointer result is not null, or return nil otherwise.
+      def nil_or_object(result, klass)
+        result.null? ? nil : klass.new(result)
+      end
+    end
+  end
+end

data/lib/libvirt/collection/domain_collection.rb

@@ -0,0 +1,98 @@
+module Libvirt
+  module Collection
+    # Represents a collection of domains. This is an enumerable (in the Ruby sense)
+    # object, but it is not directly an `Array`. This collection is a special enumerable
+    # which allows you to do things such as get only the active domains, create a new
+    # domain from a specification, etc.
+    #
+    # If you enumerate the entire collection, then this is equivalent to enumerating
+    # over {#all} domains. e.g. `collection.length` is equivalent to calling
+    # `collection.all.length` (where `collection` is a `DomainCollection` object).
+    class DomainCollection < AbstractCollection
+      # Searches for a domain. This will search first by name, then by ID,
+      # then by UUID, returning a result as soon as one is found.
+      #
+      # @return [Domain]
+      def find(value)
+        result = find_by_name(value) rescue nil
+        result ||= find_by_id(value) rescue nil
+        result ||= find_by_uuid(value) rescue nil
+      end
+
+      # Searches for a domain by name.
+      #
+      # @return [Domain]
+      def find_by_name(name)
+        nil_or_object(FFI::Libvirt.virDomainLookupByName(interface, name), Domain)
+      end
+
+      # Searches for a domain by ID.
+      #
+      # @return [Domain]
+      def find_by_id(id)
+        nil_or_object(FFI::Libvirt.virDomainLookupByID(interface, id), Domain)
+      end
+
+      # Searches for a domain by UUID.
+      #
+      # @return [Domain]
+      def find_by_uuid(uuid)
+        nil_or_object(FFI::Libvirt.virDomainLookupByUUIDString(interface, uuid), Domain)
+      end
+
+      # Defines a new domain with the given valid specification. This method
+      # doesn't start the domain.
+      #
+      # @param [Object] spec
+      # @return [Domain]
+      def define(spec)
+        spec = spec.is_a?(String) ? spec : spec.to_xml
+        nil_or_object(FFI::Libvirt.virDomainDefineXML(interface, spec), Domain)
+      end
+
+      # Creates a new domain and starts it. This domain configuration is not
+      # persisted, so it may disappear after the next reboot or shutdown.
+      #
+      # @param [Object] spec
+      # @return [Domain]
+      def create(spec)
+        spec = spec.is_a?(String) ? spec : spec.to_xml
+        nil_or_object(FFI::Libvirt.virDomainCreateXML(interface, spec, 0), Domain)
+      end
+
+      # Returns all the active (running) domains for the connection which this
+      # collection belongs to.
+      #
+      # @return [Array<Domain>]
+      def active
+        # Do some pointer and array fiddling to extract the ids of the active
+        # domains from the libvirt API
+        ids = read_array(:virConnectListDomains, :virConnectNumOfDomains, :int)
+
+        # Lookup all the IDs and make them proper Domain objects
+        ids.collect { |id| find_by_id(id) }
+      end
+
+      # Returns all the inactive (not running) domains for the connection
+      # which this collection belongs to.
+      #
+      # @return [Array<Domain>]
+      def inactive
+        # Do some pointer and array fiddling to extract the names of the active
+        # domains from the libvirt API
+        ids = read_array(:virConnectListDefinedDomains, :virConnectNumOfDefinedDomains, :string)
+
+        # Lookup all the names and make them proper Domain objects
+        ids.collect { |id| find_by_name(id) }
+      end
+
+      # Returns all domains (active and inactive) for the connection this collection
+      # belongs to.
+      #
+      # @return [Array<Domain>]
+      def all
+        active + inactive
+      end
+    end
+  end
+end

data/lib/libvirt/collection/interface_collection.rb

@@ -0,0 +1,16 @@
+module Libvirt
+  module Collection
+    # Represents a collection of interfaces. This is an enumerable (in the
+    # Ruby sense) object, but it is not directly an `Array`.
+    class InterfaceCollection < AbstractCollection
+      # Returns all the active interfaces for the connection which this
+      # collection belongs to.
+      #
+      # @return [Array<Interface>]
+      def active
+        # TODO: Doesn't work on mac :) must dev on linux
+        # read_array(:virConnectListInterfaces, :virConnectNumOfInterfaces, :string)
+      end
+    end
+  end
+end

data/lib/libvirt/collection/network_collection.rb

@@ -0,0 +1,58 @@
+module Libvirt
+  module Collection
+    # Represents a collection of networks. This is an enumerable (in the
+    # Ruby sense) object, but it is not directly an `Array`.
+    class NetworkCollection < AbstractCollection
+      # Searches for a network. This will first search by name, then
+      # by UUID.
+      #
+      # @return [Network]
+      def find(value)
+        result = find_by_name(value) rescue nil
+        result ||= find_by_uuid(value) rescue nil
+      end
+
+      # Searches for a network by name.
+      #
+      # @return [Network]
+      def find_by_name(name)
+        nil_or_object(FFI::Libvirt.virNetworkLookupByName(interface, name), Network)
+      end
+
+      # Searches for a network by UUID.
+      #
+      # @return [Network]
+      def find_by_uuid(uuid)
+        nil_or_object(FFI::Libvirt.virNetworkLookupByUUIDString(interface, uuid), Network)
+      end
+
+      # Returns all the active networks for the connection which this
+      # collection belongs to.
+      #
+      # @return [Array<Network>]
+      def active
+        read_array(:virConnectListNetworks, :virConnectNumOfNetworks, :string).collect do |name|
+          find_by_name(name)
+        end
+      end
+
+      # Returns all the inactive networks for the connection which this
+      # collection belongs to.
+      #
+      # @return [Array<Network>]
+      def inactive
+        read_array(:virConnectListDefinedNetworks, :virConnectNumOfDefinedNetworks, :string).collect do |name|
+          find_by_name(name)
+        end
+      end
+
+      # Returns all networks (active and inactive) for the connection this
+      # collection belongs to.
+      #
+      # @return [Array<Netowrk>]
+      def all
+        active + inactive
+      end
+    end
+  end
+end

data/lib/libvirt/collection/node_device_collection.rb

@@ -0,0 +1,29 @@
+module Libvirt
+  module Collection
+    # Represents a collection of devices on a given node. Retrieve
+    # this collection using {Node#devices}.
+    class NodeDeviceCollection < AbstractCollection
+      # Create a node device on the host system.
+      #
+      # @return [NodeDevice]
+      def create(spec)
+        nil_or_object(FFI::Libvirt.virNodeDeviceCreateXML(interface, spec, 0), NodeDevice)
+      end
+
+      # Returns all of the node devices for the given connection.
+      #
+      # @return [Array<NodeDevice>]
+      def all
+        # We can't use the `read_array` helper here due to the methods being
+        # a bit different.
+        count_max = FFI::Libvirt.virNodeNumOfDevices(interface, nil, 0)
+        output_ptr = FFI::MemoryPointer.new(:pointer, count_max)
+        count_returned = FFI::Libvirt.virNodeListDevices(interface, nil, output_ptr, count_max, 0)
+
+        output_ptr.get_array_of_string(0, count_returned).collect do |name|
+          nil_or_object(FFI::Libvirt.virNodeDeviceLookupByName(interface, name), NodeDevice)
+        end
+      end
+    end
+  end
+end

data/lib/libvirt/collection/nwfilter_collection.rb

@@ -0,0 +1,15 @@
+module Libvirt
+  module Collection
+    # Represents a collection of network filters.
+    class NWFilterCollection < AbstractCollection
+      # Returns all network filters.
+      #
+      # @return [Array<NWFilter>]
+      def all
+        read_array(:virConnectListNWFilters, :virConnectNumOfNWFilters, :string).each do |name|
+          # TODO
+        end
+      end
+    end
+  end
+end

data/lib/libvirt/collection/storage_pool_collection.rb

@@ -0,0 +1,58 @@
+module Libvirt
+  module Collection
+    # Represents a collection of storage pools.
+    class StoragePoolCollection < AbstractCollection
+      # Search for a storage pool. This will first search by name and
+      # then by UUID, returning the first result returned.
+      #
+      # @return [StoragePool]
+      def find(value)
+        result = find_by_name(value) rescue nil
+        result ||= find_by_uuid(value) rescue nil
+      end
+
+      # Search for a storage pool by name.
+      #
+      # @return [StoragePool]
+      def find_by_name(name)
+        nil_or_object(FFI::Libvirt.virStoragePoolLookupByName(interface, name), StoragePool)
+      end
+
+      # Search for a storage pool by UUID.
+      #
+      # @return [StoragePool]
+      def find_by_uuid(uuid)
+        nil_or_object(FFI::Libvirt.virStoragePoolLookupByUUIDString(interface, uuid), StoragePool)
+      end
+
+      # Returns the inactive storage pools.
+      #
+      # @return [Array<StoragePool>]
+      def inactive
+        read_array(:virConnectListDefinedStoragePools, :virConnectNumOfDefinedStoragePools, :string).collect do |name|
+          find_by_name(name)
+        end
+      end
+
+      # Returns the active storage pools.
+      #
+      # @return [Array<StoragePool>]
+      def active
+        read_array(:virConnectListStoragePools, :virConnectNumOfStoragePools, :string).collect do |name|
+          find_by_name(name)
+        end
+      end
+
+      # Returns all storage pools.
+      #
+      # @return [Array<StoragePool>]
+      def all
+        inactive + active
+      rescue Exception::LibvirtError
+        # If inactive isn't supported, then we just return the active
+        # storage pools.
+        active
+      end
+    end
+  end
+end

data/lib/libvirt/collection/storage_volume_collection.rb

@@ -0,0 +1,57 @@
+module Libvirt
+  module Collection
+    # Represents a collection of storage volumes, which belongs to a
+    # storage pool.
+    class StorageVolumeCollection < AbstractCollection
+      # Searches for a storage volume. This will search by name, then by
+      # key, then finally by path. If no storage volume is found, nil will
+      # be returned.
+      #
+      # @return [StorageVolume]
+      def find(value)
+        result = find_by_name(value) rescue nil
+        result ||= find_by_key(value) rescue nil
+        result ||= find_by_path(value) rescue nil
+      end
+
+      # Searches for a storage volume by name.
+      #
+      # @return [StorageVolume]
+      def find_by_name(name)
+        nil_or_object(FFI::Libvirt.virStorageVolLookupByName(interface, name), StorageVolume)
+      end
+
+      # Searches for a storage volume by key.
+      #
+      # @return [StorageVolume]
+      def find_by_key(key)
+        nil_or_object(FFI::Libvirt.virStorageVolLookupByKey(interface.connection, key), StorageVolume)
+      end
+
+      # Searches for a storage volume by path.
+      #
+      # @return [StorageVolume]
+      def find_by_path(path)
+        nil_or_object(FFI::Libvirt.virStorageVolLookupByPath(interface.connection, path), StorageVolume)
+      end
+
+      # Creates a new storage volume from an XML specification.
+      #
+      # @return [StorageVolume]
+      def create(spec)
+        nil_or_object(FFI::Libvirt.virStorageVolCreateXML(interface, spec, 0), StorageVolume)
+      end
+
+      # Returns all storage volumes. Its unnecessary to call this directly
+      # since the {#all} array is delegated for the various `Array`-like
+      # methods.
+      #
+      # @return [Array]
+      def all
+        read_array(:virStoragePoolListVolumes, :virStoragePoolNumOfVolumes, :string).collect do |name|
+          find_by_name(name)
+        end
+      end
+    end
+  end
+end

data/lib/libvirt/collection.rb

@@ -0,0 +1,12 @@
+module Libvirt
+  module Collection
+    autoload :AbstractCollection, 'libvirt/collection/abstract_collection'
+    autoload :DomainCollection, 'libvirt/collection/domain_collection'
+    autoload :InterfaceCollection, 'libvirt/collection/interface_collection'
+    autoload :NetworkCollection, 'libvirt/collection/network_collection'
+    autoload :NodeDeviceCollection, 'libvirt/collection/node_device_collection'
+    autoload :NWFilterCollection, 'libvirt/collection/nwfilter_collection'
+    autoload :StoragePoolCollection, 'libvirt/collection/storage_pool_collection'
+    autoload :StorageVolumeCollection, 'libvirt/collection/storage_volume_collection'
+  end
+end

data/lib/libvirt/connection.rb

@@ -0,0 +1,225 @@
+module Libvirt
+  # Describes a connection to an instance of libvirt. This instance may be local
+  # or remote.
+  #
+  # # Initiating a Connection
+  #
+  # ## Basic
+  #
+  # A basic example of initiating a connection is to just allow the libvirt client
+  # library to choose the best (first available) hypervisor for you. If you're only
+  # running one hypervisor or you're not sure what is available on your machine,
+  # then this is the easiest option to get started:
+  #
+  #     conn = Libvirt::Connection.new
+  #
+  # A shortcut is also provided for your convenience:
+  #
+  #     conn = Libvirt.connect
+  #
+  # ## Specifying a URI
+  #
+  # Libvirt connections are made by giving a URI to libvirt, which can describe
+  # a local or remote libvirt instance (remote being that `libvirtd` is running).
+  # The following is an example of a local VirtualBox connection:
+  #
+  #     conn = Libvirt::Connection.new("vbox:///session")
+  #
+  # And perhaps a remote qemu connection:
+  #
+  #     conn = Libvirt::Connection.new("qemu+tcp://10.0.0.1/system")
+  #
+  # # Readonly Connections
+  #
+  # A readonly connection can be made by specifying the `readonly` option to be
+  # truthy. A couple examples follow:
+  #
+  #     conn = Libvirt::Connection.new("vbox:///session", :readonly => true)
+  #     conn = Libvirt::Connection.new(:readonly => true)
+  #
+  # # Basic Information of a Connection
+  #
+  # Once you have a connection object, you can gather basic information about it
+  # by using methods such as {#name}, {#capabilities}, etc.:
+  #
+  #     puts "Hypervisor type: #{conn.hypervisor}"
+  #     puts "Hypervisor version: #{conn.hypervisor_verison}"
+  #     puts "Library version: #{conn.lib_version}"
+  #
+  class Connection
+    # Opens a new connection to libvirt. This connection may be local or remote.
+    # If a `uri` is given, an attempt to connect to the given URI is made. The URI
+    # can be used to specify the location of libvirt along with the hypervisor
+    # to connect to.
+    #
+    # @param [String] uri
+    def initialize(*args)
+      opts = args.last.is_a?(Hash) ? args.pop : {}
+      uri = args.first
+
+      if args.first.is_a?(FFI::Pointer)
+        # Store away the pointer and increase the reference count, since
+        # we're taking ownership of this pointer directly.
+        @pointer = args.first
+        FFI::Libvirt.virConnectRef(self)
+      end
+
+      # If the pointer is not yet set, attempt to open a connection with
+      # the specified URI.
+      @pointer ||= if opts[:readonly]
+        FFI::Libvirt.virConnectOpenReadOnly(uri)
+      else
+        FFI::Libvirt.virConnectOpen(uri)
+      end
+
+      ObjectSpace.define_finalizer(self, method(:finalize))
+    end
+
+    # Returns the domains (both active and inactive) related to this
+    # connection. The various states of the domains returned can be
+    # queried using {Domain#state}.
+    #
+    # @return [Collection::DomainCollection]
+    def domains
+      Collection::DomainCollection.new(self)
+    end
+
+    # Returns the interfaces (both active and inactive) related to this
+    # connection.
+    #
+    # @return [Collection::InterfaceCollection]
+    def interfaces
+      Collection::InterfaceCollection.new(self)
+    end
+
+    # Returns the networks related to this connection.
+    #
+    # @return [Collection::NetworkCollection]
+    def networks
+      Collection::NetworkCollection.new(self)
+    end
+
+    # Returns the network filters related to this connection.
+    #
+    # @return [Collection::NWFilterCollection]
+    def nwfilters
+      Collection::NWFilterCollection.new(self)
+    end
+
+    # Returns the storage pools related to this connection
+    #
+    # @return [Collection::StoragePoolCollection]
+    def storage_pools
+      Collection::StoragePoolCollection.new(self)
+    end
+
+    # Returns a node object to retrieve information about the node which
+    # this connection is established to.
+    #
+    # @return [Node]
+    def node
+      Node.new(self)
+    end
+
+    # Returns the capabilities of the connected hypervisor/driver. Returns them
+    # as an XML string. This method calls `virConnectGetCapabilities`. This will
+    # probably be parsed into a more useful format in the future.
+    #
+    # @return [String]
+    def capabilities
+      FFI::Libvirt.virConnectGetCapabilities(self)
+    end
+
+    # Returns the system hostname on which the hypervisor is running. Therefore,
+    # if connected to a remote `libvirtd` daemon, then it will return the hostname
+    # of that machine.
+    #
+    # @return [String]
+    def hostname
+      FFI::Libvirt.virConnectGetHostname(self)
+    end
+
+    # Returns the URI of the connection.
+    #
+    # @return [String]
+    def uri
+      FFI::Libvirt.virConnectGetURI(self)
+    end
+
+    # Returns the name of the hypervisor. This is named "type" since that is the
+    # terminology which libvirt itself uses. This is also aliased as `hypervisor`
+    # since that is more friendly.
+    #
+    # @return [String]
+    def type
+      FFI::Libvirt.virConnectGetType(self)
+    end
+    alias :hypervisor :type
+
+    # Returns the maximum number of virtual CPUs for a given domain type.
+    #
+    # @return [Integer]
+    def max_virtual_cpus(type)
+      FFI::Libvirt.virConnectGetMaxVcpus(self, type)
+    end
+
+    # Returns a boolean of whether the connection is encrypted or not.
+    #
+    # @return [Boolean]
+    def encrypted?
+      result = FFI::Libvirt.virConnectIsEncrypted(self)
+      return nil if result == -1
+      result == 1
+    end
+
+    # Returns a boolean of whether the connection is secure or not.
+    #
+    # @return [Boolean]
+    def secure?
+      result = FFI::Libvirt.virConnectIsSecure(self)
+      return nil if result == -1
+      result == 1
+    end
+
+    # Returns the version of the hypervisor. This version is returned as an array
+    # representation as `[major, minor, patch]`.
+    #
+    # @return [Array]
+    def hypervisor_version
+      output_ptr = FFI::MemoryPointer.new(:ulong)
+      FFI::Libvirt.virConnectGetVersion(self, output_ptr)
+      FFI::Libvirt::Util.parse_version_number(output_ptr.get_ulong(0))
+    end
+
+    # Returns the version of `libvirt` which the daemon on the other side is
+    # running. If not connected to a remote daemon, it will return the version
+    # of libvirt on this machine. The result is an array representatin of the
+    # version, as `[major, minor, patch]`.
+    #
+    # @return [Array]
+    def lib_version
+      output_ptr = FFI::MemoryPointer.new(:ulong)
+      FFI::Libvirt.virConnectGetLibVersion(self, output_ptr)
+      FFI::Libvirt::Util.parse_version_number(output_ptr.get_ulong(0))
+    end
+
+    # Provides the pointer of the connection. This allows this object to be
+    # used directly with the FFI layer, as if this object were actually
+    # a `virConnectPtr`.
+    #
+    # @return [FFI::Pointer]
+    def to_ptr
+      @pointer
+    end
+
+    protected
+
+    # Cleans up the connection by releasing the connection object. This
+    # never needs to be called directly since there is a finalizer on
+    # this object to clean the connection. Therefore, to close the connection,
+    # simply release the reference to the connection.
+    def finalize(*args)
+      FFI::Libvirt.virConnectClose(self) rescue nil
+    end
+  end
+end