Package: ploy-virtualbox
OverviewThe ploy_virtualbox plugin provides integration ofVirtualBoxwithploy.Installationploy_virtualbox is best installed with easy_install, pip or with zc.recipe.egg in a buildout.MasterThe default master for ploy_virtualbox isvirtualboxand has the following options:headlessWhether to start instances in headless mode by default.
If not set, the system default is used.use-acpi-powerbuttonWhether to use acpi power off by default when stopping instances.
If not set, the system default is used.basefolderThe basefolder for VirtualBox data.
If not set, the VirtualBox default is used.
This varies depending on the OS that ploy is running in.
When not provided as absolute path, then it’s relative toploy.conf.instanceName of instance to use to execute VirtualBox commands instead of the default local machine.Example:[vb-master:virtualbox]
headless = trueInstancesheadlessWhether to start this instance in headless mode.
If not set, the setting of the master is used.use-acpi-powerbuttonWhether to use acpi power off for this instance when stopping.
If not set, the setting of the master is used.basefolderThe basefolder for this instances VirtualBox data.
If not set, the setting of the master is used.
When not provided as absolute path, then it’s relative toploy.conf.no-terminateIf set toyes, the instance can’t be terminated via ploy until the setting is changed tonoor removed entirely.Any option starting withvm-is stripped of thevm-prefix and passed on to VBoxManage.
Almost all of these options are passed as is.
The following options are handled differently or have some convenience added:storageOne storage definition per line.
SeeVBoxManage storageattachdocumentation for details.If you don’t specify thetype, thenhddis used by default.You don’t have to specify theport, if not set the line number starting at zero is used.If you don’t set--storagectlthensatais used as default and if that controller doesn’t exist it’s created automatically.Ifmediumreferences a local file that path will be passed directly toVBoxManage storageattach.If it takes the formvb-disk:NAMEwhich refers to aDisk sectioncalledNAMEthat will be used instead.If it takes the form of an URL, the filename of that URL is assumed to be located at~/.ploy/downloads/(this default can be overridden in the[global]section of the configuration file with an entrydownload_dir).
If the file does not exist it will be downloaded.When using the URL notation it is strongly encouraged to also provide a checksum using the--medium_sha1key (currently only SHA1 is supported).Example for using a local ISO image as DVD drive:storage =
    --type dvddrive --medium ~/downloads/archives/mfsbsd-se-9.2-RELEASE-amd64.iso
    --medium vb-disk:bootExample for referencing an external URL:storage =
    --type dvddrive --medium https://mfsbsd.vx.sk/files/iso/12/amd64/mfsbsd-se-12.0-RELEASE-amd64.iso --medium_sha1 2fbf2be5a79cc8081d918475400581bd54bb30ae
    --medium vb-disk:boothostonlyadapterIf there is a matchingHost only interface section, then that is evaluated.Disk sectionsThese section allow you to describe how disks should be created.You can set thesize,variantandformatoptions as described in theVBoxManage createhddocumentation.Thefilenameoption allows you to set a filename for the disk, the extension is automatically added based on theformatoption.
If you use a relative path, then it’s base is thebasefoldersetting of the instance.When thedeleteoption is set tofalse, the disk is not deleted when the instance using it is terminated.
The default is to delete the disk upon instance termination.Example:[vb-disk:boot]
size = 102400Host only interface sectionsIf you want to use host only network interfaces, then this allows you to make sure your settings are as expected and the interface exists.
For now only theipoption is supported.
SeeVBoxManage hostonlyifdocumentation for details.Example:[vb-hostonlyif:vboxnet0]
ip = 192.168.56.1DHCPIf avb-dhcpserversection with the same name exists, then it is checked and if needed configured as well.
SeeVBoxManage hostonlyifdocumentation for details.Example:[vb-dhcpserver:vboxnet0]
ip = 192.168.56.2
netmask = 255.255.255.0
lowerip = 192.168.56.100
upperip = 192.168.56.254The combination ofvb-hostonlyifwithvb-dhcpserverallows to configure a hostonly network with a deterministic IP address.
In the above example you could configure an instance with a static IP address of192.168.56.99which would be addressable from the host.
The important part is to chose an address that iswithinthe DHCP server network butoutsideits DHCP pool, which is defined byloweripandupperiprespecitively.SSHDepending on the setup we can’t get the IP address or host name automatically.Unfortunately VirtualBox doesn’t provide a way to see which instance got which IP address from it’s own DHCP servers for example.If you know which host name or ip address your instance will have, then set thehostoripoption as explained above in thehostonlysection.As a workaround you can also setup a NAT port forwarding like this:vm-nic2 = nat
vm-natpf2 = ssh,tcp,,47022,,22For this case ploy_virtualbox knows how to get the port and uses it for SSH access via localhost.If you install the VirtualBox guest additions in your instance, then thestatuscommand can show you the current IP address of the instance.Example config[vb-master:virtualbox]
# use-acpi-powerbutton = false

[vb-disk:boot]
size = 102400

[vb-hostonlyif:vboxnet0]
ip = 192.168.56.1

[vb-dhcpserver:vboxnet0]
ip = 192.168.56.2
netmask = 255.255.255.0
lowerip = 192.168.56.100
upperip = 192.168.56.254

[vb-instance:foo]
# headless = true
vm-ostype = FreeBSD_64
vm-memory = 512
vm-accelerate3d = off
vm-acpi = on
vm-rtcuseutc = on
vm-boot1 = disk
vm-boot2 = dvd
vm-nic1 = hostonly
vm-hostonlyadapter1 = vboxnet0
vm-nic2 = nat
vm-natpf2 = ssh,tcp,,47022,,22
storage =
    --type dvddrive --medium ~/downloads/archives/mfsbsd-se-9.2-RELEASE-amd64.iso
    --medium vb-disk:bootChangelog2.0.0 - 2022-08-17Dropped support for Python 3.6.
[fschulze]Added support for Python 3.10.
[fschulze]2.0.0b3 - 2021-07-17Fix dhcpserver setup for newer VirtualBox versions.
[fschulze]2.0.0b2 - 2019-06-09Fix tests for Python 3.x after ploy 2.0.0b3 release.
[fschulze]Drop support for Python 3.4.
[fschulze]2.0.0b1 - 2018-02-07Support for ploy 2.0.0.
[fschulze]1.2.0 - 2015-09-03Adddeleteoption to disks. If set tofalse, the disk is kept in
place upon instance termination and not deleted as per default.
[fschulze]Ask user whether to continue or not when checksum of downloaded iso image
doesn’t match.
[tomster]1.1.0 - 2015-01-20Log info when starting an instance.
[fschulze]Handle instances inabortedstate.
[fschulze]Print error output of commands on failures.
[fschulze]Use new helper in ploy 1.0.2 to setup proxycommand.
[fschulze]Added possibility to specify a remote instance to use for a virtualbox master.
[fschulze]Added ability to reference disk images via external URL for virtualbox instances storage.
[tomster]1.0.0 - 2014-07-19Added documentation.
[fschulze]Renamedvb-mastertovirtualbox, so the uids of instances are nicer.
[fschulze]Enable DHCP server when creating or modifying it.
[fschulze]1.0b4 - 2014-07-15Verify and if possible create host only interfaces and dhcpservers.
[fschulze]Add support for instances that have manually been put intosavedstate.
[fschulze]1.0b3 - 2014-07-08Packaging and test fixes.
[fschulze]1.0b2 - 2014-07-04Python 3 compatibility.
[fschulze]Renamed mr.awsome to ploy and mr.awsome.virtualbox to ploy_virtualbox.
[fschulze]1.0b1 - 2014-06-16Initial release
[fschulze]