virtual_box 0.0.1 → 0.1.0

data/.autotest

@@ -0,0 +1,9 @@
+Autotest.add_hook :initialize do |autotest|
+  autotest.add_exception '.git'
+  autotest.add_mapping %r{lib/virtual_box/.*\.rb$} do |file, match|
+    p match
+    autotest.files_matching %r{spec/.*_spec\.rb$}
+  end
+  p autotest.mappings
+  false
+end

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.project

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>virtual_box</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+	</buildSpec>
+	<natures>
+		<nature>org.radrails.rails.core.railsnature</nature>
+	</natures>
+</projectDescription>

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,14 @@
+source :rubygems
+
+gem 'hashie', '>= 0.4.0'
+gem 'uuid', '>= 2.3.5'
+
+group :development do
+  gem 'bundler', '>= 1.1.3'
+  gem 'jeweler', '>= 1.8.3'
+  gem 'minitest', '>= 2.12.1'
+  gem 'mocha', '>= 0.11.0', :require => false
+  gem 'net-ssh', '>= 2.3.0', :require => 'net/ssh'
+  gem 'simplecov', '>= 0.6.1'
+  gem 'yard', '>= 0.7.5'
+end

data/Gemfile.lock

@@ -0,0 +1,44 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    hashie (1.2.0)
+    jeweler (1.8.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.0)
+    macaddr (1.5.0)
+      systemu (>= 2.4.0)
+    metaclass (0.0.1)
+    minitest (2.12.1)
+    mocha (0.11.3)
+      metaclass (~> 0.0.1)
+    multi_json (1.3.4)
+    net-ssh (2.3.0)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    simplecov (0.6.2)
+      multi_json (~> 1.3)
+      simplecov-html (~> 0.5.3)
+    simplecov-html (0.5.3)
+    systemu (2.5.0)
+    uuid (2.3.5)
+      macaddr (~> 1.0)
+    yard (0.8.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.1.3)
+  hashie (>= 0.4.0)
+  jeweler (>= 1.8.3)
+  minitest (>= 2.12.1)
+  mocha (>= 0.11.0)
+  net-ssh (>= 2.3.0)
+  simplecov (>= 0.6.1)
+  uuid (>= 2.3.5)
+  yard (>= 0.7.5)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Victor Costan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,67 @@
+# virtual_box
+
+This gem is a Ruby API for VirtualBox, Sun's open-source virtualization software
+that supports Linux, Mac OS X, and Windows.
+
+
+## Features
+
+Currently, the gem supports the following features:
+* VM creation and removal
+* VM start, and stop
+* Disk (VDI, VMDK, VHD) and DVD (ISO) images
+* NAT, bridged, host-only and internal networking
+* DHCP configuration for host-only and internal networks
+* VirtualBox version detection (OSE vs. regular)
+
+
+## Dependencies
+
+The gem uses the VirtualBox CLI (command-line tools), so they must be installed
+and on the system's path. The gem is developed against the documentation for
+VirtualBox 4.
+
+## Development Dependencies
+
+Running tests relies on a few command-line tools.
+
+On Fedora, use the following command to install the packages.
+
+```bash
+sudo yum install advancecomp curl mkisofs p7zip squashfs-tools
+```
+
+On OSX, run the following command.
+
+```bash
+brew install advancecomp cdrtools curl p7zip squashfs
+```
+
+
+## Limitations
+
+This gem makes some simplifying assumptions (rails people would say it is
+opinionated).
+
+* VM configuration XML file management is completely delegated to VirtualBox;
+the gem assumes and enforces the invariant that all XML files map to registered
+VMs
+
+
+## Contributing to virtual_box
+ 
+* Check out the latest master to make sure the feature hasn't been implemented
+or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it
+and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a
+future version unintentionally.
+* Please do not mess with the Rakefile, version, or history.
+
+
+## Copyright
+
+Copyright (c) 2010-2012 Victor Costan. See LICENSE.txt for further details.

data/Rakefile

@@ -1,28 +1,41 @@
-# Rakefile that uses echoe to manage virtual_box's gemspec. 
-#
-# Author:: Victor Costan
-# Copyright:: Copyright (C) 2009 Zergling.Net
-# License:: MIT
+# encoding: utf-8
 
 require 'rubygems'
-require 'echoe'
+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 'rake'
 
-Echoe.new('virtual_box') do |p|
-  p.project = 'zerglings' # rubyforge project
-  
-  p.author = 'Victor Costan'
-  p.email = 'victor@zergling.net'
-  p.summary = "Ruby API for VirtualBox (Sun's OSS virtualization software)."
-  p.url = 'http://github.com/costan/virtual_box'
-  p.dependencies = []
-  p.development_dependencies = ["echoe >=3.1.1", "flexmock >=0.8.6"]
-  
-  p.need_tar_gz = true
-  p.need_zip = true
-  p.rdoc_pattern = /^(lib|bin|tasks|ext)|^BUILD|^README|^CHANGELOG|^TODO|^LICENSE|^COPYING$/  
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "virtual_box"
+  gem.homepage = "http://github.com/csail/police"
+  gem.license = "MIT"
+  gem.summary = %Q{VirtualBox driver}
+  gem.description = %Q{Drives the VirtualBox command-line to manage VMs}
+  gem.email = "victor@costan.us"
+  gem.authors = ["Victor Costan"]
+  # dependencies defined in Gemfile
 end
+Jeweler::RubygemsDotOrgTasks.new
 
-if $0 == __FILE__
-  Rake.application = Rake::Application.new
-  Rake.application.run
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
 end
+
+load './test/tasks/tinycore.rake'
+
+task :test => :fixtures
+task :default => :test
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/virtual_box/board.rb

@@ -0,0 +1,287 @@
+module VirtualBox
+
+# Specification for a virtual machine's motherboard.
+class Board
+  # The number of CPUs (cores) on this board.
+  # @return [Integer]
+  attr_accessor :cpus
+
+  # The amount of megabytes of RAM on this board.
+  # @return [Integer]
+  attr_accessor :ram
+  # The amount of megabytes of video RAM on this board's video card.
+  # @return [Integer]
+  attr_accessor :video_ram
+  
+  # The UUID presented to the guest OS.
+  # @return [String]
+  attr_accessor :hardware_id  
+  
+  # The OS that will be running in the virtualized VM.
+  #
+  # Used to improve the virtualization performance.
+  # @return [Symbol]
+  attr_accessor :os
+  
+  # Whether the VM supports PAE (36-bit address space).
+  # @return [Boolean]
+  attr_accessor :pae  
+  # Whether the VM supports ACPI.
+  # @return [Boolean]
+  attr_accessor :acpi
+  # Whether the VM supports I/O APIC.
+  #
+  # This is necessary for 64-bit OSes, but makes the virtualization slower.
+  # @return [Boolean]
+  attr_accessor :io_apic
+    
+  # Whether the VMM attempts to use hardware support (Intel VT-x or AMD-V).
+  #
+  # Hardware virtualization can increase VM performance, especially used in
+  # conjunction with the other hardware virtualization options. However, using
+  # hardware virtualization in conjunction with other hypervisors can crash the
+  # host machine.
+  # @return [Boolean]
+  attr_accessor :hardware_virtualization
+  # Whether the VMM uses hardware support for nested paging.
+  #
+  # The option is used only if hardware_virtualization is set.
+  # @return [Boolean]
+  attr_accessor :nested_paging
+  # Whether the VMM uses hardware support for tagged TLB (VPID).
+  #
+  # The option is used only if hardware_virtualization is set. 
+  # @return [Boolean]
+  attr_accessor :tagged_tlb
+  
+  # Whether the VM supports 3D acceleration.
+  #
+  # 3D acceleration will only work with the proper guest extensions.
+  # @return [Boolean]
+  attr_accessor :accelerate_3d
+  
+  # Whether the BIOS logo will fade in when the board boots.
+  # @return [Boolean]
+  attr_accessor :bios_logo_fade_in
+  # Whether the BIOS logo will fade out when the board boots.
+  # @return [Boolean]
+  attr_accessor :bios_logo_fade_out
+  # The number of seconds to display the BIOS logo when the board boots.
+  # @return [Integer]
+  attr_accessor :bios_logo_display_time
+  # Whether the BIOS allows the user to temporarily override the boot VM device. 
+  #
+  # If false, no override is allowed. Otherwise, the user can press F12 at
+  # boot time to select a boot device. The user gets a prompt at boot time if
+  # the value is true. If the value is :menu_only the user does not get a
+  # prompt, but can still press F12 to select a device.
+  # @return [Boolean, Symbol]
+  attr_accessor :bios_boot_menu  
+  # Indicates the boot device search order for the VM's BIOS.
+  #
+  # This is an array that can contain the following symbols: :floppy+, :dvd,
+  # :disk, :net. Symbols should not be repeated.
+  # @return [Array<Symbol>]
+  attr_accessor :boot_order
+
+  # True if the motherboard includes an audio chipset.
+  # @return [Boolean]
+  attr_accessor :audio
+  
+  # If +true+, EFI firmware will be used instead of BIOS, for booting.
+  #
+  # The VirtualBox documentation states that EFI booting is highly experimental,
+  # and should only be used to virtualize MacOS.
+  # @return [Boolean]
+  attr_accessor :efi
+  
+  # Creates a new motherboard specification based on the given attributes.
+  #
+  # @param [Hash<Symbol, Object>] options ActiveRecord-style initial values for
+  #     attributes; can be used together with Board#to_hash to save and restore
+  def initialize(options = {})
+    reset
+    options.each { |k, v| self.send :"#{k}=", v }
+  end  
+   
+  # Arguments to "VBoxManage modifyvm" describing the VM's general settings.
+  #
+  # @return [Array<String>] arguments that can be concatenated to a "VBoxManage
+  #     modifyvm" command
+  def to_params
+    params = []
+    params.push '--cpus', cpus.to_s
+    params.push '--memory', ram.to_s
+    params.push '--vram', video_ram.to_s
+    params.push '--hardwareuuid', hardware_id
+    params.push '--ostype',
+               self.class.os_types[self.class.os_types[os.to_s]]
+        
+    params.push '--pae', pae ? 'on' : 'off'
+    params.push '--acpi', acpi ? 'on' : 'off'
+    params.push '--ioapic', io_apic ? 'on' : 'off'
+    
+    params.push '--hwvirtex', hardware_virtualization ? 'on' : 'off'
+    params.push '--nestedpaging',
+        (hardware_virtualization && nested_paging) ? 'on' : 'off'
+    params.push '--vtxvpid',
+        (hardware_virtualization && tagged_tlb) ? 'on' : 'off'
+    
+    params.push '--firmware', efi ? 'efi' : 'bios'
+    params.push '--bioslogofadein', bios_logo_fade_in ? 'on' : 'off'
+    params.push '--bioslogofadeout', bios_logo_fade_out ? 'on' : 'off'
+    params.push '--bioslogodisplaytime', bios_logo_display_time.to_s
+
+    bios_boot_menu_str = case bios_boot_menu
+    when false
+      'disabled'
+    when :menu_only
+      'message'
+    else
+      'messageandmenu'
+    end
+    params.push '--biosbootmenu', bios_boot_menu_str
+    unique_boot_order = boot_order.uniq
+    1.upto(4) do |i|
+      device = unique_boot_order[i - 1]
+      params.push "--boot#{i}", (device ? device.to_s : 'none')
+    end
+    
+    params.push '--audio', (audio ? 'null' : 'none') 
+    
+    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
+  # @return [VirtualBox::Board] self, for easy call chaining
+  def from_params(params)
+    self.cpus = params['cpus'].to_i
+    self.ram = params['memory'].to_i
+    self.video_ram = params['vram'].to_i
+    self.hardware_id = params['hardwareuuid']
+    self.os = self.class.os_types[params['ostype']]
+
+    self.pae = params['pae'] == 'on'    
+    self.acpi = params['acpi'] == 'on'    
+    self.io_apic = params['io_apic'] == 'on'    
+
+    self.hardware_virtualization = params['hwvirtex'] == 'on'    
+    self.nested_paging = params['nestedpaging'] == 'on'    
+    self.tagged_tlb = params['vtxvpid'] == 'on'    
+
+    self.efi = params['firmware'] == 'efi'
+    self.bios_logo_fade_in = params['bioslogofadein'] == 'on'
+    self.bios_logo_fade_out = params['bioslogofadeout'] == 'on'
+    self.bios_logo_display_time = params['bioslogodisplaytime'].to_i
+    
+    self.bios_boot_menu = case params['bootmenu']
+    when 'disabled'
+       false
+    when 'message'
+      :menu_only
+    else
+      true
+    end
+    
+    self.boot_order = []
+    %w(boot1 boot2 boot3 boot4).each do |boot_key|
+      next unless params[boot_key] && params[boot_key] != 'none'
+      boot_order << params[boot_key].to_sym
+    end
+    
+    self.audio = params['audio'] != 'none'
+    
+    self
+  end
+  
+  # Resets to default settings.
+  #
+  # The defaults are chosen somewhat arbitrarily by the gem's author.
+  # @return [VirtualBox::Board] self, for easy call chaining
+  def reset
+    self.cpus = 1
+    self.ram = 512
+    self.video_ram = 18
+    self.hardware_id = UUID.generate
+
+    self.os = :other    
+    self.pae = false
+    self.acpi = true
+    self.io_apic = false
+    
+    self.hardware_virtualization = true
+    self.nested_paging = true
+    self.tagged_tlb = true
+    self.accelerate_3d = false
+    
+    self.efi = false
+    self.bios_logo_fade_in = false    
+    self.bios_logo_fade_out = false
+    self.bios_logo_display_time = 0
+    self.bios_boot_menu = false
+    
+    self.boot_order = [:disk, :net, :dvd]
+    
+    self.audio = false
+    self
+  end
+  
+  # Hash capturing this motherboard specification. Can be passed to Board#new.
+  #
+  # @return [Hash<Symbol, Object>] Ruby-friendly Hash that can be used to
+  #                                re-create this motherboard specification
+  def to_hash
+    { :cpus => cpus, :ram => ram, :video_ram => video_ram,
+      :hardware_id => hardware_id, :os => os, :pae => pae, :acpi => acpi,
+      :io_apic => io_apic, :hardware_virtualization => hardware_virtualization,
+      :nested_paging => nested_paging, :tagged_tlb => tagged_tlb,
+      :accelerate_3d => accelerate_3d, :efi => efi,
+      :bios_logo_fade_in => bios_logo_fade_in,
+      :bios_logo_fade_out => bios_logo_fade_out,
+      :bios_logo_display_time => bios_logo_display_time,
+      :bios_boot_menu => bios_boot_menu, :audio => audio }
+  end
+  
+  # The OS types supported by the VirtualBox installation.
+  #
+  # @return [Hash<Symbol|String, String|Symbol>] mapping from
+  #     programmer-friendly symbols (e.g. :linux26) to proper VirtualBox OS IDs,
+  #     and from VirtualBox IDs and description strings to programmer-friendly
+  #     symbols
+  def self.os_types
+    return @os_types if @os_types
+    
+    @os_types = {}
+    list_os_types.each do |key, value|
+      os_id = key.downcase.to_sym
+      @os_types[key] = os_id
+      @os_types[key.downcase] = os_id
+      @os_types[value] = os_id
+      @os_types[os_id] = key
+    end
+    @os_types
+  end
+  
+  # Queries VirtualBox for available OS types.
+  #
+  # @return [Hash<String, String> mapping from each VirtualBox OS type ID to its
+  #     description
+  def self.list_os_types
+    result = VirtualBox.run_command ['VBoxManage', '--nologo', 'list',
+                                     '--long', 'ostypes']
+    if result.status != 0
+      raise 'Unexpected error code returned by VirtualBox'
+    end
+    
+    types = result.output.split("\n\n").map do |os_info|
+      i = Hash[os_info.split("\n").map { |line| line.split(':').map(&:strip) }]
+      [i['ID'], i['Description']]
+    end
+    Hash[types]
+  end
+end  # class VirtualBox::Board
+
+end  # namespace VirtualBox

data/lib/virtual_box/cli.rb

@@ -0,0 +1,20 @@
+# Run code via the command-line interface.
+
+require 'English'
+require 'shellwords'
+
+module VirtualBox
+
+# Runs a command in a sub-shell, waiting until the command completes.
+#
+# @param [Array<String>] args the name and arguments for the command to be run
+#
+# @return [Hashie::Mash<Symbol, String>] hash with the following keys / methods:
+#     :status:: the command's exit status
+#     :output:: a string with the command's output
+def self.run_command(args)
+  output = Kernel.`(Shellwords.shelljoin(args))
+  Hashie::Mash.new :status => $CHILD_STATUS.exitstatus, :output => output
+end
+
+end  # namespace VirtualBox