virtual_box 0.0.1 → 0.1.0

data/lib/virtual_box/nic.rb

@@ -0,0 +1,213 @@
+require 'securerandom'
+
+module VirtualBox
+
+# Configuration for a network card.
+class Nic
+  # The kind of network emulation implemented on this card.
+  #
+  # Can be one of the following values:
+  # :nat:: uses VirtualBox internal NAT engine to hide under host OS
+  # :bridged:: bypasses host OS, connects directly to a network interface
+  # :host:: virtual network connecting guest to host
+  # :virtual:: virtual network connecting multiple guests
+  # @return [Symbol]
+  attr_accessor :mode
+  
+  # The NIC controller chip.
+  #
+  # Can be one of the following values:
+  # :amd:: AMD PCNet FAST III (good default)
+  # :intel:: Intel PRO/1000 MT Server (for newer Windows systems)
+  # :intel_xp:: Intel PRO/1000 MT Server (for Windows XP)
+  # :virtio:: fake card optimized for virtualization (custom drivers needed)
+  # @return [Symbol]
+  attr_accessor :chip
+  
+  # Name of the virtual network that the NIC is connected to.
+  #
+  # The identifier differs depending on the networking mode:
+  # :nat:: not applicable
+  # :bridged:: name of the bridge network interface on the host
+  # :host:: name of the host-only network interface
+  # :virtual:: virtual network name
+  # @return [Symbol]
+  attr_accessor :net_name
+  
+  # MAC address for the network card, as a hexadecimal string.
+  #
+  # The format for specifying MACs is '0123456789AB'. A random MAC will be
+  # generated if one is not assigned. 
+  # @return [String]
+  attr_accessor :mac
+  
+  # Path to a file that logs a network trace for the VM.
+  #
+  # Can be null to disable tracing.
+  # @return [String]
+  attr_accessor :trace_file
+    
+  undef :mode
+  def mode
+    @mode ||= :nat
+  end
+
+  undef :chip
+  def chip
+    @chip ||= (:mode == :virtual) ? :virtual : :amd
+  end
+  
+  undef :mac
+  def mac
+    return @mac if @mac
+    @mac = SecureRandom.hex(6).upcase
+    @mac[1] = 'A'  # Set the OUI bits to unicast and globally unique
+    @mac
+  end
+  undef :mac=
+  def mac=(new_mac)
+    @mac = new_mac && new_mac.upcase.gsub(/[^0-9A-F]/, '')
+  end
+  
+  # Creates a NIC with the given attributes.
+  #
+  # @param [Hash<Symbol, Object>] options ActiveRecord-style initial values for
+  #     attributes; can be used together with Nic#to_hash to save and restore
+  def initialize(options = {})
+    options.each { |k, v| self.send :"#{k}=", v }
+  end  
+   
+  # Arguments to "VBoxManage modifyvm" describing the NIC.
+  #
+  # @param [Number] nic_id the number of the card (1-4) connected to the host
+  # @return [Array<String>] arguments that can be concatenated to a "VBoxManage
+  #     modifyvm" command to express this NIC specification
+  def to_params(nic_id)
+    params = []
+        
+    params.push "--nic#{nic_id}"
+    case mode
+    when :nat
+      params.push 'nat'
+    when :bridged
+      params.push 'bridged', "--bridgeadapter#{nic_id}", net_name
+    when :virtual
+      params.push 'intnet', "--intnet#{nic_id}", net_name
+    when :host
+      params.push 'hostonly', "--hostonlyadapter#{nic_id}", net_name
+    else
+      params.push 'null'
+    end
+    
+    params.push "--nictype#{nic_id}", case chip
+    when :amd
+      'Am79C973'
+    when :intel
+      '82545EM'
+    when :intel_xp
+      '82543GC'
+    when :virtual
+      'virtio'
+    end      
+    
+    params.push "--cableconnected#{nic_id}", 'on'    
+    params.push "--macaddress#{nic_id}", mac if mac
+    
+    params.push "--nictrace#{nic_id}"
+    if trace_file
+      params.push 'on', "--nictracefile#{nic_id}", trace_file
+    else
+      params.push 'off'
+    end
+    
+    params
+  end
+  
+  # Parses "VBoxManage showvminfo --machinereadable" output into this instance.
+  #
+  # @param [Hash<String, String>] params the "VBoxManage showvminfo" output,
+  #                                      parsed by Vm.parse_machine_readble
+  # @param [Integer] nic_id the NIC's number in the VM
+  # @return [VirtualBox::Nic] self, for easy call chaining
+  def from_params(params, nic_id)
+    case params["nic#{nic_id}"]
+    when 'nat'
+      self.mode = :nat
+    when 'bridged'
+      self.mode = :bridged
+      self.net_name = params["bridgeadapter#{nic_id}"]
+    when 'intnet'
+      self.mode = :virtual
+      self.net_name = params["intnet#{nic_id}"]
+    when 'hostonly'
+      self.mode = :host
+      self.net_name = params["hostonlyadapter#{nic_id}"]    
+    end
+    
+    self.chip = case params["nictype#{nic_id}"]
+    when 'Am79C970A', 'Am79C973',
+      :amd
+    when '82543GC'
+      :intel_xp
+    when '82540OEM', '82545EM'
+      :intel
+    when 'virtio'
+      :virtual
+    else
+      (self.mode == :virtual) ? :virtual : :amd
+    end
+    
+    self.mac = params["macaddress#{nic_id}"]
+    if params["nictrace#{nic_id}"] == 'on'
+      self.trace_file = params["nictracefile#{nic_id}"]
+    else
+      self.trace_file = nil
+    end
+   
+    self
+  end
+  
+  # Hash capturing this specification. Can be passed to Nic#new.
+  #
+  # @return [Hash<Symbol, Object>] Ruby-friendly Hash that can be used to
+  #                                re-create this NIC specification
+  def to_hash
+    { :mode => mode, :chip => chip, :net_name => net_name, :mac => mac,
+      :trace_file => trace_file }
+  end
+  
+  # Information about the NICs attached to the computer.
+  #
+  # @return [Array<Hash<Symbol, Object>>] an array with one hash per NIC; hashes
+  #     have the following keys:
+  #     :id:: the inteface id (use when setting a Nic's net_id)
+  #     :ip:: the IP address (check for 0.0.0.0 to see if it's live)
+  #     :mask:: the netmask
+  #     :mac:: the NICs MAC address
+  def self.host_nics
+    @host_nics ||= get_host_nics
+  end
+
+  # Queries VirtualBox for the network interfaces on the computer.
+  #
+  # @return (see .host_nics)
+  def self.get_host_nics    
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'list',
+                                     '--long', 'hostifs']
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    
+    result.output.split("\n\n").map do |nic_info|
+      i = Hash[nic_info.split("\n").map { |line|
+        line.split(':', 2).map(&:strip)
+      }]
+      {
+        :id => i['Name'], :ip => i['IPAddress'], :mask => i['NetworkMask'],
+        :mac => i['HardwareAddress'].upcase.gsub(/[^0-9A-F]/, '')
+      }
+    end
+  end
+end  # class VirtualBox::Nic
+
+end  # namespace VirtualBox

data/lib/virtual_box/version.rb

@@ -1,46 +1,59 @@
 # VirtualBox version detection. 
-#
-# Author:: Victor Costan
-# Copyright:: Copyright (C) 2009 Zergling.Net
-# License:: MIT
 
-# :nodoc: namespace
 module VirtualBox
   @version_info = nil
   
   # True if the installed VirtualBox is the open-source edition.
   #
-  # The open-source edition of VirtualBox has some limitations, such as no support
-  # for RDP and USB devices.
+  # The open-source edition of VirtualBox has some limitations, such as no
+  # support for RDP and USB devices.
   def self.ose?
-    version_info ? (version_info[:edition] == 'OSE') : nil
+    unless version.edition
+      raise 'VirtualBox is not installed on this machine.'
+    end
+    version.edition == 'OSE'
   end
   
-  # Version information about the installed VirtualBox.
+  # Version information about the VirtualBox package installed on this machine.
   #
-  # Returns:
-  #   false if VirtualBox is not installed; otherwise, a hash with the keys:
-  #       revision:: (number) the SVN revision that VirtualBox is built off of
-  #       edition:: the VirtualBox edition (nil for the personal edition, 'OSE'
-  #                 for the open-source edition)
-  #       version:: the VirtualBox version (e.g. '3.0.4')
-  def self.version_info
+  # @return [Hash<Symbol, Object>, Boolean] false if VirtualBox is not
+  #     installed; otherwise, a hash with the following keys:
+  #     :svn:: (number) the SVN revision that VirtualBox is built off of
+  #     :edition:: the VirtualBox edition ('' for the personal edition, 'OSE'
+  #                for the open-source edition)
+  #     :release:: the public release number (e.g. '3.0.4')
+  def self.version
     return @version_info unless @version_info.nil?
     
-    cmd_result = shell_command 'VBoxManage --version'
-    return @version_info = false if cmd_result[:status] != 0
+    cmd_result = run_command ['VBoxManage', '--version']
+    if cmd_result.status != 0
+      @version_info = Hashie::Mash.new
+      return @version_info
+    end
     
-    output = cmd_result[:output].strip
-    @version_info = {}
+    output = cmd_result.output.strip
+
     if revision_offset = output.rindex('r')
-      @version_info[:revision] = output[revision_offset + 1, output.length].to_i
+      revision = output[revision_offset + 1, output.length].to_i
       output.slice! revision_offset..-1
+    else
+      revision = nil
     end
+    
     if edition_offset = output.rindex('_')
-      @version_info[:edition] = output[edition_offset + 1, output.length]
+      edition = output[edition_offset + 1, output.length]
       output.slice! edition_offset..-1
+    else
+      edition = ''
     end
-    @version_info[:version] = output
-    @version_info
+    
+    @version_info = Hashie::Mash.new :release => output, :svn => revision,
+                                     :edition => edition
+  end
+  
+  # Removes the cached information on the VirtualBox package version.
+  # @return <NilObject> nil
+  def self.reset_version_info!
+    @version_info = nil
   end
 end  # namespace VirtualBox

data/lib/virtual_box/vm.rb

@@ -1,35 +1,300 @@
-# Definition for the main VM class.
-#
-# Author:: Victor Costan
-# Copyright:: Copyright (C) 2009 Zergling.Net
-# License:: MIT
-
-# :nodoc: namespace
 module VirtualBox
+
+# VirtualBox virtual machine.
+class Vm
+  # The UUID used to register this virtual machine with VirtualBox.
+  #
+  # The UUID is used to identify the VM in many VirtualBox commands. It should
+  # not be changed once the VM is registered. In fact, the UUID should not
+  # be manually assigned under normal use.
+  # @return [String]
+  attr_accessor :uid
+  
+  # A user-friendly name for this virtual machine.
+  #
+  # If not assigned, a unique name will be generated based on the VM's UUID.
+  #
+  # @return [String]
+  attr_accessor :name
+  
+  # The general VM configuration.
+  # @return [VirtualBox::Board]
+  attr_accessor :board
   
-# A VirtualBox virtual machine.
-class VM
-  include GeneralSettings
-  include Identity
-  include Lifecycle
+  # The IO controllers (and disks) connected to the VM.
+  # @return [Array<VirtualBox::IoBus>]
+  attr_accessor :io_buses
   
-  def initialize
-    reset_identity
-    reset_settings
+  # The network cards connected to this virtual machine.
+  # @return [Array<VirtualBox::Nic>]
+  attr_accessor :nics
+  
+  # If true, the VM's screen will be displayed in a GUI.
+  #
+  # This is only intended for manual testing. Many continuous integration
+  # servers cannot display the VirtualBox GUI, so this attribute should not be
+  # set to true in test suites.
+  # @return [Boolean]
+  attr_accessor :gui
+    
+  undef :uid
+  def uid
+    @uid ||= UUID.generate
+  end
+  
+  undef :name
+  def name
+    @name ||= 'rbx_' + uid.gsub('-', '')
   end
   
-  # Resets the VM's settings to their defaults.
+  undef :board=
+  def board=(new_board)
+    @board = if new_board.kind_of?(VirtualBox::Board)
+      new_board
+    else
+      VirtualBox::Board.new new_board
+    end
+  end
+
+  undef :io_buses=
+  def io_buses=(new_io_buses)
+    @io_buses = new_io_buses.map do |io_bus|
+      if io_bus.kind_of?(VirtualBox::IoBus)
+        io_bus
+      else
+        VirtualBox::IoBus.new io_bus
+      end
+    end
+  end
+  
+  undef :nics=
+  def nics=(new_nics)
+    @nics = []
+    new_nics.each do |nic|
+      if nic.kind_of?(VirtualBox::Nic) || nic.nil?
+        @nics << nic
+      else
+        options = nic.dup
+        port = options.delete(:port) || @nics.length
+        @nics[port] = VirtualBox::Nic.new options
+      end
+    end
+    new_nics
+  end
+  
+  # Creates a new virtual machine specification based on the given attributes.
   #
-  # The defaults are chosen somewhat arbitrarily by the gem's author.
-  def reset_settings
-    reset_general_settings
+  # @param [Hash<Symbol, Object>] options ActiveRecord-style initial values for
+  #     attributes; can be used together with Vm#to_hash to save and restore
+  def initialize(options = {})
+    self.board = {}
+    self.io_buses = []
+    self.nics = []
+    self.gui = false
+    options.each { |k, v| self.send :"#{k}=", v }
+  end
+  
+  # Hash capturing this specification. Can be passed to Vm#new.
+  #
+  # @return [Hash<Symbol, Object>] Ruby-friendly Hash that can be used to
+  #                                re-create this virtual machine specification
+  def to_hash
+    {
+      :name => name, :uid => uid, :gui => gui,
+      :board => board.to_hash, :io_buses => io_buses.map(&:to_hash),
+      :nics => nics.map.
+           with_index { |nic, i| nic && nic.to_hash.merge!(:port => i) }.
+           reject!(&:nil?)
+    }
+  end
+  
+  # True if this VM has been registered with VirtualBox.
+  #
+  # @return [Boolean] true for VMs that are already registered with VirtualBox
+  def registered?
+    self.class.registered_uids.include? uid
+  end
+  
+  # Registers this VM with VirtualBox.
+  #
+  # @return [VirtualBox::Vm] self, for easy call chaining
+  def register
+    unregister if registered?
+    
+    result = VirtualBox.run_command ['VBoxManage', 'createvm',
+        '--name', name, '--uuid', uid, '--register']
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    
+    begin
+      push_config
+    rescue
+      unregister
+      raise
+    end
+    
+    self
+  end
+  
+  # De-registers this VM from VirtualBox's database.
+  #
+  # @return [VirtualBox::Vm] self, for easy call chaining
+  def unregister
+    VirtualBox.run_command ['VBoxManage', 'unregistervm', uid, '--delete']
+    self
+  end
+  
+  # Starts the virtual machine.
+  #
+  # @return [VirtualBox::Vm] self, for easy call chaining
+  def start
+    register unless registered?
+    
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'startvm', uid,
+                                     '--type', gui ? 'gui' : 'headless']
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    self
+  end
+  
+  # Stops the virtual machine simulation.
+  #
+  # This is equivalent to pulling the power cord from a physical machine.
+  # @return [VirtualBox::Vm] self, for easy call chaining
+  def stop
+    control :kill
+    self
+  end
+
+  # Controls a started virtual machine.
+  #
+  # @param [Symbol] action the following actions are supported: 
+  #   :kill:: hard power-off (pulling the power cord from the machine)
+  #   :power_button:: Power button press
+  #   :nmi:: NMI (non-maskable interrupt)
+  # @return [VirtualBox::Vm] self, for easy call chaining
+  def control(action)
+    action = case action
+    when :kill
+      'poweroff'
+    when :power_button
+      'acpipowerbutton'
+    when :nmi
+      'injectnmi'
+    end
+
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'controlvm', uid,
+                                     action]
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    self
+  end
+  
+  # The UUIDs of all VMs that are registered with VirtualBox.
+  #
+  # @return [Array<String>] UUIDs for VMs that VirtualBox is aware of
+  def self.registered_uids
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'list', 'vms']
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    result.output.split("\n").map do |id_info|
+      uid_offset = id_info.rindex(?{) + 1
+      uid = id_info[uid_offset...-1]  # Exclude the closing }
+    end
   end
 
-  # Arguments to "VBoxManage modifyvm" describing the VM's settings.
-  def modifyvm_params
-    params = ''
-    params << modifyvm_general_params
+  # The UUIDs of all VirtualBox VMs that are started.
+  #
+  # @return [Array<String>] UUIDs for VMs that are running in VirtualBox
+  def self.started_uids
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'list',
+                                     'runningvms']
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    result.output.split("\n").map do |id_info|
+      uid_offset = id_info.rindex(?{) + 1
+      uid = id_info[uid_offset...-1]  # Exclude the closing }
+    end
   end
-end  # class VM
   
+  # Updates the configuration in VirtualBox to reflect this VM's configuration.
+  #
+  # @return [VirtualBox::Vm] self, for easy call chaining
+  def push_config
+    command = ['VBoxManage', 'modifyvm', uid]
+    command.concat board.to_params
+    nics.each_with_index do |nic, index|
+      if nic.nil?
+        command.push "--nic#{index + 1}", 'none'
+      else
+        command.concat nic.to_params(index + 1)
+      end
+    end
+    if VirtualBox.run_command(command).status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    
+    io_buses.each { |bus| bus.add_to self }
+     
+    self
+  end
+  
+  # Updates this VM's configuration to reflect the VirtualBox configuration.
+  #
+  # @return [VirtualBox::Vm] self, for easy call chaining
+  def pull_config
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'showvminfo',
+                                     '--machinereadable', uid]
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    
+    config = self.class.parse_machine_readable result.output
+    
+    self.name = config['name']
+    self.uid = config['UUID']
+    board.from_params config
+    
+    nic_count = config.keys.select { |key| /^nic\d+$/ =~ key }.max[3..-1].to_i
+    1.upto nic_count do |index|
+      if config["nic#{index}"] == 'none'
+        nics[index - 1] = nil
+      else
+        nics[index - 1] ||= VirtualBox::Nic.new
+        nics[index - 1].from_params config, index
+      end
+    end
+
+    bus_count = 1 + (config.keys.select { |key|
+      /^storagecontrollername\d+$/ =~ key
+    }.max || "storagecontrollername-1")[21..-1].to_i
+    0.upto bus_count - 1 do |index|
+      io_buses[index] ||= VirtualBox::IoBus.new
+      io_buses[index].from_params config, index
+    end
+    
+    self
+  end
+  
+  # Parses the output of the 'VBoxManage showvminfo --machinereadable' command.
+  #
+  # @param [String] output the command output
+  # @return [Hash<String, Object>] a Hash whose keys are the strings on the left
+  #     side of "=" on each line, and whose values are the strings on the right
+  #     side
+  def self.parse_machine_readable(output)
+    Hash[output.split("\n").map { |line|
+      key, value = *line.split('=', 2)
+      key = key[1...-1] if key[0] == ?"  # Remove string quotes ("").
+      value = value[1...-1] if value[0] == ?"  # Remove string quotes ("").
+      [key, value]
+    }]    
+  end
+end  # class VirtualBox::Vm
+
 end  # namespace VirtualBox

data/lib/virtual_box.rb

@@ -1,12 +1,17 @@
-# Main include file for the virtual_box gem.  
-#
-# Author:: Victor Costan
-# Copyright:: Copyright (C) 2009 Zergling.Net
-# License:: MIT
+# TODO(pwnall): documentation for the top-level VirtualBox module
+module VirtualBox
+  
+end
 
-require 'virtual_box/command_line.rb'
+require 'hashie/mash'
+require 'uuid'
+
+require 'virtual_box/board.rb'
+require 'virtual_box/cli.rb'
+require 'virtual_box/dhcp.rb'
+require 'virtual_box/disk.rb'
+require 'virtual_box/io_bus.rb'
+require 'virtual_box/net.rb'
+require 'virtual_box/nic.rb'
 require 'virtual_box/version.rb'
-require 'virtual_box/vm/general_settings.rb'
-require 'virtual_box/vm/identity.rb'
-require 'virtual_box/vm/lifecycle.rb'
 require 'virtual_box/vm.rb'

data/test/helper.rb

@@ -0,0 +1,24 @@
+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 'minitest/unit'
+require 'minitest/spec'
+require 'mocha'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'virtual_box'
+
+class MiniTest::Unit::TestCase
+end
+
+Dir[File.expand_path('helpers/**/*.rb', File.dirname(__FILE__))].
+    each { |h| require h }
+
+MiniTest::Unit.autorun