virtual_box 0.0.1 → 0.1.0

data/lib/virtual_box/dhcp.rb

@@ -0,0 +1,149 @@
+module VirtualBox
+
+# Specification for a virtual DHCP server.
+class Dhcp
+  # The name of the VirtualBox network served by this DHCP server.
+  #
+  # This name must match the name of a host-only or internal network that is
+  # registered with VirtualBox.
+  # @return [String]
+  attr_accessor :net_name
+  
+  # This DHCP server's IP address on the virtual network that it serves.
+  # @return [String]
+  attr_accessor :ip
+  
+  # The network mask reported by this DHCP server.
+  # @return [String]
+  attr_accessor :netmask
+  
+  # The first IP address in this DHCP server's address pool.
+  # @return [String]
+  attr_accessor :start_ip
+
+  # The last IP address in this DHCP server's address pool.
+  # @return [String]
+  attr_accessor :end_ip
+
+  undef :ip
+  def ip
+    @ip ||= self.class.ip_btos((self.class.ip_stob(start_ip) &
+                                self.class.ip_stob(netmask)) + 1)
+  end
+
+  undef :netmask
+  def netmask
+    @netmask ||= '255.255.255.0'
+  end
+
+  undef :start_ip
+  def start_ip
+    @start_ip ||= self.class.ip_btos(self.class.ip_stob(ip) + 1)
+  end
+
+  undef :end_ip
+  def end_ip
+    nm = self.class.ip_stob(netmask)
+    @end_ip ||= self.class.ip_btos((self.class.ip_stob(start_ip) & nm) +
+                                   ~nm - 1)
+  end
+
+  # Creates a DHCP server specification based on the given attributes.
+  #
+  # The DHCP server is not automatically added to VirtualBox.
+  # @param [Hash<Symbol, Object>] options ActiveRecord-style initial values for
+  #     attributes; can be used together with Net#to_hash to save and restore
+  def initialize(options = {})
+    options.each { |k, v| self.send :"#{k}=", v }
+  end
+  
+  # Hash capturing this specification. Can be passed to Dhcp#new.
+  #
+  # @return [Hash<Symbol, Object>] Ruby-friendly Hash that can be used to
+  #                                re-create this DHCP server specification
+  def to_hash
+    { :net_name => 'net_name', :ip => ip, :netmask => netmask,
+      :start_ip => start_ip, :end_ip => end_ip }
+  end
+  
+  # True if this DHCP rule has been registered with VirtualBox.
+  def live?
+    servers = self.class.all
+    dhcp = servers.find { |server| server.net_name == net_name }
+    dhcp ? true : false
+  end
+  
+  # Adds this DHCP server to VirtualBox.
+  #
+  # @return [VirtualBox::Dhcp] self, for easy call chaining
+  def add
+    remove if live?
+    
+    result = VirtualBox.run_command ['VBoxManage', 'dhcpserver', 'add',
+        '--netname', net_name, '--ip', ip, '--netmask', netmask,
+        '--lowerip', start_ip, '--upperip', end_ip, '--enable']
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    self
+  end
+  
+  # Removes this DHCP server from VirtualBox.
+  #
+  # @return [VirtualBox::Dhcp] self, for easy call chaining
+  def remove
+    VirtualBox.run_command ['VBoxManage', 'dhcpserver', 'remove', '--netname',
+                            net_name]
+    self
+  end
+  
+  # The DHCP servers added to with VirtualBox.
+  #
+  # @return [Array<VirtualBox::Dhcp>] all the DHCP servers added to VirtualBox
+  def self.all
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'list', '--long',
+                                     'dhcpservers']
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    result.output.split("\n\n").
+                  map { |dhcp_info| new.from_dhcp_info(dhcp_info) }
+  end
+  
+  # Parses information about a DHCP server returned by VirtualBox.
+  #
+  # The parsed information is used to replace this network's specification.
+  # @param [String] dhcp_info output from "VBoxManage list --long dhcpservers"
+  #                           for one server
+  # @return [VirtualBox::Dhcp] self, for easy call chaining
+  def from_dhcp_info(dhcp_info)
+    info = Hash[dhcp_info.split("\n").map { |line|
+      line.split(':', 2).map(&:strip)
+    }]
+
+    self.net_name = info['NetworkName']
+    self.ip = info['IP']
+    self.netmask = info['NetworkMask']
+    self.start_ip = info['lowerIPAddress']
+    self.end_ip = info['upperIPAddress']
+    self
+  end
+  
+  # Converts an IP number into a string.
+  #
+  # @param [Integer] ip_number a 32-bit big-endian number holding an IP address
+  # @return [String] the IP address, encoded using the dot (.) notation
+  def self.ip_btos(ip_number)
+    [ip_number].pack('N').unpack('C*').join('.')
+  end
+  
+  # Converts an IP string into a number.
+  #
+  # @param [String] ip_string an IP address using the dot (.) notation
+  # @return [Integer] the IP adddres, encoded as a 32-bit big-endian number
+  def self.ip_stob(ip_string)
+    ip_string.split('.').map(&:to_i).pack('C*').unpack('N').first
+  end
+end  # class VirtualBox::Dhcp
+
+end  # namespace VirtualBox

data/lib/virtual_box/disk.rb

@@ -0,0 +1,138 @@
+module VirtualBox
+
+# Descriptor for a VirtualBox hard-disk or DVD image.
+class Disk
+  # Path to the file storing this disk image.
+  #
+  # @return [String]
+  attr_accessor :file
+  
+  # The format of this disk image.
+  #
+  # The recognized formats are :raw, :vdi, :vmdk, and :vhd.
+  # @return [Symbol]
+  attr_accessor :format
+  
+  # The type of media that the image represents.
+  #
+  # The recognized types are :disk and :dvd.
+  # @return [Symbol]
+  attr_accessor :media
+  
+  undef :format
+  def format
+    @format ||= self.class.guess_image_format file
+  end
+
+  undef :media
+  def media
+    @media ||= self.class.guess_media_type file
+  end
+  
+  # Creates an image descriptor with the given attributes.
+  #
+  # @param [Hash<Symbol, Object>] options ActiveRecord-style initial values for
+  #     attributes; can be used together with Disk#to_hash to save and restore
+  def initialize(options)
+    options.each { |k, v| self.send :"#{k}=", v }
+    self.file = File.expand_path file
+  end
+
+  # Attaches this disk to a virtual machine.
+  #
+  # @param [VirtualBox::Vm] vm the VM that this image will be attached to
+  # @param [VirtualBox::IoBus] io_bus the IO controller that this disk will be
+  #                                   attached to
+  # @param [Integer] port the IO bus port this disk will be connected to
+  # @param [Integer] device number indicating the device's ordering on its port
+  # @return [VirtualBox::Disk] self, for easy call chaining
+  def add_to(vm, io_bus, port, device)
+    media_arg = case media
+    when :disk
+      'hdd'
+    when :dvd
+      'dvddrive'
+    end
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'storageattach',
+        vm.uid, '--storagectl', io_bus.name, '--port', port.to_s,
+        '--device', device.to_s, '--type', media_arg, '--medium', file]
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    self
+  end
+  
+  # Creates a new image descriptor based on the given attributes.
+  #
+  # @param Hash<Symbol, Object> options ActiveRecord-style initial values for
+  #     attributes; can be used together with Disk#to_hash to save and restore
+  def to_hash
+    { :file => file, :format => format, :media => media }
+  end
+  
+  # Creates a VirtualBox disk image.
+  #
+  # @param [Hash] options one or many of the options documented below
+  # @option options [String] file path to the file that will hold the disk image
+  # @option options [Integer] size the image size, in bytes
+  # @option options [Symbol] format the image format; if not provided, an
+  #     intelligent guess is made, based on the file extension
+  # @option options [Boolean] prealloc unless explicitly set to true, the image
+  #     file will grow in size as the disk's blocks are used
+  #
+  # @return [VirtualBox::Disk] a Disk describing the image that was created
+  def self.create(options)
+    path = options[:file]
+    format = options[:format] || guess_image_format(path)
+    size_mb = (options[:size] / (1024 * 1024)).to_i
+    memo = options[:memo] || 'Created with the virtual_box RubyGem'
+    variant = options[:prealloc] ? 'Fixed' : 'Standard'
+    
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'createhd',
+        '--filename', path, '--size', size_mb.to_s, '--format', format.to_s,
+        '--variant', variant]
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    
+    Disk.new :file => path, :format => format, :media => :disk
+  end
+  
+  # Disk image format based on the extension in the file name.
+  def self.guess_image_format(image_file)
+    parts = File.basename(image_file).split('.')
+    if parts.length >= 2
+      case parts.last
+      when 'vdi'
+        :vdi
+      when 'vmdk'
+        :vmdk
+      when 'vhd'
+        :vhd
+      when 'iso'
+        :raw
+      else
+        :vdi
+      end
+    else
+      :vdi
+    end
+  end
+  
+  # Disk media type on the extension in the file name.
+  def self.guess_media_type(image_file)
+    parts = File.basename(image_file).split('.')
+    if parts.length >= 2
+      case parts.last
+      when 'iso'
+        :dvd
+      else
+        :disk
+      end
+    else
+      :disk
+    end
+  end
+end  # class VirtualBox::Disk
+
+end  # namespace VirtualBox

data/lib/virtual_box/io_bus.rb

@@ -0,0 +1,261 @@
+module VirtualBox
+
+# Specification for a IO controller attached to a virtual machine.
+class IoBus
+  # A user-friendly name for the I/O controller.
+  #
+  # I/O controller names must be unique within the scope of a virtual machine.
+  # VirtualBox uses "IDE Controller" and "SATA Controller" as default names.
+  # @return [String]
+  attr_accessor :name
+  
+  # The kind of bus used by this controller.
+  #
+  # The following bus types are recognized: :ide, :sata, :sas, :scsi, :floppy.
+  # @return [Symbol]
+  attr_accessor :bus
+  
+  # The chipset simulated by the IO controller
+  #
+  # The following chipsets are recogniezd:
+  # IDE :: :piix3, :piix4, and :ich6
+  # SATA :: :ahci (Intel AHCI)
+  # SCSI :: :lsi_logic and :bus_logic
+  # SAS :: lsi_logic_sas
+  # Floppy :: :i82078
+  # @return [Symbol]
+  attr_accessor :chip
+  
+  # True if the VM BIOS considers this controller bootable.
+  # @return [Boolean]
+  attr_accessor :bootable
+  
+  # True if the controller's I/O bypasses the host OS cache.
+  # @return [Boolean]
+  attr_accessor :no_cache
+  
+  # The maximum number of I/O devices supported by this controller.
+  # @return [Integer]
+  attr_accessor :max_ports
+  
+  # The disks connected to this controller's bus.
+  # @return [Hash<Array<Integer>, VirtualBox::Disk>]
+  attr_accessor :disks
+  
+  undef :name
+  def name
+    @name ||= case bus
+    when :ide, :sata, :scsi, :sas
+      "#{bus.upcase} Controller"
+    when :floppy
+      'Floppy Controller'
+    end
+  end 
+  
+  undef :no_cache
+  def no_cache
+    @no_cache.nil? ? false : @bootable
+  end
+
+  undef :bootable
+  def bootable
+    @bootable.nil? ? true : @bootable
+  end
+  
+  undef :chip
+  def chip
+    @chip ||= case @bus
+    when :ide
+      :piix4
+    when :sata
+      :ahci
+    when :scsi
+      :lsi_logic
+    when :sas
+      :lsi_logic_sas
+    when :floppy
+      :i82078
+    end
+  end
+  
+  undef :bus
+  def bus
+    @bus ||= case @chip
+    when :piix3, :piix4, :ich6
+      :ide
+    when :ahci
+      :sata
+    when :lsi_logic, :bus_logic
+      :scsi
+    when :lsi_logic_sas
+      :sas
+    when :i82078
+      :floppy
+    end
+  end
+  
+  undef :max_ports
+  def max_ports
+    @max_ports ||= case bus
+    when :sata
+      30
+    when :sas, :scsi
+      16
+    when :ide
+      2
+    when :floppy
+      1
+    end
+  end
+  
+  undef :disks=
+  def disks=(new_disks)
+    @disks = {}
+    new_disks.each do |disk|
+      if disk.kind_of? VirtualBox::Disk
+        @disks[[first_free_port, 0]] = disk
+      else
+        options = disk.dup
+        port = options.delete(:port) || first_free_port
+        device = options.delete(:device) || 0
+        @disks[[port, device]] = VirtualBox::Disk.new options
+      end
+    end
+    new_disks
+  end
+  
+  # Parses "VBoxManage showvminfo --machinereadable" output into this instance.
+  #
+  # @return [VirtualBox::IoBus] self, for easy call chaining
+  def from_params(params, bus_id)
+    self.name = params["storagecontrollername#{bus_id}"]
+    self.bootable = params["storagecontrollerbootable#{bus_id}"] == 'on'
+    self.max_ports = params["storagecontrollermaxportcount#{bus_id}"].to_i
+    case params["storagecontrollertype#{bus_id}"]
+    when 'PIIX3'
+      self.chip = :piix3
+    when 'PIIX4'
+      self.chip = :piix4
+    when 'ICH6'
+      self.chip = :ich6      
+    when 'IntelAhci'
+      self.chip = :ahci
+    when 'LsiLogic'
+      self.chip = :lsi_logic
+    when 'BusLogic'
+      self.chip = :bus_logic
+    when 'LSILogicSAS'
+      self.chip = :lsi_logic_sas
+    when 'I82078'
+      self.chip = :i82078
+    end
+    self.no_cache = nil
+    
+    image_re = /\A#{name}-(\d+)-(\d+)\Z/
+    @disks = {}
+    params.each do |key, value|
+      next unless match = image_re.match(key)
+      next if value == 'none'
+      port, device = match[1].to_i, match[2].to_i
+      @disks[[port, device]] = VirtualBox::Disk.new :file => value
+    end
+    self
+  end
+  
+  # Parameters for "VBoxManage storagectl" to add this IO bus to a VM.
+  #
+  # @return [Array<String>] the parameters for a "VBoxManage storagectl" command
+  #     that get this IO bus added to a VM.
+  def to_params
+    params = []
+    params.push '--name', name
+    params.push '--add', bus.to_s
+    params.push '--controller', case chip
+    when :piix3, :piix4, :ich6, :i82078
+      chip.to_s.upcase
+    when :ahci
+      'IntelAhci'
+    when :lsi_logic
+      'LsiLogic'
+    when :bus_logic
+      'BusLogic'
+    when :lsi_logic_sas
+      'LSILogicSAS'
+    end
+    params.push '--sataportcount', max_ports.to_s
+    params.push '--hostiocache', (no_cache ? 'off' : 'on')
+    params.push '--bootable', (bootable ? 'on' : 'off')
+  end
+  
+
+  # Adds this IO bus and all its disks to a virtual machine.
+  #
+  # @param [VirtualBox::Vm] vm the virtual machine that this IO controller will
+  #                            be added to
+  # @return [VirtualBox::IoBus] self, for easy call chaining
+  def add_to(vm)
+    add_bus_to vm
+    disks.each do |port_device, disk|
+      disk.add_to vm, self, port_device.first, port_device.last
+    end
+    self
+  end
+  
+  # Removes this IO bus from a virtual machine.
+  #
+  # @param [VirtualBox::Vm] vm the virtual machine that this IO controller will
+  #                            be removed from
+  # @return [VirtualBox::IoBus] self, for easy call chaining
+  def remove_from(vm)
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'storagectl',
+                                     vm.uuid, '--name', name, '--remove']
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    self
+  end
+
+  # Adds this IO bus to a virtual machine.
+  #
+  # @param [VirtualBox::Vm] vm the virtual machine that this IO bus will be
+  #                            added to
+  # @return [VirtualBox::IoBus] self, for easy call chaining
+  def add_bus_to(vm)
+    command = ['VBoxManage', '--nologo', 'storagectl', vm.uid].concat to_params
+    result = VirtualBox.run_command command
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    self
+  end
+  
+  # Creates a new IO controller specification based on the given attributes.
+  #
+  # @param [Hash<Symbol, Object>] options ActiveRecord-style initial values for
+  #     attributes; can be used together with IoBus#to_hash to save and restore
+  def initialize(options = {})
+    @disks = {}
+    options.each { |k, v| self.send :"#{k}=", v }
+  end
+  
+  # Hash capturing this specification. Can be passed to IoBus#new.
+  #
+  # @return [Hash<Symbol, Object>] Ruby-friendly Hash that can be used to
+  #                                re-create this IO controller specification
+  def to_hash
+    disk_hashes = disks.map do |port_device, disk|
+      disk.to_hash.merge! :port => port_device.first,
+                          :device => port_device.last
+    end
+    { :name => name, :bus => bus, :chip => chip, :bootable => bootable,
+      :no_cache => no_cache, :max_ports => max_ports, :disks => disk_hashes }
+  end
+
+  # Finds an unused port on this IO controller's bus.
+  # @return [Integer] a port number that a new disk can be attached to
+  def first_free_port
+    disks.empty? ? 0 : disks.keys.min.first + 1
+  end
+end  # class VirtualBox::IoBus
+
+end  # namespace VirtualBox

data/lib/virtual_box/net.rb

@@ -0,0 +1,144 @@
+module VirtualBox
+
+# Descriptor for a virtual network managed by Virtual Box.
+class Net 
+  # The IP address received by the host computer on this virtual network.
+  # @return [String]
+  attr_accessor :ip
+  
+  # The network mask received by the host computer on this virtual network.
+  # @return [String]
+  attr_accessor :netmask
+
+  # The name of the host's virtual NIC that's connected to this network.
+  #
+  # VirtualBox's CLI does not provide a way to set the NIC name. Therefore, this
+  # attribute is read-only, and it is automatically set when the network is
+  # registered with VirtualBox.
+  # @return [String]
+  attr_reader :if_name
+
+  # The name of the VirtualBox internal network.
+  #
+  # VirtualBox's CLI does not provide a way to set the internal network name.
+  # Therefore, this attribute is read-only, and it is automatically set when the
+  # network is registered with VirtualBox.
+  # @return [String]
+  attr_reader :name
+  
+  # The MAC address of the host's virtual NIC that's connected to this network.
+  #
+  # VirtualBox's CLI does not provide a way to set the MAC. Therefore, this
+  # attribute is read-only, and it is automatically set when the network is
+  # registered with VirtualBox.
+  # @return [String]
+  attr_reader :mac
+  
+  # Creates a virtual network specification rule based on the given attributes.
+  #
+  # The network is not automatically added to VirtualBox.
+  # @param [Hash<Symbol, Object>] options ActiveRecord-style initial values for
+  #     attributes; can be used together with Net#to_hash to save and restore
+  def initialize(options = {})
+    options.each { |k, v| self.send :"#{k}=", v }
+  end
+
+  # Hash capturing this specification. Can be passed to Net#new.
+  #
+  # @return [Hash<Symbol, Object>] Ruby-friendly Hash that can be used to
+  #                                re-create this virtual network specification
+  def to_hash
+    { :ip => ip, :netmask => netmask }
+  end
+  
+  # True if this virtual network has been added to VirtualBox.
+  # @return [Boolean] true if this network exists, false otherwise
+  def live?
+    networks = self.class.all
+    network = networks.find { |net| net.if_name == if_name }
+    network ? true : false
+  end
+  
+  # Adds this virtual network specification to VirtualBox.
+  #
+  # @return [VirtualBox::Net] self, for easy call chaining
+  def add
+    unless if_name.nil?
+      raise "Virtual network already added to VirtualBox"
+    end
+    
+    # Create the network and pull its name.
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'hostonlyif',
+        'create']
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    unless match = /^interface\s+'(.*)'\s+.*created/i.match(result.output)
+      raise "VirtualBox output does not include interface name"
+    end
+    @if_name = match[1]
+    
+    # Now list all the networks to pull the rest of the information.
+    networks = self.class.all
+    network = networks.find { |net| net.if_name == if_name }
+    @name = network.name
+    @mac = network.mac
+    
+    if (ip && ip != network.ip) || (netmask && netmask != network.netmask)
+      result = VirtualBox.run_command ['VBoxManage', '--nologo', 'hostonlyif',
+          'ipconfig', if_name, '--ip', ip, '--netmask', netmask]
+      if result.status != 0
+        raise 'Unexpected error code returned by VirtualBox'
+      end
+    else
+      self.ip = network.ip
+      self.netmask = network.netmask
+    end
+    
+    self
+  end
+  
+  # Removes this virtual network from VirtualBox's database.
+  #
+  # @return [VirtualBox::Net] self, for easy call chaining
+  def remove
+    unless if_name.nil?
+      VirtualBox.run_command ['VBoxManage', 'hostonlyif', 'remove', if_name]
+    end
+    self
+  end
+  
+  # The DHCP servers added to with VirtualBox.
+  #
+  # @return [Array<VirtualBox::Dhcp>] all the DHCP servers added to VirtualBox
+  def self.all
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'list', '--long',
+                                     'hostonlyifs']
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    result.output.split("\n\n").
+                  map { |net_info| new.from_net_info(net_info) }
+  end
+  
+  # Parses information about a DHCP server returned by VirtualBox.
+  #
+  # The parsed information is used to replace this network's specification.
+  # @param [String] net_info output from "VBoxManage list --long hostonlyifs"
+  #                          for one network
+  # @return [VirtualBox::Net] self, for easy call chaining
+  def from_net_info(net_info)
+    info = Hash[net_info.split("\n").map { |line|
+      line.split(':', 2).map(&:strip)
+    }]
+    
+    @if_name = info['Name']
+    @name = info['VBoxNetworkName']
+    @mac = info['HardwareAddress'].upcase.gsub(/[^0-9A-F]/, '')
+    self.ip = info['IPAddress']
+    self.netmask = info['NetworkMask']
+    self
+  end
+end  # class VirtualBox::Dhcp
+
+end  # namespace VirtualBox