libvirt 0.1.0

data/lib/libvirt/spec/device/disk.rb

@@ -0,0 +1,58 @@
+module Libvirt
+  module Spec
+    module Device
+      # Any device that looks like a disk, be it a floppy, harddisk,
+      # cdrom, or paravirtualized driver is specified via the disk
+      # element.
+      class Disk
+        attr_accessor :type
+        attr_accessor :source
+        attr_accessor :target_dev
+        attr_accessor :target_bus
+        attr_accessor :driver
+        attr_accessor :driver_type
+        attr_accessor :driver_cache
+        attr_accessor :shareable
+        attr_accessor :serial
+
+        # Initialize a new disk element with the given type. Examples
+        # of valid `type`s are "disk," "floppy," and "cdrom."
+        def initialize(type)
+          @type = type
+          @shareable = false
+        end
+
+        # Returns the XML representation of this device.
+        def to_xml(xml=Nokogiri::XML::Builder.new)
+          xml.disk(:type => type) do |d|
+            if source
+              # Source tag, the attribute depends on the type.
+              attribute = type == :block ? :dev : :file
+              d.source(attribute => source)
+            end
+
+            if target_dev
+              # Target tag has optional "bus" parameter
+              options = { :dev => target_dev }
+              options[:bus] = target_bus if target_bus
+              d.target(options)
+            end
+
+            if driver
+              # Driver tag has a couple optional parameters
+              options = { :name => driver }
+              options[:type] = driver_type if driver_type
+              options[:cache] = driver_cache if driver_cache
+              d.driver(options)
+            end
+
+            d.shareable if shareable
+            d.serial serial if serial
+          end
+
+          xml.to_xml
+        end
+      end
+    end
+  end
+end

data/lib/libvirt/spec/device/emulator.rb

@@ -0,0 +1,23 @@
+module Libvirt
+  module Spec
+    module Device
+      class Emulator
+        attr_accessor :path
+
+        # Initialize an emulator device with the given path. The capabilities
+        # XML from {Connection} describes what emulators are available.
+        def initialize(path)
+          @path = path
+        end
+
+        # Returns the XML for this device.
+        #
+        # @return [String]
+        def to_xml(xml=Nokogiri::XML::Builder.new)
+          xml.emulator path
+          xml.to_xml
+        end
+      end
+    end
+  end
+end

data/lib/libvirt/spec/device.rb

@@ -0,0 +1,8 @@
+module Libvirt
+  module Spec
+    module Device
+      autoload :Disk, 'libvirt/spec/device/disk'
+      autoload :Emulator, 'libvirt/spec/device/emulator'
+    end
+  end
+end

data/lib/libvirt/spec/domain/os_booting.rb

@@ -0,0 +1,69 @@
+module Libvirt
+  module Spec
+    class Domain
+      # The OS booting section of a domain specification indicates to libvirt
+      # how to configure the virtual machine to boot. There are three main ways
+      # to configure booting. Each hypervisor supports one or more of the following:
+      #
+      # 1. BIOS bootloader
+      # 2. Host bootloader
+      # 3. Direct kernel boot
+      #
+      # TODO: Host bootloader and direct kernel bootloader options.
+      class OSBooting
+        attr_accessor :type
+        attr_accessor :arch
+        attr_accessor :loader # Part of the BIOS bootloader
+        attr_accessor :boot
+        attr_accessor :bootmenu_enabled
+
+        # Host bootloader configuration options
+        attr_accessor :bootloader
+        attr_accessor :bootloader_args
+
+        # Direct kernel boot
+        attr_accessor :kernel
+        attr_accessor :initrd
+        attr_accessor :cmdline
+
+        def initialize
+          @boot = []
+        end
+
+        # Enables or disables the interactive boot menu prompt on guest startup.
+        def bootmenu_enabled=(value)
+          # Force a boolean value
+          @bootmenu_enabled = !!value
+        end
+
+        # Convert just the OS booting section to its XML representation.
+        def to_xml(parent=Nokogiri::XML::Builder.new)
+          parent.os do |os|
+            # Build the arguments for the OS booting type
+            type_args = [type]
+            type_args << { :arch => arch } if arch
+
+            # Setup the specification
+            os.type_ *type_args
+            os.loader loader if loader
+            os.bootmenu(:enable => bootmenu_enabled ? 'yes' : 'no') if !bootmenu_enabled.nil?
+
+            # Boot order for BIOS booting
+            boot.each { |dev| os.boot :dev => dev } if boot.is_a?(Array)
+
+            # Host bootloader configuration options
+            os.bootloader bootloader if bootloader
+            os.bootloader_args bootloader_args if bootloader_args
+
+            # Direct kernel boot options
+            os.kernel kernel if kernel
+            os.initrd initrd if initrd
+            os.cmdline cmdline if cmdline
+          end
+
+          parent.to_xml
+        end
+      end
+    end
+  end
+end

data/lib/libvirt/spec/domain.rb

@@ -0,0 +1,71 @@
+require 'libvirt/spec/domain/os_booting'
+
+module Libvirt
+  module Spec
+    # A specification of a domain. This translates directly down to XML
+    # which can be used to define and launch domains on a node by libvirt.
+    #
+    # **Note:** This class may only be temporary, and the functionality
+    # may be merged back into {Domain}. Also, the interface will likely
+    # change.
+    class Domain
+      attr_accessor :hypervisor
+      attr_accessor :name
+      attr_accessor :uuid
+      attr_accessor :description
+      attr_accessor :os
+      attr_accessor :memory
+      attr_accessor :current_memory
+      attr_accessor :vcpu
+
+      attr_accessor :on_poweroff
+      attr_accessor :on_reboot
+      attr_accessor :on_crash
+
+      attr_accessor :devices
+
+      def initialize
+        @os = OSBooting.new
+        @devices = []
+      end
+
+      # Returns the XML for this specification. This XML may be passed
+      # into libvirt to create a domain. This is actually the method which
+      # should be used for validation of this XML, since libvirt has
+      # great validation built in. If you define a domain and an error occurs,
+      # then it will notify you what is missing or wrong with the specification.
+      #
+      # @return [String]
+      def to_xml
+        Nokogiri::XML::Builder.new do |xml|
+          xml.domain(:type => hypervisor) do
+            # Name and description
+            xml.name name if name
+            xml.uuid uuid if uuid
+            xml.description description if description
+
+            # Operating system boot information
+            os.to_xml(xml)
+
+            # Basic resources
+            xml.memory memory if memory
+            xml.currentMemory current_memory if current_memory
+            xml.vcpu vcpu if vcpu
+
+            # Lifecycle control
+            xml.on_poweroff on_poweroff if on_poweroff
+            xml.on_reboot on_reboot if on_reboot
+            xml.on_crash on_crash if on_crash
+
+            # Devices
+            if !devices.empty?
+              xml.devices do
+                devices.map { |d| d.to_xml(xml) }
+              end
+            end
+          end
+        end.to_xml
+      end
+    end
+  end
+end

data/lib/libvirt/spec.rb

@@ -0,0 +1,12 @@
+module Libvirt
+  # This is the namespace which contains all the classes which define
+  # specifications for domains, networks, storage pools, etc. These
+  # specifications are used to define and launch them via libvirt.
+  # The specifications are converted down to XML for consumption by
+  # libvirt. Please view the example files for examples on how to use
+  # the specs.
+  module Spec
+    autoload :Device, 'libvirt/spec/device'
+    autoload :Domain, 'libvirt/spec/domain'
+  end
+end

data/lib/libvirt/storage_pool.rb

@@ -0,0 +1,164 @@
+module Libvirt
+  # Represents a single storage pool.
+  class StoragePool
+    # Initializes a new {StoragePool} object given a `virStoragePoolPtr`.
+    # Do not call this directly. Instead, use the {Connection#storage_pools}
+    # object to retrieve a specific {StoragePool}.
+    def initialize(pointer)
+      @pointer = pointer
+      ObjectSpace.define_finalizer(self, method(:finalize))
+    end
+
+    # Returns the connection of this storage pool.
+    #
+    # @return [Connection]
+    def connection
+      Connection.new(FFI::Libvirt.virStoragePoolGetConnect(self))
+    end
+
+    # Returns the name of the network as a string.
+    #
+    # @return [String]
+    def name
+      FFI::Libvirt.virStoragePoolGetName(self)
+    end
+
+    # Returns the UUID of the storage pool as a string.
+    #
+    # @return [String]
+    def uuid
+      output_ptr = FFI::MemoryPointer.new(:char, 36)
+      FFI::Libvirt.virStoragePoolGetUUIDString(self, output_ptr)
+      output_ptr.read_string
+    end
+
+    # Returns the XML description of this storage pool.
+    #
+    # @return [String]
+    def xml
+      FFI::Libvirt.virStoragePoolGetXMLDesc(self, 0)
+    end
+
+    # Deterine if the storage pool is active or not.
+    #
+    # @return [Boolean]
+    def active?
+      FFI::Libvirt.virStoragePoolIsActive(self) == 1
+    end
+
+    # Determine if the storage pool is persistent or not.
+    #
+    # @return [Boolean]
+    def persistent?
+      FFI::Libvirt.virStoragePoolIsPersistent(self) == 1
+    end
+
+    # Build the underlying storage pool.
+    #
+    # @return [Boolean]
+    def build
+      FFI::Libvirt.virStoragePoolBuild(self, 0) == 0
+    end
+
+    # Starts an inactive storage pool.
+    #
+    # @return [Boolean]
+    def create
+      return true if active?
+      FFI::Libvirt.virStoragePoolCreate(self, 0) == 0
+    end
+    alias :start :create
+
+    # Delete the underlying pool resources. This is a non-recoverable
+    # operation. This won't undefine the pool.
+    #
+    # @return [Boolean]
+    def delete(type=nil)
+      type ||= :normal
+      FFI::Libvirt.virStoragePoolDelete(self, type) == 0
+    end
+
+    # Stops an active storage pool.
+    #
+    # @return [Boolean]
+    def destroy
+      FFI::Libvirt.virStoragePoolDestroy(self) == 0
+    end
+    alias :stop :destroy
+
+    # Undefines the storage pool. This requires that the storage pool be
+    # inactive. This won't delete the underlying resources of the storage pool,
+    # however. Run {#delete} for that.
+    #
+    # @return [Boolean]
+    def undefine
+      FFI::Libvirt.virStoragePoolUndefine(self) == 0
+    end
+
+    # Returns the state of the storage pool as a symbol.
+    #
+    # @return [Symbol]
+    def state
+      info[:state]
+    end
+
+    # Returns the capacity in bytes.
+    #
+    # @return [Fixnum]
+    def capacity
+      info[:capacity]
+    end
+
+    # Returns the current allocation in bytes.
+    #
+    # @return [Fixnum]
+    def allocation
+      info[:allocation]
+    end
+
+    # Returns the available free space in bytes.
+    #
+    # @return [Fixnum]
+    def available
+      info[:available]
+    end
+
+    # Returns the volumes associated with this storage pool.
+    #
+    # @return [Collection::StorageVolumeCollection]
+    def volumes
+      Collection::StorageVolumeCollection.new(self)
+    end
+
+    # Provide a meaningful equality check for two storage pools by comparing
+    # UUID.
+    #
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(StoragePool) && other.uuid == uuid
+    end
+
+    # Returns the actual `virStoragePoolPtr` underlying this structure.
+    #
+    # @return [FFI::Pointer]
+    def to_ptr
+      @pointer
+    end
+
+    protected
+
+    # Gets the virStoragePoolInfo structure for this storage pool.
+    #
+    # @return [Hash]
+    def info
+      result = FFI::Libvirt::StoragePoolInfo.new
+      FFI::Libvirt.virStoragePoolGetInfo(self, result.to_ptr)
+      result
+    end
+
+    # Frees the underlying memory associated with this object.
+    def finalize(*args)
+      FFI::Libvirt.virStoragePoolFree(self)
+    end
+  end
+end

data/lib/libvirt/storage_volume.rb

@@ -0,0 +1,109 @@
+module Libvirt
+  # Represents a single storage volume.
+  class StorageVolume
+    # Initializes a new {StorageVolume} object given a `virStorageVolPtr`.
+    # Do not call this directly. Instead, use the {StoragePool#volumes} collection
+    # object to retrieve a specific {StorageVolume}.
+    def initialize(pointer)
+      @pointer = pointer
+      ObjectSpace.define_finalizer(self, method(:finalize))
+    end
+
+    # Returns a key for this storage volume. The key is a unique identifier.
+    #
+    # @return [String]
+    def key
+      FFI::Libvirt.virStorageVolGetKey(self)
+    end
+    alias :uuid :key
+
+    # Returns the name of this storage volume.
+    #
+    # @return [String]
+    def name
+      FFI::Libvirt.virStorageVolGetName(self)
+    end
+
+    # Returns the path of this storage volume.
+    #
+    # @return [String]
+    def path
+      FFI::Libvirt.virStorageVolGetPath(self)
+    end
+
+    # Returns the type of this storage volume.
+    #
+    # @return [Symbol]
+    def type
+      info[:type]
+    end
+
+    # Returns the capacity of this volume in bytes.
+    #
+    # @return [Integer]
+    def capacity
+      info[:capacity]
+    end
+
+    # Returns the currently allocated number of bytes.
+    #
+    # @return [Integer]
+    def allocation
+      info[:allocation]
+    end
+
+    # Wipe the contents of a volume so it is not readable in the future.
+    #
+    # @return [Boolean]
+    def wipe
+      FFI::Libvirt.virStorageVolWipe(self, 0) == 0
+    end
+
+    # Delete the storage volume rom the pool.
+    #
+    # @return [Boolean]
+    def delete
+      FFI::Libvirt.virStorageVolDelete(self, 0) == 0
+    end
+
+    # Returns the XML description of this storage volume.
+    #
+    # @return [String]
+    def xml
+      FFI::Libvirt.virStorageVolGetXMLDesc(self, 0)
+    end
+
+    # Returns the actual `virStorageVolPtr` underlying this structure.
+    #
+    # @return [FFI::Pointer]
+    def to_ptr
+      @pointer
+    end
+
+    # Provide a meaningful equality check so that two storage volumes
+    # can eaisly be checked for equality.
+    #
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(StorageVolume) && other.uuid == uuid
+    end
+
+    protected
+
+    # Returns the {FFI::Libvirt::StorageVolumeInfo} object for this volume.
+    # The various fields of the info struct are accessible via other getters.
+    #
+    # @return [FFI::Libvirt::StorageVolumeInfo]
+    def info
+      result = FFI::Libvirt::StorageVolumeInfo.new
+      FFI::Libvirt.virStorageVolGetInfo(self, result.to_ptr)
+      result
+    end
+
+    # Release the resources underlying this storage volume. This is called
+    # automatically when this volume is garbage collected.
+    def finalize(*args)
+      FFI::Libvirt.virStorageVolFree(self)
+    end
+  end
+end

data/lib/libvirt/version.rb

@@ -0,0 +1,3 @@
+module Libvirt
+  VERSION = "0.1.0"
+end

data/lib/libvirt.rb

@@ -0,0 +1,53 @@
+require 'nokogiri'
+require 'ffi/libvirt'
+
+# This module is the namespace for the higher level library on top of
+# libvirt, in typicaly Ruby library style. In contrast with {FFI::Libvirt}
+# which is a direct layer on top of FFI, this namespace abstracts much of
+# the manual work away (especially pointer handling) and exposes aspects
+# of the API through nice Ruby objects.
+#
+# Due to the nature of this side of the project, there may be certain features
+# not readily available which are supported by the API. If this is the case,
+# you can use the {FFI::Libvirt} library alongside this side.
+module Libvirt
+  autoload :Collection, 'libvirt/collection'
+  autoload :Connection, 'libvirt/connection'
+  autoload :Domain, 'libvirt/domain'
+  autoload :Error, 'libvirt/error'
+  autoload :Exception, 'libvirt/exception'
+  autoload :Network, 'libvirt/network'
+  autoload :Node, 'libvirt/node'
+  autoload :NodeDevice, 'libvirt/node_device'
+  autoload :Spec, 'libvirt/spec'
+  autoload :StoragePool, 'libvirt/storage_pool'
+  autoload :StorageVolume, 'libvirt/storage_volume'
+
+  # Initializes the library by calling `virInitialize`. Most methods
+  # in libvirt actually call this themselves, so its not strictly
+  # necessary. However, it is good practice and is **highly** recommended
+  # that this is called at a same place in a multi-threaded environment.
+  def self.initialize!
+    FFI::Libvirt.virInitialize == 0
+  end
+
+  # Returns the version of `libvirt` on the client machine. **This is
+  # not the version of the `libvirt` ruby library.** The result is
+  # return as an array of `[major, minor, patch]`.
+  #
+  # @return [Array]
+  def self.version
+    FFI::Libvirt.version
+  end
+
+  # Connect to a hypervisor using libvirt. This is a shortcut to
+  # instantiating a {Connection} object, therefore for documentation on
+  # the arguments and return value for this method, please consult
+  # {Connection#initialize}.
+  def self.connect(*args)
+    Connection.new(*args)
+  end
+end
+
+# Disable the stderr output which libvirt defaults to.
+Libvirt::Error.on_error

data/libvirt.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "libvirt/version"
+
+Gem::Specification.new do |s|
+  s.name        = "libvirt"
+  s.version     = Libvirt::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Mitchell Hashimoto"]
+  s.email       = ["mitchell.hashimoto@gmail.com"]
+  s.homepage    = "http://rubygems.org/gems/libvirt"
+  s.summary     = "A ruby client library providing the raw interface to libvirt via FFI."
+  s.description = "A ruby client library providing the raw interface to libvirt via FFI."
+
+  s.rubyforge_project = "libvirt"
+
+  s.add_dependency "ffi", "~> 0.6.3"
+  s.add_dependency "nokogiri", "~> 1.4.3"
+
+  s.add_development_dependency "protest", "~> 0.4.0"
+  s.add_development_dependency "mocha", "~> 0.9.8"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/test/libvirt/collection/abstract_collection_test.rb

@@ -0,0 +1,14 @@
+require "test_helper"
+
+Protest.describe("abstract collection") do
+  setup do
+    @klass = Libvirt::Collection::AbstractCollection
+
+    @connection = mock("connection")
+    @instance = @klass.new(@connection)
+  end
+
+  should "have interface be available as an attribute" do
+    assert_equal @connection, @instance.interface
+  end
+end