bbrowning-virtualbox 0.7.6.dev

data/lib/virtualbox/forwarded_port.rb

@@ -0,0 +1,222 @@
+module VirtualBox
+  # When a VM uses NAT as its NIC type, VirtualBox acts like its
+  # own private router for all virtual machines. Because of this,
+  # the host machine can't access services within the guest machine.
+  # To get around this, NAT supports port forwarding, which allows the
+  # guest machine services to be forwarded to some port on the host
+  # machine. Port forwarding is done completely through {ExtraData}, but
+  # is a complicated enough procedure that this class was made to
+  # faciliate it.
+  #
+  # **Note:** After changing any forwarded ports, the entire VirtualBox
+  # process must be restarted completely for them to take effect. When
+  # working with the ruby library, this isn't so much of an issue, but
+  # if you have any VMs running, they must all be shut down and restarted.
+  #
+  # # Adding a new Forwarded Port
+  #
+  # Since forwarded ports rely on being part of a {VM}, we're going to
+  # assume that `vm` points to a {VM} which has already been found.
+  #
+  #     port = VirtualBox::ForwardedPort.new
+  #     port.name = "apache" # This can be anything
+  #     port.guestport = 80
+  #     port.hostport = 8080
+  #     vm.forwarded_ports << port
+  #     port.save # Or vm.save
+  #
+  # # Modifying an Existing Forwarded Port
+  #
+  # This is assuming that `vm` is a local variable storing a {VM} object
+  # which has already been found.
+  #
+  #     vm.forwarded_ports.first.hostport = 1919
+  #     vm.save
+  #
+  # # Deleting a Forwarded Port
+  #
+  # To delete a forwarded port, you simply destroy it like any other model:
+  #
+  #     vm.forwarded_ports.first.destroy
+  #
+  # # Attributes and Relationships
+  #
+  # Properties of the model are exposed using standard ruby instance
+  # methods which are generated on the fly. Because of this, they are not listed
+  # below as available instance methods.
+  #
+  # These attributes can be accessed and modified via standard ruby-style
+  # `instance.attribute` and `instance.attribute=` methods. The attributes are
+  # listed below.
+  #
+  # Relationships are also accessed like attributes but can't be set. Instead,
+  # they are typically references to other objects such as an {AttachedDevice} which
+  # in turn have their own attributes which can be modified.
+  #
+  # ## Attributes
+  #
+  # This is copied directly from the class header, but lists all available
+  # attributes. If you don't understand what this means, read {Attributable}.
+  #
+  #     attribute :parent, :readonly => true
+  #     attribute :name
+  #     attribute :instance, :default => "0"
+  #     attribute :device, :default => "pcnet"
+  #     attribute :protocol, :default => "TCP"
+  #     attribute :guestport
+  #     attribute :hostport
+  #
+  class ForwardedPort < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :parent_collection, :readonly => true, :property => false
+    attribute :name
+    attribute :instance, :default => "0"
+    attribute :device, :default => "pcnet"
+    attribute :protocol, :default => "TCP"
+    attribute :guestport
+    attribute :hostport
+
+    class << self
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<ForwardedPort>]
+      def populate_relationship(caller, data)
+        relation = Proxies::Collection.new(caller)
+
+        caller.extra_data.each do |key, value|
+          next unless key =~ /^(VBoxInternal\/Devices\/(.+?)\/(.+?)\/LUN#0\/Config\/(.+?)\/)Protocol$/i
+
+          port = new({
+            :parent => caller,
+            :parent_collection => relation,
+            :name => $4.to_s,
+            :instance => $3.to_s,
+            :device => $2.to_s,
+            :protocol => value,
+            :guestport => caller.extra_data["#{$1.to_s}GuestPort"],
+            :hostport => caller.extra_data["#{$1.to_s}HostPort"]
+          })
+
+          port.existing_record!
+
+          relation.push(port)
+        end
+
+        relation
+      end
+
+      # Saves the relationship. This simply calls {#save} on every
+      # member of the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, data)
+        data.dup.each do |fp|
+          fp.save
+        end
+      end
+    end
+
+    # @param [Hash] data The initial attributes to populate.
+    def initialize(data={})
+      super()
+      populate_attributes(data) if !data.empty?
+    end
+
+    # Validates a forwarded port.
+    def validate
+      super
+
+      validates_presence_of :parent
+      validates_presence_of :name
+      validates_presence_of :guestport
+      validates_presence_of :hostport
+    end
+
+    # Retrieves the device for the forwarded port. This tries to "do the
+    # right thing" depending on the first NIC of the VM parent by either
+    # setting the forwarded port type to "pcnet" or "e1000." If the device
+    # was already set manually, this method will simply return that value
+    # instead.
+    #
+    # @return [String] Device type for the forwarded port
+    def device
+      # Return the current or default value if it is:
+      #  * an existing record, since it was already mucked with, no need to
+      #    modify it again
+      #  * device setting changed, since we should return what the user set
+      #    it to
+      #  * If the parent is nil, since we can't infer the type without a parent
+      return read_attribute(:device) if !new_record? || device_changed? || parent.nil?
+
+      device_map = {
+        :Am79C970A => "pcnet",
+        :Am79C973 => "pcnet",
+        :I82540EM => "e1000",
+        :I82543GC => "e1000",
+        :I82545EM => "e1000"
+      }
+
+      return device_map[parent.network_adapters[0].adapter_type]
+    end
+
+    # Saves the forwarded port.
+    #
+    # @return [Boolean] True if command was successful, false otherwise.
+    def save
+      return true if !new_record? && !changed?
+      raise Exceptions::ValidationFailedException.new(errors) if !valid?
+
+      destroy if !new_record? && name_changed?
+
+      parent.extra_data["#{key_prefix}Protocol"] = protocol
+      parent.extra_data["#{key_prefix}GuestPort"] = guestport
+      parent.extra_data["#{key_prefix}HostPort"] = hostport
+      result = parent.extra_data.save
+
+      clear_dirty!
+      existing_record!
+
+      result
+    end
+
+    # Destroys the port forwarding mapping.
+    #
+    # @return [Boolean] True if command was successful, false otherwise.
+    def destroy
+      results = []
+
+      if !new_record?
+        results << parent.extra_data.delete("#{key_prefix(true)}Protocol")
+        results << parent.extra_data.delete("#{key_prefix(true)}GuestPort")
+        results << parent.extra_data.delete("#{key_prefix(true)}HostPort")
+
+        # Remove it from any collection
+        parent_collection.delete(self, true) if parent_collection
+
+        new_record!
+      end
+
+      results.empty? || results.all? { |o| o == true }
+    end
+
+    # Relationship callback when added to a collection. This is automatically
+    # called by any relationship collection when this object is added.
+    def added_to_relationship(proxy)
+      write_attribute(:parent, proxy.parent)
+      write_attribute(:parent_collection, proxy)
+    end
+
+    # Returns the prefix to be used for the extra data key. Forwarded ports
+    # are created by simply setting {ExtraData} on a {VM}. This class hides most
+    # of the inner workings of it, but it requires a common prefix. This method
+    # generates that.
+    #
+    # @return [String]
+    def key_prefix(old_name=false)
+      name_value = old_name && name_changed? ? name_was : name
+      "VBoxInternal\/Devices\/#{device}\/#{instance}\/LUN#0\/Config\/#{name_value}\/"
+    end
+  end
+end

data/lib/virtualbox/global.rb

@@ -0,0 +1,102 @@
+module VirtualBox
+  # Represents the VirtualBox main configuration file (VirtualBox.xml)
+  # which VirtualBox uses to keep track of all known virtual machines
+  # and images. This "global" configuration has many relationships which
+  # allow the user to retrieve a list of all VMs, media, global extra data,
+  # etc. Indeed, even methods like {VM.all} are implemented using this class.
+  #
+  # # Getting Global Data
+  #
+  # To retrieve the global data, use `Global.global`. This value is _cached_
+  # between calls, so subsequent calls will not go through the entire parsing
+  # process. To force a reload, set the `reload` parameter to true. Besides
+  # setting the parameter explicitly, some actions will implicitly force the
+  # global data to reload on the next call, such as saving a VM or destroying
+  # an image, for example.
+  #
+  #     # Retrieve global data for the first time. This will parse all the
+  #     # data.
+  #     global_object = VirtualBox::Global.global
+  #
+  #     # Subsequent calls are near-instant:
+  #     VirtualBox::Global.global
+  #
+  #     # Or we can choose to reload the data...
+  #     reloaded_object = VirtualBox::Global.global(true)
+  #
+  # # Relationships
+  #
+  # While a global object doesn't have attributes, it does have many
+  # relationships. The relationships are listed below. If you don't
+  # understand this, read {Relatable}.
+  #
+  #     relationship :vms, VM
+  #     relationship :media, Media
+  #     relationship :extra_data, ExtraData
+  #     relationship :system_properties, :SystemProperties, :lazy => true
+  #
+  class Global < AbstractModel
+    attribute :lib, :readonly => true
+
+    relationship :vms, :VM, :lazy => true
+    relationship :media, :Media, :lazy => true
+    relationship :extra_data, :ExtraData, :lazy => true
+    relationship :system_properties, :SystemProperties, :lazy => true
+    relationship :host, :Host, :lazy => true
+    relationship :dhcp_servers, :DHCPServer, :lazy => true
+
+    @@global_data = nil
+
+    class << self
+      # Retrieves the global data. The return value of this call is cached,
+      # and can be reloaded by setting the `reload` parameter to true. Besides
+      # explicitly setting the parameter, some actions within the library
+      # force global to reload itself on the next call, such as saving a VM,
+      # or destroying an image.
+      #
+      # @param [Boolean] reload True if you want to force a reload of the data.
+      # @return [Global]
+      def global(reload=false)
+        if !@@global_data || reload
+          @@global_data = new(Lib.lib)
+        end
+
+        @@global_data
+      end
+
+      # Resets the global data singleton. This is used for testing purposes.
+      def reset!
+        @@global_data = nil
+      end
+    end
+
+    def initialize(lib)
+      write_attribute(:lib, lib)
+
+      # Required to load lazy relationships
+      existing_record!
+    end
+
+    def create_machine(name, type)
+      imachine = lib.virtualbox.create_machine(name, type)
+      lib.virtualbox.register_machine(imachine)
+      VirtualBox::VM.find(imachine.id)
+    end
+
+    def load_relationship(name)
+      # "Lazy loaded" associations table. These associate the relationship
+      # with the data it needs to load. The data is wrapped in lambdas so
+      # that the evaluation doesn't occur unless necessary.
+      relationships = {
+        :vms => lambda { lib.virtualbox.machines },
+        :media => lambda { lib },
+        :extra_data => lambda { lib.virtualbox },
+        :system_properties => lambda { lib.virtualbox.system_properties },
+        :host => lambda { lib.virtualbox.host },
+        :dhcp_servers => lambda { lib.virtualbox.dhcp_servers }
+      }
+
+      populate_relationship(name, relationships[name].call)
+    end
+  end
+end

data/lib/virtualbox/guest_property.rb

@@ -0,0 +1,116 @@
+module VirtualBox
+  # Represents guest properties which can be read and set per virtual
+  # machine as long as the guest additions are running in the VM.
+  #
+  # A number of properties are predefined by VirtualBox for retrieving
+  # information about the VM such as operating system, guest additions
+  # version, users currently logged in, network statistics (including ip
+  # addresses), and more. For more information, read the Guest Properties
+  # section under the Guest Additions chapter (currently chapter 4) in
+  # the VirtualBox manual.
+  #
+  # Guest Properties on a Virtual Machine
+  #
+  # Setting a guest property on a virtual machine is easy. All {VM} objects
+  # have a `guest_property` relationship which is just a simple ruby hash,
+  # so you can treat it like one! Once the data is set, simply saving the VM
+  # will save the guest property. An example below:
+  #
+  #     vm = VirtualBox::VM.find("FooVM")
+  #     vm.guest_property["/Foo/Bar"] = "yes"
+  #     vm.save
+  #
+  # Now, let's say you open up the VM again some other time:
+  #
+  #     vm = VirtualBox::VM.find("FooVM")
+  #     puts vm.guest_property["/Foo/Bar"]
+  #
+  # It acts just like a hash!
+  #
+  class GuestProperty < Hash
+    include AbstractModel::Dirty
+
+    attr_accessor :parent
+    attr_reader :interface
+
+    class << self
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<GuestProperty>]
+      def populate_relationship(caller, interface)
+        data = new(caller, interface)
+
+        keys, values, timestamps, flags  = interface.enumerate_guest_properties
+        keys.each_with_index do |key, index|
+          data[key] = values[index]
+        end
+
+        data.clear_dirty!
+        data
+      end
+
+      # Saves the relationship. This simply calls {#save} on every
+      # member of the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, data)
+        data.save
+      end
+    end
+
+    # Initializes a guest property object.
+    #
+    # @param [Hash] data Initial attributes to populate.
+    def initialize(parent, interface)
+      @parent = parent
+      @interface = interface
+    end
+
+    # Set a guest property key-value pair. Overrides ruby hash implementation
+    # to set dirty state. Otherwise, behaves the same way.
+    def []=(key,value)
+      set_dirty!(key, self[key], value)
+      super
+    end
+
+    # Saves guest properties. This method does the same thing for both new
+    # and existing guest properties, since virtualbox will overwrite old data or
+    # create it if it doesn't exist.
+    def save
+      changes.each do |key, value|
+        unless virtualbox_key?(key)
+          interface.set_guest_property_value(key.to_s, value[1].to_s)
+
+          clear_dirty!(key)
+
+          if value[1].nil?
+            # Remove the key from the hash altogether
+            hash_delete(key.to_s)
+          end
+        end
+      end
+    end
+
+    # Alias away the old delete method so its still accessible somehow
+    alias :hash_delete :delete
+
+    # Deletes the specified extra data.
+    #
+    # @param [String] key The extra data key to delete
+    def delete(key)
+      unless virtualbox_key?(key)
+        interface.set_guest_property_value(key.to_s, nil)
+        hash_delete(key.to_s)
+      end
+    end
+
+    # Determine if a key is one set by VirtualBox
+    #
+    # **This method typically won't be used except internally.**
+    def virtualbox_key?(key)
+      key =~ /^\/VirtualBox/
+    end
+  end
+end

data/lib/virtualbox/hard_drive.rb

@@ -0,0 +1,246 @@
+module VirtualBox
+  # Represents a hard disk which is registered with VirtualBox.
+  #
+  # # Finding a Hard Drive
+  #
+  # Hard drives can be found use {HardDrive.all} and {HardDrive.find}, which
+  # find all or a specific hard drive, respectively. Example below:
+  #
+  #     VirtualBox::HardDrive.all
+  #
+  # Or use find with the UUID of the HardDrive:
+  #
+  #     VirtualBox::HardDrive.find("4a896f0b-b3a3-4dec-8c26-8406c6fccd6e")
+  #
+  # # Creating a Hard Drive
+  #
+  # Hard Drives can be created by intilizing an empty hard drive, assigning
+  # values to the necessary attributes, and calling save on the object.
+  # Below is a simple example of how this works:
+  #
+  #     hd = VirtualBox::HardDrive.new
+  #     hd.format = "VDI" # Or any format list with `VBoxManage list hddbackends`
+  #     hd.location = "foo.vdi"
+  #     hd.size = 2400 # in megabytes
+  #     hd.save
+  #
+  #     # You can now access other attributes, since its saved:
+  #     hd.uuid
+  #     hd.location # will return a full path now
+  #
+  # # Destroying Hard Drives
+  #
+  # Hard drives can also be deleted. **This operation is not reversable**.
+  #
+  #     hd = VirtualBox::HardDrive.find("...")
+  #     hd.destroy
+  #
+  # This will only unregister the Hard Drive from VirtualBox and will not destroy
+  # the storage space on the disk. To destroy the storage space, pass `true` to
+  # the destroy method, example:
+  #
+  #     hd.destroy(true)
+  #
+  # # Cloning Hard Drives
+  #
+  # Hard Drives can just as easily be cloned as they can be created or destroyed.
+  #
+  #     hd = VirtualBox::HardDrive.find("...")
+  #     cloned_hd = hd.clone("bar.vdi")
+  #
+  # In addition to simply cloning hard drives, this command can be used to
+  # clone to a different format. If the format is not passed in (as with the
+  # the above example, the system default format will be used). example:
+  #
+  #     hd = VirtualBox::HardDrive.find("...")
+  #     hd.clone("bar.vmdk", "VMDK") # Will clone and convert to VMDK format
+  #
+  # # Attributes
+  #
+  # Properties of the model are exposed using standard ruby instance
+  # methods which are generated on the fly. Because of this, they are not listed
+  # below as available instance methods.
+  #
+  # These attributes can be accessed and modified via standard ruby-style
+  # `instance.attribute` and `instance.attribute=` methods. The attributes are
+  # listed below. If you aren't sure what this means or you can't understand
+  # why the below is listed, please read {Attributable}.
+  #
+  #     attribute :format, :default => "VDI"
+  #     attribute :location
+  #     attribute :logical_size
+  #     attribute :physical_size, :readonly => true, :property => :size
+  #
+  # There are more attributes on the {Medium} model, which {HardDrive} inherits
+  # from.
+  #
+  class HardDrive < Medium
+    include ByteNormalizer
+
+    attribute :format, :default => "VDI"
+    attribute :location
+    attribute :logical_size
+    attribute :physical_size, :readonly => true, :property => :size
+
+    class << self
+      # Returns an array of all available hard drives as HardDrive
+      # objects.
+      #
+      # @return [Array<HardDrive>]
+      def all
+        Global.global(true).media.hard_drives
+      end
+
+      # Finds one specific hard drive by UUID. If the hard drive
+      # can not be found, will return `nil`.
+      #
+      # @param [String] id The UUID of the hard drive
+      # @return [HardDrive]
+      def find(id)
+        all.detect { |hd| hd.uuid == id }
+      end
+
+      # Override of {Medium.device_type}.
+      def device_type
+        :hard_disk
+      end
+    end
+
+    # Overwrite the AbstractModel initialize to make the imedium parameter
+    # optional so that new Hard Drives can be created
+    def initialize(imedium = nil)
+      super if imedium
+    end
+
+    # Custom getter to convert the physical size from bytes to megabytes.
+    def physical_size
+      bytes_to_megabytes(read_attribute(:physical_size))
+    end
+
+    # Get an array of machines attached to this Virtual Machine
+    def machines
+      interface.machine_ids.collect { |id| VirtualBox::VM.find(id) }
+    end
+
+    # Validates a hard drive for the minimum attributes required to
+    # create or save.
+    def validate
+      super
+
+      medium_formats = Global.global.system_properties.medium_formats.collect { |mf| mf.id }
+      validates_inclusion_of :format, :in => medium_formats, :message => "must be one of the following: #{medium_formats.join(', ')}."
+
+      validates_presence_of :location
+
+      max_vdi_size = Global.global.system_properties.max_vdi_size
+      validates_inclusion_of :logical_size, :in => (0..max_vdi_size), :message => "must be between 0 and #{max_vdi_size}."
+    end
+
+    # Creates a new {COM::Interface::Medium} instance. This simply creates
+    # the new {COM::Interface::Medium} structure. It does not (and shouldn't)
+    # create the storage space on the host system. See the create method for
+    # an example on to create the storage space.
+    #
+    # @param [String] outputfile The output file. This can be a full path
+    #   or just a filename. If its just a filename, it will be placed in
+    #   the default hard drives directory. Should not be present already.
+    # @param [String] format The format to convert to. If not present, the
+    #   systems default will be used.
+    # @return [COM::Interface::Medium] The new {COM::Interface::Medium} instance
+    #   or will raise a {Exceptions::MediumCreationFailedException} on failure.
+    def create_hard_disk_medium(outputfile, format = nil)
+      # Get main VirtualBox object
+      virtualbox = Lib.lib.virtualbox
+
+      # Assign the default format if it isn't set yet
+      format ||= virtualbox.system_properties.default_hard_disk_format
+
+      # Expand path relative to the default hard disk folder. This allows
+      # filenames to exist in the default folder while full paths will use
+      # the paths specified.
+      outputfile = File.expand_path(outputfile, virtualbox.system_properties.default_hard_disk_folder)
+
+      # If the outputfile path is in use by another Hard Drive, lets fail
+      # now with a meaningful exception rather than simply return a nil
+      raise Exceptions::MediumLocationInUseException.new(outputfile) if File.exist?(outputfile)
+
+      # Create the new {COM::Interface::Medium} instance.
+      new_medium = virtualbox.create_hard_disk(format, outputfile)
+
+      # Raise an error if the creation of the {COM::Interface::Medium}
+      # instance failed
+      raise Exceptions::MediumCreationFailedException.new unless new_medium
+
+      # Return the new {COM::Interface::Medium} instance.
+      new_medium
+    end
+
+    # Clone hard drive, possibly also converting formats. All formats
+    # supported by your local VirtualBox installation are supported
+    # here. If no format is specified, the systems default will be used.
+    #
+    # @param [String] outputfile The output file. This can be a full path
+    #   or just a filename. If its just a filename, it will be placed in
+    #   the default hard drives directory. Should not be present already.
+    # @param [String] format The format to convert to. If not present, the
+    #   systems default will be used.
+    # @return [HardDrive] The new, cloned hard drive, or nil on failure.
+    def clone(outputfile, format = nil)
+      # Create the new Hard Disk medium
+      new_medium = create_hard_disk_medium(outputfile, format)
+
+      # Clone the current drive onto the new Hard Disk medium
+      interface.clone_to(new_medium, :standard, nil).wait_for_completion(-1)
+
+      # Locate the newly cloned hard drive
+      self.class.find(new_medium.id) if new_medium.respond_to?(:id)
+    end
+
+    # Creates a new hard drive.
+    #
+    # **This method should NEVER be called. Call {#save} instead.**
+    #
+    # @return [Boolean] True if command was successful, false otherwise.
+    def create
+      return false unless new_record?
+      raise Exceptions::ValidationFailedException.new(errors) if !valid?
+
+      # Create the new Hard Disk medium
+      new_medium = create_hard_disk_medium(location, format)
+
+      # Create the storage on the host system
+      new_medium.create_base_storage(logical_size, :standard).wait_for_completion(-1)
+
+      # Update the current Hard Drive instance with the uuid and
+      # other attributes assigned after storage was written
+      write_attribute(:interface, new_medium)
+      initialize_attributes(new_medium)
+
+      # If the uuid is present, then everything worked
+      uuid && !uuid.to_s.empty?
+    end
+
+    # Saves the hard drive object. If the hard drive is new,
+    # this will create a new hard drive. Otherwise, it will
+    # save any other details about the existing hard drive.
+    #
+    # Currently, **saving existing hard drives does nothing**.
+    # This is a limitation of VirtualBox, rather than the library itself.
+    #
+    # @return [Boolean] True if command was successful, false otherwise.
+    def save
+      return true if !new_record? && !changed?
+      raise Exceptions::ValidationFailedException.new(errors) if !valid?
+
+      if new_record?
+        create # Create a new hard drive
+      else
+        # Mediums like Hard Drives are not updatable, they need to be recreated
+        # Because Hard Drives contain info and paritions, it's easier to error
+        # out now than try and do some complicated logic
+        msg = "Hard Drives cannot be updated. You need to create one from scratch."
+        raise Exceptions::MediumNotUpdatableException.new(msg)
+      end
+    end
+  end
+end