libvirt 0.1.0

data/.gitignore

@@ -0,0 +1,10 @@
+pkg/*
+*.gem
+.bundle
+.yardoc
+doc/
+test.rb
+test.c
+
+# Rubinius
+*.rbc

data/.yardopts

@@ -0,0 +1,3 @@
+-m markdown
+--files
+docs/user_guide.md

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0 (November 16, 2010)
+
+  - Initial release

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in libvirt.gemspec
+gemspec
+
+group :development do
+  # Not JRuby, which doesn't like bluecloth
+  platforms :ruby, :mri do
+    gem "yard", "~> 0.6.1"
+    gem "bluecloth", "~> 2.0.9"
+  end
+end

data/Gemfile.lock

@@ -0,0 +1,36 @@
+PATH
+  remote: .
+  specs:
+    libvirt (0.1.0)
+      ffi (~> 0.6.3)
+      nokogiri (~> 1.4.3)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    bluecloth (2.0.9)
+    ffi (0.6.3)
+      rake (>= 0.8.7)
+    ffi (0.6.3-java)
+    mocha (0.9.8)
+      rake
+    nokogiri (1.4.3.1)
+    nokogiri (1.4.3.1-java)
+      weakling (>= 0.0.3)
+    protest (0.4.1)
+    rake (0.8.7)
+    weakling (0.0.4-java)
+    yard (0.6.1)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  bluecloth (~> 2.0.9)
+  ffi (~> 0.6.3)
+  libvirt!
+  mocha (~> 0.9.8)
+  nokogiri (~> 1.4.3)
+  protest (~> 0.4.0)
+  yard (~> 0.6.1)

data/README.md

@@ -0,0 +1,83 @@
+# Libvirt Ruby Library
+
+* Source: [http://github.com/mitchellh/libvirt-rb](http://github.com/mitchellh/libvirt-rb)
+* IRC: `#vagrant` on Freenode
+* Issues: [http://github.com/mitchellh/libvirt-rb/issues](http://github.com/mitchellh/libvirt-rb/issues)
+
+A ruby client library providing the raw interface to libvirt via
+FFI. The library is backwards compatible to libvirt 0.6.0. The
+library consists of two namespaces:
+
+* `Libvirt` - All objects under this namespace provide a very Ruby-like
+  object oriented interface above the raw libvirt API. This is the recommended
+  way of using libvirt with Ruby. These objects are mostly compatible with
+  the FFI layer as well (you may pass in a `Connection` object in place of
+  a `virConnectPtr` for example).
+* `FFI::Libvirt` - A direct interface to the libvirt API using FFI. This is
+  for the power players out there who need extremely customized functionality,
+  with the tradeoff being that it is more complicated to use and you must manage
+  your own pointers.
+
+## Project Status
+
+**Functional beta.** The project has been initially released with complete
+FFI coverage and extensive coverage with the nicer Ruby objects. More
+functionality will constantly be developed. If you'd like to see a specific
+feature come first, please open an [issue](http://github.com/mitchellh/libvirt-rb/issues).
+
+## Installation
+
+This library will be a gem. First, you need to install libvirt, using
+your OS's respective package manager. On OS X the recommended way is
+using [homebrew](http://github.com/mxcl/homebrew):
+
+    brew install libvirt
+
+After installing libvirt, install the gem:
+
+    gem install libvirt
+
+If you'd like to try the bleeding edge version of libvirt-rb, we try
+to keep master pretty stable and you're welcome to give it a shot. To
+do this just clone out the repository and run this from the working
+directory:
+
+    rake install
+
+## Usage
+
+For detailed usage and examples, please view the documentation. But
+a small example is shown below so you can get a feel for how the library
+is meant to be used:
+
+    require 'libvirt'
+
+    conn = Libvirt.connect
+
+    # Output some basic information
+    puts "You are connected to: #{cxn.hypervisor}"
+    puts "Hypervisor version: #{cxn.hypervisor_version}"
+    puts "Libvirt version: #{cxn.lib_version}"
+
+    # Output the names of all the domains
+    conn.domains.each do |domain|
+      puts "Domain: #{domain.name}"
+    end
+
+    # Start a domain and stop another
+    conn.domains[0].start
+    conn.domains[1].stop
+
+    # Create a new domain (assuming `xml` is defined somewhere)
+    # to an XML string
+    new_domain = conn.domains.create(xml)
+    puts "New domain created: #{new_domain.name}"
+
+As I said earlier, please read the full usage page in the documentation
+and also check out the examples in the `examples/` directory.
+
+## Contributing
+
+To contribute to the project, fork it and send me pull requests of any
+changes made. For more information, see the [Hacker's Guide](http://github.com/mitchellh/libvirt-rb/wiki/Hacker's-Guide)
+and the [Contributor's Guide](http://github.com/mitchellh/libvirt-rb/wiki/Contributor's-Guide).

data/Rakefile

@@ -0,0 +1,20 @@
+require 'rubygems'
+require 'bundler'
+require 'bundler/setup'
+Bundler::GemHelper.install_tasks
+
+task :default => :test
+
+desc "Run the test suite."
+task :test do
+  $:.unshift File.expand_path("../test", __FILE__)
+  files = ENV["TEST"] ? [ENV["TEST"]] : Dir["test/**/*_test.rb"]
+  files.each { |f| load f }
+end
+
+begin
+  # Documentation task
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+end

data/docs/user_guide.md

@@ -0,0 +1,259 @@
+# libvirt-rb User's Guide
+
+## Overview
+
+`libvirt-rb` is a Ruby library for [libvirt](http://libvirt.org), a library sponsored
+by RedHat for talking to various hypervisors with a single API. `libvirt-rb` is backwards
+compatible to libvirt 0.6.0 and consists of two namespaces for users to interact
+with depending on their level of comfort with the libvirt API:
+
+* `Libvirt` - All objects under this namespace provide a very Ruby-like
+  object oriented interface above the raw libvirt API. This is the recommended
+  way of using libvirt with Ruby. These objects are mostly compatible with
+  the FFI layer as well (you may pass in a `Connection` object in place of
+  a `virConnectPtr` for example).
+* `FFI::Libvirt` - A direct interface to the libvirt API using FFI. This is
+  for the power players out there who need extremely customized functionality,
+  with the tradeoff being that it is more complicated to use and you must manage
+  your own pointers.
+
+## Installation
+
+### Prerequisites
+
+Before the library itself is installed, [libvirt](http://libvirt.org) must be
+installed on the system. How to do this for various operating systems is shown
+below.
+
+#### Mac OS X
+
+On Mac OS X, [homebrew](http://github.com/mxcl/homebrew) is the recommended
+way of installing Mac OS X. There is currently not a MacPort for it.
+
+    brew install libvirt
+
+#### Linux
+
+Most linux flavors have a libvirt installation in their respective package
+managers. The libvirt library might be slightly out of date but if you
+find you need the most up-to-date libvirt, its very easy to compile by
+hand as well.
+
+    apt-get install libvirt
+
+#### Windows
+
+While libvirt supposedly compiles on Windows, this is still a work in
+progress on my part to verify the install and test the library. Hang
+in there!
+
+### Install libvirt-rb
+
+`libvirt-rb` is packaged as a RubyGem, making the installation a one-step
+process:
+
+    gem install libvirt
+
+
+## Basic Concepts and Usage
+
+This section will cover the basic concepts of the higher level portion of
+the libvirt ruby library (that is, it won't talk directly about the `FFI`
+portion, which is mentioned in a later section). This is the portion of the
+library that most people will use and is the recommended way of interacting
+with libvirt from ruby.
+
+This section _will not_ try cover how libvirt works or the various uses of
+libvirt. Libvirt itself has many pages of documentation on this which you
+should read to learn more about it.
+
+### Establishing a Connection to Libvirt
+
+The first step before anything can be done with libvirt is to establish
+a connection to either a local or remote instance of libvirt (if remote,
+you would be connecting to a `libvirtd` instance). Libvirt establishes
+connections using a URI. Each line below is another example on how to
+establish a connection:
+
+
+    conn = Libvirt.connect
+    conn = Libvirt.connect("test:///default")
+    conn = Libvirt.connect("qemu+ssh://10.0.0.1/system")
+    conn = Libvirt.connect("vbox:///system", :readonly => true)
+
+This connection is the base object used to do most other things. Libvirt
+has been made so that when you're done with the connection and it is
+garbage collected, the underlying connection data is properly freed as
+well. In fact, this is true for all objects in the libvirt library. If
+you find a memory leak with the libvirt objects, it is a bug.
+
+### Accessing Collections
+
+Libvirt objects, especially the connection, exposes a variety of
+_collection_ objects, such as domains, interfaces, networks, etc.
+These collections are all exposed in a similar way, and this section
+is meant to give a rough overview on how they work. Exact details
+for each collection can be seen by reading their respective
+documentation (such as {Libvirt::Collection::DomainCollection}).
+
+### Using and Accessing Objects in Collections
+
+All collections can be treated as `Array`-like objects. They are
+`Enumerable` and provide additional methods as well. All collections
+implement the `all` method to retrieve all of their collection.
+Some collections can be drilled down further, such as domains, with
+`inactive` and just `active`.
+
+Examples of using a collection are shown below:
+
+    # You can use a collection like an array:
+    conn.domains.include?(other)
+
+    # You can iterate over a collection:
+    conn.domains.each do |domain|
+      puts "Domain: #{domain.name}"
+    end
+
+    # You can drill down further on some collections:
+    puts "Inactive domains: #{conn.domains.inactive.length}"
+
+    # You can explicitly access all domains, though this is
+    # the same as treating the whole collection as an array:
+    puts "All domains: #{conn.domains.all.length}"
+
+Understanding these collections are fundamental to using the library,
+so play around with them and get comfortable.
+
+### Creating and Defining Objects in Collections
+
+Most collection objects support creation and definition. The difference
+in libvirt is that defining will create a persistent object that survives
+node reboots, but it will not start immediately. Creating, on the other
+hand, creates and starts the object but it won't persist after reboots,
+typically. Refer to the actual libvirt documentation for verification
+on this.
+
+Everything in libvirt is defined using XML. In the future, the libvirt-rb
+library will probably provide Ruby object wrappers around these XML
+structures but in the current version, you are expected to pass in the
+XML as a string. An example is shown below:
+
+    volume_xml = <<-XML
+    <volume>
+      <name>test</name>
+      <key>g9eba311-ea76-4e4a-ad7b-401fa81e38c8</key>
+      <source>
+      </source>
+      <capacity>8589934592</capacity>
+      <allocation>33280</allocation>
+      <target>
+        <format type='raw'/>
+        <permissions>
+          <mode>00</mode>
+          <owner>0</owner>
+          <group>0</group>
+        </permissions>
+      </target>
+    </volume>
+    XML
+
+    volume = conn.storage_pools.first.volumes.create(volume_xml)
+
+**Note:** You can also retrieve the XML for an object using the `xml`
+method which is available on most objects, such as {Libvirt::Domain#xml}.
+
+### Using Libvirt Objects
+
+Once you have retrieved a single libvirt object, such as {Libvirt::Connection Connection}
+or {Libvirt::Domain Domain}, there are common ways to access information
+and manipulate the object.
+
+All objects have attributes which are accessed using simple method
+calls, an example using a domain object below:
+
+    puts domain.name
+    puts domain.uuid
+    puts domain.xml
+    puts domain.state
+
+Additionally, there are usually methods to control the state of an
+object, and transition it to new states, such as starting or stopping
+a domain:
+
+    domain.start
+    domain.stop
+    domain.undefine
+
+These methods return a boolean `true` or `false` depending on whether
+they succeed or not.
+
+### Error Handling
+
+Libvirt itself provides a great error handling mechanism through
+callbacks. By default, libvirt-rb will raise an {Libvirt::Exception::LibvirtError}
+whenever an error occurs. That error contains a human readable
+message and an error code, as well as a backtrace as to where the error
+could have occurred. The exception simply wraps a {Libvirt::Error}
+object.
+
+If, instead of raising an exception for every error, you'd like
+custom behavior, you can set a new callback which will be called
+every time:
+
+    Libvirt::Error.on_error do |error|
+      # Do anything you want with `error`...
+    end
+
+You can also disable error callbacks alltogether by specifying no
+block:
+
+    Libvirt::Error.on_error
+
+Most methods return `nil` on error. Some methods have no reasonable
+way of representing an error (for example `nil` might just mean a
+find failed), so doing nothing is not recommended.
+
+## Advanced: Direct FFI Access
+
+For advanced users out there, there is nearly 100% FFI coverage over
+the libvirt API from the `FFI::Libvirt` namespace. This is a mostly
+flat namespace for all the API methods, with classes for the various
+structs. An example of using this API directly:
+
+    c = FFI::Libvirt.virConnectOpen("test:///default")
+    puts "Connected URI: #{FFI::Libvirt.virConnectGetURI(c)}"
+
+### Creating libvirt-rb Objects with FFI Pointers
+
+Many of the pointers returned by the FFI layer can be used to initialize
+higher level objects, allowing a smooth transition between FFI and
+libvirt-rb. An example of this is shown below:
+
+    c = FFI::Libvirt.virConnectOpen("test:///default")
+
+    # Use the pointer to create a Connection object, this is the
+    # same as doing `Libvirt.connect("test:///default")`
+    conn = Libvirt::Connection.new(c)
+
+    # We are responsible for cleaning up the pointer. Since the Connection
+    # object took ownership, this free simply decreases a reference count
+    FFI::Libvirt.virConnectFree(c)
+
+**Warning:** As you can see through the example above, you must remember
+to _ALWAYS_ free your pointers after initializing a higher level object.
+This is to ensure that memory is properly freed. Using the FFI API makes
+it very easy to leak memory, so you have been warned.
+
+### Using libvirt-rb Objects as Pointer Arguments
+
+In addition to creating libvirt-rb objects, the libvirt-rb objects can
+also be used as pointer arguments for the FFI API. This is because all
+of the objects implement the `to_ptr` method. An example is shown below:
+
+    c = Libvirt.connect("test:///default")
+    puts "URI: #{FFI::Libvirt.virConnectGetURI(c)}"
+
+**Warning:** If you store the pointer directly somewhere (assigning
+the `to_ptr` value to a variable), do not forget to increase the
+reference count by calling the respective API, since when the libvirt-rb
+objects are garbage collected, they automatically free the pointer.

data/examples/README.md

@@ -0,0 +1,10 @@
+# Libvirt Ruby Library Exmaples
+
+These examples are meant to be run within the source tree of
+libvirt, meaning you can run the without installing the libvirt
+gem beforehand. To try them out, first install the dependencies
+locally using `bundle install`, then run the examples directly
+via `ruby`. Example:
+
+    ruby print_domain_info.rb
+

data/examples/create_domain.rb

@@ -0,0 +1,46 @@
+require "rubygems"
+require "bundler/setup"
+require "libvirt"
+
+# Warning: In the current version of the libvirt-rb library, the
+# spec classes are not completely thought out and for now it is
+# recommended that full XML strings are used.
+
+spec = Libvirt::Spec::Domain.new
+
+#
+# Example of valid hypervisors
+# :kvm
+# :xen
+# :test
+#
+spec.hypervisor = :test
+spec.name = "My Test VM"
+#
+# :hvm (FullVirt in KVM anx Xen)
+# :linux (Xen PV)
+#
+spec.os.type = :hvm
+spec.memory = 123456 # KB
+
+# Connect to the test hypervisor so we don't actually create a
+# domain somewhere.
+#
+# Example of valid URIs:
+# vbox:///system (local virtualbox)
+# qemu+tcp://10.0.0.1/system (remote qemu over TCP)
+# qemu+ssh://10.0.0.1/system (remote qemu over SSH)
+# qemu+unix:///system (local qemu over unix socket)
+# xen+tcp://10.0.0.1/ (remote Xen over TCP)
+#
+# If no URI is given, libvirt does its best to guess.
+conn = Libvirt.connect("test:///default")
+
+# This creates the domain on the hypervisor without starting it.
+# The return value is the {Libvirt::Domain} object associated
+# with it.
+conn.domains.define(spec)
+
+puts "Success! A test domain was created with the following XML:"
+puts
+puts spec.to_xml

data/examples/print_domain_info.rb

@@ -0,0 +1,46 @@
+require "rubygems"
+require "bundler/setup"
+require "libvirt"
+
+#----------------------------------------------------------------------
+# Helper methods for pretty printing
+#----------------------------------------------------------------------
+def two_columns(str1, str2)
+  puts "#{str1}".ljust(40) + "#{str2}"
+end
+
+def humanize_bytes(bytes)
+  if bytes < 1048576
+    "#{bytes/1024} MB"
+  else
+    "#{bytes/1024/1024} GB"
+  end
+end
+
+# Example connecting to a node and hypervisor:
+#
+# Example of valid URIs:
+# vbox:///system (local virtualbox)
+# qemu+tcp://10.0.0.1/system (remote qemu over TCP)
+# qemu+ssh://10.0.0.1/system (remote qemu over SSH)
+# qemu+unix:///system (local qemu over unix socket)
+#
+# If no URI is given, libvirt does its best to guess.
+h = Libvirt.connect
+
+h.domains.each do |d|
+  puts "Domain: #{d.name}"
+  puts "-----------"
+  two_columns "ID:", d.id
+  two_columns "UUID:", d.uuid
+  two_columns "Memory:", humanize_bytes(d.memory)
+  two_columns "Max Mem", humanize_bytes(d.max_memory)
+  two_columns "State", d.state
+  two_columns "Virtual CPUs:", d.virtual_cpus
+  two_columns "CPU time used (nanosecs):", d.cpu_time_used
+  two_columns "Active?:", d.active? ? 'yes': 'no'
+  two_columns "Persistent?:", d.persistent? ? 'yes':'no'
+  puts
+end
+
+

data/examples/print_hypervisor_info.rb

@@ -0,0 +1,40 @@
+require "rubygems"
+require "bundler/setup"
+require "libvirt"
+
+#----------------------------------------------------------------------
+# Helper methods for pretty printing
+#----------------------------------------------------------------------
+def two_columns(str1, str2)
+  puts "#{str1}".ljust(40) + "#{str2}"
+end
+
+def humanize_bytes(bytes)
+  if bytes < 1048576
+    "#{bytes/1024} MB"
+  else
+    "#{bytes/1024/1024} GB"
+  end
+end
+
+# Example connecting to a node and hypervisor:
+#
+# Example of valid URIs:
+# vbox:///system (local virtualbox)
+# qemu+tcp://10.0.0.1/system (remote qemu over TCP)
+# qemu+ssh://10.0.0.1/system (remote qemu over SSH)
+# qemu+unix:///system (local qemu over unix socket)
+#
+# If no URI is given, libvirt does its best to guess.
+h = Libvirt.connect
+
+puts "Hypervisor INFO"
+puts "---------------"
+two_columns "Hypervisor Type:", h.type
+two_columns "Domains Created:", h.domains.size
+# outputs XML
+# puts h.capabilities
+two_columns "Hostname:", h.hostname
+two_columns "Connection URI:", h.uri
+two_columns "Hypervisor Version:", h.hypervisor_version.join('.')
+two_columns "Libvirt Version:", h.lib_version.join('.')

data/lib/ffi/libvirt/domain_info.rb

@@ -0,0 +1,12 @@
+module FFI
+  module Libvirt
+    # virDomainInfo structure, used to represent a single domain.
+    class DomainInfo < ::FFI::Struct
+      layout :state, :virDomainState,
+             :maxMem, :ulong,
+             :memory, :ulong,
+             :nrVirtCpu, :ushort,
+             :cpuTime, :ulong_long
+    end
+  end
+end

data/lib/ffi/libvirt/error.rb

@@ -0,0 +1,25 @@
+module FFI
+  module Libvirt
+    # virError structure, which is used to represent any errors raised by
+    # libvirt.
+    class Error < ::FFI::Struct
+      # Note: The "DEPRECATED" notes below are important and if you use
+      # these you should take extreme caution since the error struct doesn't
+      # properly increaes the reference count on this objects, so its likely
+      # they are no longer valid. They exist for backwards compatibility.
+
+      layout :code, :virErrorNumber,
+             :domain, :virErrorDomain,
+             :message, :string,
+             :level, :virErrorLevel,
+             :conn, :virConnectPtr, # DEPRECATED
+             :dom, :virDomainPtr, # DEPRECATED
+             :str1, :string,
+             :str2, :string,
+             :str3, :string,
+             :int1, :int,
+             :int2, :int,
+             :net, :virNetworkPtr # DEPRECATED
+    end
+  end
+end

data/lib/ffi/libvirt/error_functions.rb

@@ -0,0 +1,21 @@
+module FFI
+  module Libvirt
+    libvirt_version "0.6.0" do
+      attach_function :virGetLastError, [], :virErrorPtr
+      attach_function :virResetLastError, [], :void
+      attach_function :virResetError, [:virErrorPtr], :void
+      attach_function :virConnGetLastError, [:virConnectPtr], :virErrorPtr
+      attach_function :virConnResetLastError, [:virConnectPtr], :void
+      attach_function :virCopyLastError, [:virErrorPtr], :int
+      attach_function :virDefaultErrorFunc, [:virErrorPtr], :void
+      attach_function :virSetErrorFunc, [:void_pointer, :virErrorFunc], :void
+      attach_function :virConnSetErrorFunc, [:virConnectPtr, :void_pointer, :virErrorFunc], :void
+      attach_function :virConnCopyLastError, [:virConnectPtr, :virErrorPtr], :int
+    end
+
+    libvirt_version "0.6.1" do
+      attach_function :virSaveLastError, [], :virErrorPtr
+      attach_function :virFreeError, [:virErrorPtr], :void
+    end
+  end
+end