Teleporting settings

With the following commands forVBoxManage modifyvmyou can configure a machine to be a target for teleporting. See chapter7.2,Teleporting, page93for an introduction.

• --teleporter on|off: With this setting you turn on or off whether a machine waits for a teleporting request to come in on the network when it is started. If “on”, when the machine is started, it does not boot the virtual machine as it would normally; instead, it then waits for a teleporting request to come in on the port and address listed with the next two parameters.

• --teleporterport <port>, --teleporteraddress <address>: these must be used with –teleporter and tell the virtual machine on which port and address it should listen for a teleporting request from another virtual machine. <port>can be any free TCP/IP port number (e.g. 6000);<address>can be any IP address or hostname and specifies the TCP/IP socket to bind to. The default is “0.0.0.0”, which means any address.

• --teleporterpassword <password>: if this optional argument is given, then the tele- porting request will only succeed if the source machine specifies the same password as the one given with this command.

• --cpuid <leaf> <eax> <ebx> <ecx> <edx>: Advanced users can use this command be- fore a teleporting operation to restrict the virtual CPU capabilities that VirtualBox presents to the guest operating system. This must be run on both the source and the target machines involved in the teleporting and will then modify what the guest sees when it executes the CPUID machine instruction. This might help with misbehaving applications that wrongly assume that certain CPU capabilities are present. The meaning of the parameters is hard- ware dependent; please refer to the AMD or Intel processor manuals.

8.8 VBoxManage import

This command imports a virtual appliance in OVF format by copying the virtual disk images and creating virtual machines in VirtualBox. See chapter 1.11,Importing and exporting virtual machines, page24for an introduction to appliances.

Theimportsubcommand takes at least the path name of an OVF file as input and expects the disk images, if needed, in the same directory as the OVF file. A lot of additional command- line options are supported to control in detail what is being imported and modify the import parameters, but the details depend on the content of the OVF file.

It is therefore recommended to first run the import subcommand with the--dry-runor-n option. This will then print a description of the appliance’s contents to the screen how it would be imported into VirtualBox, together with the optional command-line options to influence the import behavior.

As an example, here is the screen output with a sample appliance containing a Windows XP guest:

VBoxManage import WindowsXp.ovf --dry-run Interpreting WindowsXp.ovf...

OK.

Virtual system 0:

0: Suggested OS type: "WindowsXP"

(change with "--vsys 0 --ostype <type>"; use "list ostypes" to list all) 1: Suggested VM name "Windows XP Professional_1"

(change with "--vsys 0 --vmname <name>") 3: Number of CPUs: 1

(change with "--vsys 0 --cpus <n>")

4: Guest memory: 956 MB (change with "--vsys 0 --memory <MB>") 5: Sound card (appliance expects "ensoniq1371", can change on import)

(disable with "--vsys 0 --unit 5 --ignore") 6: USB controller

(disable with "--vsys 0 --unit 6 --ignore")

7: Network adapter: orig bridged, config 2, extra type=bridged 8: Floppy

(disable with "--vsys 0 --unit 8 --ignore") 9: SCSI controller, type BusLogic

(change with "--vsys 0 --unit 9 --scsitype {BusLogic|LsiLogic}"; disable with "--vsys 0 --unit 9 --ignore")

10: IDE controller, type PIIX4

(disable with "--vsys 0 --unit 10 --ignore") 11: Hard disk image: source image=WindowsXp.vmdk,

target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0 (change controller with "--vsys 0 --unit 11 --controller <id>"; disable with "--vsys 0 --unit 11 --ignore")

As you can see, the individual configuration items are numbered, and depending on their type support different command-line options. The import subcommand can be directed to ignore many such items with a--vsys X --unit Y --ignoreoption, where X is the number of the virtual system (zero unless there are several virtual system descriptions in the appliance) and Y the item number, as printed on the screen.

In the above example, Item #1 specifies the name of the target machine in VirtualBox. Items #9 and #10 specify hard disk controllers, respectively. Item #11 describes a hard disk image;

in this case, the additional--controlleroption indicates which item the disk image should be connected to, with the default coming from the OVF file.

You can combine several items for the same virtual system behind the same--vsysoption. For example, to import a machine as described in the OVF, but without the sound card and without the USB controller, and with the disk image connected to the IDE controller instead of the SCSI controller, use this:

VBoxManage import WindowsXp.ovf

--vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10

8.9 VBoxManage export

This command exports one or more virtual machines from VirtualBox into a virtual appliance in OVF format, including copying their virtual disk images to compressed VMDK. See chapter1.11,

Importing and exporting virtual machines, page24for an introduction to appliances.

Theexportcommand is simple to use: list the machine (or the machines) that you would like to export to the same OVF file and specify the target OVF file after an additional--outputor-o option. Note that the directory of the target OVF file will also receive the exported disk images in the compressed VMDK format (regardless of the original format) and should have enough disk space left for them.

Beside a simple export of a given virtual machine, you can append several product information to the appliance file. Use--product,--producturl,--vendor,--vendorurland--version to specify this additional information. For legal reasons you may add a license text or the content of a license file by using the--eulaand--eulafileoption respectively. As with OVF import, you must use the --vsys X option to direct the previously mentioned options to the correct virtual machine.

For virtualization products which aren’t fully compatible with the OVF standard 1.0 you can enable a OVF 0.9 legacy mode with the--legacy09option.

8.10 VBoxManage startvm

This command starts a virtual machine that is currently in the “Powered off” or “Saved” states.

Note: This is provided for backwards compatibility only. We recommend to start virtual

machines directly by running the respective front-end, as you might otherwise miss im- portant error and state information that VirtualBox may display on the console. This is especially important for front-ends other than VirtualBox, our graphical user in- terface, because those cannot display error messages in a popup window. See chapter

7.1.2,VBoxHeadless, the VRDP-only server, page88for more information.

The optional--typespecifier determines whether the machine will be started in a window (GUI mode, which is the default) or whether the output should go throughVBoxHeadless, with VRDP enabled or not; see chapter7.1.2, VBoxHeadless, the VRDP-only server, page88for more information. The list of types is subject to change, and it’s not guaranteed that all types are accepted by any product variant.

The following values are allowed:

gui Starts a VM showing a GUI window. This is the default.

vrdp Starts a VM showing a GUI window, with its graphics card output accessible by an RDP client.

8.11 VBoxManage controlvm

Thecontrolvmsubcommand allows you to change the state of a virtual machine that is currently running. The following can be specified:

• VBoxManage controlvm <vm> pausetemporarily puts a virtual machine on hold, without changing its state for good. The VM window will be painted in gray to indicate that the VM is currently paused. (This is equivalent to selecting the “Pause” item in the “Machine” menu of the GUI.)

• UseVBoxManage controlvm <vm> resumeto undo a previouspausecommand. (This is equivalent to selecting the “Resume” item in the “Machine” menu of the GUI.)

• VBoxManage controlvm <vm> resethas the same effect on a virtual machine as pressing the “Reset” button on a real computer: a cold reboot of the virtual machine, which will restart and boot the guest operating system again immediately. The state of the VM is not saved beforehand, and data may be lost. (This is equivalent to selecting the “Reset” item in the “Machine” menu of the GUI.)

• VBoxManage controlvm <vm> poweroff has the same effect on a virtual machine as pulling the power cable on a real computer. Again, the state of the VM is not saved be- forehand, and data may be lost. (This is equivalent to selecting the “Close” item in the “Machine” menu of the GUI or pressing the window’s close button, and then selecting “Power off the machine” in the dialog.)

After this, the VM’s state will be “Powered off”. From there, it can be started again; see chapter8.10,VBoxManage startvm, page111.

• VBoxManage controlvm <vm> savestate will save the current state of the VM to disk and then stop the VM. (This is equivalent to selecting the “Close” item in the “Machine” menu of the GUI or pressing the window’s close button, and then selecting “Save the ma- chine state” in the dialog.)

After this, the VM’s state will be “Saved”. From there, it can be started again; see chapter

8.10,VBoxManage startvm, page111.

• VBoxManage controlvm <vm> teleport --hostname <name> --port <port> [--password <password>]makes the machine the source of a teleporting operation and initiates a tele- port to the given target. See chapter 7.2, Teleporting, page 93for an introduction. If the optional password is specified, it must match the password that was given to themodifyvm command for the target machine; see chapter 8.7.5, Teleporting settings, page 109 for details.

A few extra options are available withcontrolvmthat do not directly affect the VM’s running state:

• The setlinkstate<1-N>operation connects or disconnects virtual network cables from their network interfaces.

• nic<1-N> null|nat|bridged|intnet|hostonly: With this, you can set, for each of the VM’s virtual network cards, what type of networking should be available. They can be not connected to the host (null), use network address translation (nat), bridged net- working (bridged) or communicate with other virtual machines using internal network- ing (intnet) or host-only networking (hostonly). These options correspond to the modes which are described in detail in chapter6.2,Introduction to networking modes, page81. • usbattachandusbdettachmake host USB devices visible to the virtual machine on the

fly, without the need for creating filters first. The USB devices can be specified by UUID (unique identifier) or by address on the host system.

• vrdp on|offlets you enable or disable the built-in VRDP server.

• vrdpport default|<ports> changes the port or a range of ports that the VRDP server can bind to; “default” or “0” means port 3389, the standard port for RDP. For details, see the description for the --vrdpportoption in chapter8.7.3, Serial port, audio, clipboard, VRDP and USB settings, page108.

• setvideomodehintrequests that the guest system change to a particular video mode. This requires that the Guest Additions be installed, and will not work for all guest systems. • Thesetcredentialsoperation is used for remote logons in Windows guests. For details,

please refer to chapter9.3,Automated guest logons, page128.

• Theguestmemoryballoonoperation changes the size of the guest memory balloon, that is, memory allocated by the VirtualBox Guest Additions from the guest operating system and returned to the hypervisor for re-use by other virtual machines. This must be specified in megabytes. For details, see chapter4.8,Memory ballooning, page66.

8.12 VBoxManage discardstate

This command discards the saved state of a virtual machine which is not currently running, which will cause its operating system to restart next time you start it. This is the equivalent of pulling out the power cable on a physical machine, and should be avoided if possible.

8.13 VBoxManage snapshot

This command is used to control snapshots from the command line. A snapshot consists of a complete copy of the virtual machine settings, copied at the time when the snapshot was taken, and optionally a virtual machine saved state file if the snapshot was taken while the machine was running. After a snapshot has been taken, VirtualBox creates differencing hard disk for each normal hard disk associated with the machine so that when a snapshot is restored, the contents of the virtual machine’s virtual hard disks can be quickly reset by simply dropping the pre-existing differencing files.

Thetake operation takes a snapshot of the current state of the virtual machine. You must supply a name for the snapshot and can optionally supply a description. The new snapshot is inserted into the snapshots tree as a child of the current snapshot and then becomes the new current snapshot.

Thedelete operation deletes a snapshot (specified by name or by UUID). This can take a while to finish since the differencing images associated with the snapshot might need to be merged with their child differencing images.

Therestore operation will restore the given snapshot (specified by name or by UUID) by resetting the virtual machine’s settings and current state to that of the snapshot. The previous current state of the machine will be lost. After this, the given snapshot becomes the new “current” snapshot so that subsequent snapshots are inserted under the snapshot from which was restored. Therestorecurrentoperation is a shortcut to restore the current snapshot (i.e. the snapshot from which the current state is derived). This subcommand is equivalent to using the “restore” subcommand with the name or UUID of the current snapshot, except that it avoids the extra step of determining that name or UUID.

With theeditoperation, you can change the name or description of an existing snapshot. With theshowvminfooperation, you can view the virtual machine settings that were stored with an existing snapshot.