When running VBoxManage without parameters or when supplying an invalid command line, the syntax diagram will be shown.The Linux and Windows versions are slightly different, to re ect differences between these operating systems. When in
doubt, check the output of VBoxManage for the commands available on a particular
host system. The following diagram shows a superset of all commands understood by
VBoxManage:
VirtualBox Command Line Management Interface Version 1.3.99
(C) 2005-2007 innotek GmbH
Usage:
VBoxManage list vmsostypeshostdvdshostfloppieshostifs
hddsdvdsfloppiesusbhostusbfilters
systemproperties
VBoxManage showvminfo
[-details]
VBoxManage registervm
VBoxManage unregistervm
[-delete]
VBoxManage createvm -name
[-register]
[-basefolder -settingsfile ]
VBoxManage modifyvm
[-name ]
[-ostype ]
[-memory ]
[-vram ]
[-acpi onoff]
[-ioapic onoff]
[-hwvirtex onoffdefault]
[-bioslogofadein onoff]
[-bioslogofadeout onoff]
[-bioslogodisplaytime ]
[-bioslogoimagepath ]
[-biosbootmenu disabledmenuonlymessageandmenu]
[-biossystemtimeoffset ]
[-boot<1-4> nonefloppydvddisknet>]
[-hd none]
[-dvd nonehost:]
[-dvdpassthrough onoff]
[-floppy disabledempty
host:]
[-nic<1-n> nonenullnathostifintnet]
[-nictype<1-n> Am79C970AAm79C973]
[-cableconnected<1-n> onoff]
[-nictrace<1-n> onoff]
[-nictracefile<1-n> ]
[-hostifdev<1-n> none]
[-intnet<1-n> network]
[-macaddress<1-n> auto
[-tapsetup<1-n> none]
[-tapterminate<1-n> none]
[-audio nonenullwinmmdsoundossalsa]
[-clipboard disabledhosttoguestguesttohost
bidirectional]
[-vrdp onoff]
[-vrdpport default]
[-vrdpaddress ]
[-vrdpauthtype nullexternalguest]
[-vrdpmulticon onoff]
[-usb onoff]
[-snapshotfolder default]
VBoxManage startvm
[-type guivrdp]
VBoxManage controlvm
pauseresumeresetpoweroffsavestate
acpipowerbutton
setlinkstate<1-4> onoff
usbattach
usbdetach
dvdattach nonehost:
floppyattach nonehost:
setvideomodehint
setcredentials
[-allowlocallogon ]
VBoxManage discardstate
VBoxManage snapshot
take [-desc ]
discard
discardcurrent -state-all
edit -current
[-newname ]
[-newdesc ]
showvminfo
VBoxManage registerimage diskdvdfloppy
[-type normalimmutablewritethrough] (disk only)
VBoxManage unregisterimage diskdvdfloppy
VBoxManage showvdiinfo
VBoxManage createvdi -filename
-size
[-static]
[-comment
] [-apply]
[-nobackup] [-skipinvalid]
Each time VBoxManage is invoked, only one command can be executed. However, a command might support several subcommands which then can be invoked in one single call. The following sections provide detailed reference information on the different commands.
The list command gives relevant information about your system and information about irtualBox’s current settings.
The following subcommands are available with VBoxManage list:
• vms, hdds, dvds and floppies all give you information about virtual machines and virtual disk images currently registered in VirtualBox, including all their settings, the unique identifiers (UUIDs) associated with them by VirtualBox and all files associated with them.
• ostypes lists all guest operating systems presently known to VirtualBox, along with the identifiers used to refer to them with the modifyvm command.
• hostdvds, hostfloppies and hostifs, respectively, list DVD, oppy and host networking interfaces on the host, along with the name used to access them from within VirtualBox.
• hostusb supplies information about USB devices attached to the host, notably information useful for constructing USB filters and whether they are currently in use by the host.
• usbfilters lists all global USB filters registered with VirtualBox – that is, filters for devices which are accessible to all virtual machines – and displays the filter parameters.
• systemproperties displays some global VirtualBox settings, such as minimum and maximum guest RAM and virtual hard disk size, folder settings and the current authentication library in use.
VBoxManage showvminfo
The showvminfo command shows information about a particular virtual machine.
This is the same information as VBoxManage list vms would show for all virtual machines.
You will get information similar to the following:
$ VBoxManage showvminfo "Windows XP"
VirtualBox Command Line Management Interface Version 1.4.0
(C) 2005-2007 innotek GmbH
All rights reserved.
Name: Windows XP
Guest OvS: Other/Unknown
UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7
Config file: /home/username/.VirtualBox/Machines/Windows XP/Windows XP.xml
Memory size: 128MB
VRAM size: 8MB
Boot menu mode: message and menu
ACPI: on
IOAPIC: off
Hardw. virt.ext: off
State: powered off
Floppy: empty
DVD: empty
NIC 1: disabled
NIC 2: disabled
NIC 3: disabled
NIC 4: disabled
Audio: disabled (Driver: Unknown)
VRDP: disabled
USB: disabled
USB Device Filters:
Shared folders:
The registervm command allows you to import a virtual machine definition in an XML file into VirtualBox. There are some restrictions here: the machine must not con ict with one already registered in VirtualBox and it may not have any hard or removable disks attached. It is advisable to place the definition file in the machines folder before registering it.
Note: When creating a new virtual machine with VBoxManage createvm (see below), you can directly specify the -register option to avoid having to register it separately.
The unregistervm command unregisters a virtual machine. If -delete is also specified then the XML definition file will be deleted.
VBoxManage createvm
This command creates a new XML virtual machine definition file.
The -name parameter is required and must specify the name of the machine. Since this name is used by default as the file name of the settings file (with the extension .xml) and the machine folder (a subfolder of the .VirtualBox/Machines folder), it must conform to your host operating system’s requirements for file name specifications. If the VM is later renamed, the file and
folder names will change automatically.
However, if the -basefolder and the -settingsfile options are used, the XML definition file will be given the name and the machine folder will be named . In this case, the names of the file and the
folder will not change if the virtual machine is renamed.
By default, this command only creates the XML file without automatically registering the VM with your VirtualBox installation. To register the VM instantly, use the optional -register option, or run VBoxManage registervm separately afterwards.
VBoxManage modifyvm
This command changes the properties of a registered virtual machine. Most of the properties that this command makes available correspond to the VM settings that VirtualBox graphical user interface displays in each VM’s “Settings” dialog.
Some of the more advanced settings, however, are only available through the VBoxManage interface.
The following settings are available through VBoxManage modifyvm:
• -name : This changes the VM’s name and possibly renames the internal virtual machine files, as described with VBoxManage createvm above.
• -ostype : This specifies what guest operating system is supposed to run in the VM.
this setting is presently purely descriptive. To learn about the various identifiers that can be used here, use VBoxManage list ostypes.
• -memory : This sets the amount of RAM, in MB, that the virtual machine should allocate for itself from the host. Again, see the remarks in chapter 3.2, Creating a virtual machine, page 23 for more information.
• -vram : This sets the amount of RAM that the virtual graphics card should have. See chapter 3.7.1, General settings, page 37 for details.
• -acpi onoff; -ioapic onoff: These two determine whether the VM
should have ACPI and I/O APIC support, respectively.
• -hwvirtex onoffdefault: This enables or disables the use of virtualiza-
tion extensions in the processor of your host system. This feature may still be
experimental at the time you read this, and may not be enabled in your build of
VirtualBox.
• You can in uence the BIOS logo that is displayed when a virtual machine starts up with a number of settings. Per default, an “innotek” logo is displayed.
With -bioslogofadein onoff and -bioslogofadeout onoff, you can determine whether the logo should fade in and out, respectively.
With -bioslogodisplaytime you can set how long the logo should be visible, in milliseconds.
With -bioslogoimagepath you can, if you are so inclined, replace the image that is shown, with your own logo. The image must be an uncompressed 256 color BMP file.
• -biosbootmenu disabledmenuonlymessageandmenu: This specifies whether the BIOS allows the user to select a temporary boot device. menuonly suppresses the message, but the user can still press F12 to select a temporary boot device.
• -boot<1-4> nonefloppydvddisknet: This specifies the boot order for the virtual machine. There are four “slots”, which the VM will try to access from 1 to 4, and for each of which you can set a device that the VM should attempt to boot from.
• -hd none: This specifies the settings for
each of the three virtual hard disks that can be attached to a VM (primary master and slave, and secondary slave; the secondary master is always reserved for the virtual CD/DVD drive). For each of ;
• -dvd nonehost:: This specifies what
VirtualBox should provide to the VM as the virtual CD/DVD drive; specify either the UUID or the filename of an image file that you have registered with VBoxManage registerimage • -dvdpassthrough onoff: With this, you can enable DVD writing support
(currently experimental.
• -floppy disabledemptyhost:: This is the oppy equivalent to the -dvd option described above. disabled completely disables the oppy controller, whereas empty keeps the oppy controller
enabled, but without a media inserted.
• -nic<1-n> nonenullnathostifintnet: 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 present (none), not connected to the host (null), use network address translation (nat), a host interface (hostif) or communicate with other virtual machines using internal networking (intnet).
• -nictype<1-n> Am79C970AAm79C973: This allows you, for each of the VM’s virtual network cards, to specify whether the host will see the network adaptors as 10 Mbps AMD PCnet 79C970A cards or as 100Mbps 79C973 cards.
This is in fact purely cosmetic, as both virtual cards run at full speed.
• -cableconnected<1-n> onoff: This allows you to temporarily disconnect a virtual network interface, as if a network cable had been pulled from a real
network card. This might be useful for resetting certain software components in
the VM.
• With the “nictrace” options, you can optionally trace network traffic, for debugging purposes. With -nictrace<1-n> onoff, you can enable network tracing for a particular virtual network card.
If enabled, you must specify with -nictracefile<1-n> what file the trace should be logged to.
• -hostifdev<1-n> none: If host interface networking has been enabled for a virtual network card (see the -nic option above; otherwise this setting has no effect), use this option to specify which host interface the given virtual network interface will use.
• -intnet<1-n> network: If internal networking has been enabled for a virtual network card (see the -nic option above; otherwise this setting has no effect), use this option to specify the name of the internal network
• -macaddress<1-n> auto: With this option you can set the MAC address of the virtual network card. Per default, each virtual network card is assigned a random address by VirtualBox at VM creation.
• -audio nonenulloss: With this option, you can set whether the VM should have audio support.
• -clipboard -clipboard disabledhosttoguestguesttohost bidirectional: With this setting, you can select whether the guest operating system’s clipboard should be shared with the host.
• -vrdp onoff: With the VirtualBox graphical user interface, this enables or disables the built-in VRDP server. Note that if you are using VBoxVRDP, our headless server described in chapter 7.4.1, VBoxVRDP, the headless VRDP server,
page 72, VRDP output is always enabled.
• -vrdpport default: This lets you specify which port should be used; “default” or “0” means port 3389, the standard port for RDP. Only one machine can use a given port at a time.
• -vrdpauthtype nullexternalguest: This allows you to choose whether and how authorization will be performed; see chapter 7.4.4, RDP authentication.
• -usb onoff: This option enables or disables the VM’s virtual USB controller; see chapter 3.7.6.1, USB settings.
• -snapshotfolder default: This allows you to specify the folder in which snapshots will be kept for a virtual machine.
VBoxManage startvm
This command starts a virtual machine that is currently in the “Powered off” or “Saved”
states. This is provided for backwards compatibility only.
The optional -type specifier determines whether the machine will be started in a window (GUI mode, which is the default) or whether the output should go through VBoxVRDP, the headless VRDP server; see chapter 7.4.1, VBoxVRDP, the headless VRDP server.
Note: We recommend to start virtual machines directly by running the respective front-end, as you might otherwise miss important error and state information that VirtualBox may display on the console. This is especially important for front-ends other than VirtualBox, our graphical user interface, because those cannot display error messages in a popup window.
VBoxManage controlvm
The controlvm subcommand allows you to change the state of a virtual machine that is currently running. The following can be specified:
• VBoxManage controlvm pause temporarily 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 “VM” menu of the GUI.)
• Use VBoxManage controlvm resume to undo a previous pause command. (This is equivalent to selecting the “Resume” item in the “VM” menu of the GUI.)
• VBoxManage controlvm reset has 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 “VM” menu of the GUI.)
• VBoxManage controlvm 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 beforehand, and data may be lost. (This is equivalent to selecting the “Close” item in the “VM” 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”.
• VBoxManage controlvm 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 “VM” menu of the GUI or pressing the window’s close button, and then selecting “Save the machine state” in the dialog.)
After this, the VM’s state will be “Saved”.
A few extra options are available with controlvm that do not directly affect the VM’s running state:
• The setlinkstate<1-4> operation connects or disconnects virtual network cables from their network interfaces
• usbattach and usbdettach make host USB devices visible to the virtual machine on the y, without the need for creating filters first. The USB devices can be specified by UUID (unique identifier) or by address on the host system.
You can use VBoxManage list usbhost to locate this information.
• dvdattach inserts a DVD image into the virtual machine or connects it to the host DVD drive. With this command (as opposed to VBoxManage modifyvm), the image file does not first have to be registered with VirtualBox.
You can use VBoxManage list hostdvds to display all the drives found on the host and the names VirtualBox uses to access them.
• floppyattach works in a similar way.
• setvideomodehint requests 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.
• The setcredentials operation is used for remote logons in Windows guests.
For details, please refer to chapter 9.2, Automated Windows guest logons.
VBoxManage discardstate
This command discards the saved state of a virtual machine which is not currentlyrunning, which will cause its operating system to restart next time you start it. Thisis the equivalent of pulling out the power cable on a physical machine, and should beavoided if possible.
VBoxManage snapshot
This command is used for taking snapshots of a virtual machine and for manipulatingand discarding snapshots.
The take operation takes a snapshot of a virtual machine. You must supply a namefor the snapshot and can optionally supply a description.The discard operation discards a snapshot specified by name or by identifier(UUID).
The discardcurrent operation will either revert the current state to the mostrecent snapshot (if you specify the -state option) or discard the last snapshot andrevert to the last but one (with the -all option).
VBoxManage registerimage / unregisterimage
These commands register or unregister hard disk, DVD or oppy images in VirtualBox.
This is the command-line equivalent of the Virtual Disk Manager.Note however that when you unregister a hard disk image using VBoxManage, itwill not be deleted from the host computer’s hard drive.
VBoxManage showvdiinfo
This command shows information about a virtual hard disk image, notably its size, itssize on disk, its type and the VM it is in use by.
VBoxManage createvdi
This command creates a new virtual hard disk image. You must specify the filenamefor the new image and the virtual size. If you give the -static option, disk space forthe whole image will be allocated at once on the host. With the -comment option youcan attach a comment to the image. The -register option, if given, tells VirtualBoxto register the image for use with virtual machines.
You can use the -type option to create a disk in write-through mode, which willnot be affected by snapshots.
VBoxManage modifyvdi
The modifyvdi command can be used to compact disk images, i.e. remove blocksthat only contains zeroes. For this operation to be effective, it is required to zero outfree space in the guest system using a suitable software tool.
This command duplicates a registered virtual hard disk image to a new image file witha new unique identifier (UUID). The new image can be transferred to another hostsystem or imported into VirtualBox again using the Virtual Disk Manager.
VBoxManage addiscsidisk
The addiscsidisk command attaches an iSCSI network storage unit to VirtualBox.The iSCSI target can then be made available to and used by a virtual machine asthough it were a standard write-through virtual disk image.This command has the following syntax:
VBoxManage addiscsidisk -server
-target
[-port ]
[-lun ]
[-username ]
[-password ]
[-comment]
where the parameters mean:server The host name or IP address of the iSCSI target.target Target name string. This is determined by the iSCSI target and used to identifythe storage resource.port TCP/IP port number of the iSCSI service on the target (optional).lun Logical Unit Number of the target resource (optional). Often, this value is zero.username, password Username and password for target authentication, if required(optional).
Note: Currently, username and password are stored without encryption (i.e.in cleartext) in the machine configuration file.comment Any description that you want to have stored with this item (optional; e.g.“Big storage server downstairs”). This is stored internally only and not neededfor operation.
VBoxManage createhostif/removehostif
These two commands add and remove, respectively, virtual network interfaces on Windows hosts. See chapter 6.4, Host interface networking on Windows hosts.
VBoxManage getextradata/setextradata
These commands let you attach and retrieve string data to a virtual machine or to aVirtualBox configuration (by specifying global instead of a virtual machine name).You must specify a key (as a text string) to associate the data with, which you can lateruse to retrieve it. For example:
VBoxManage setextradata Fedora5 installdate 2006.01.01
VBoxManage setextradata SUSE10 installdate 2006.02.02
would associate the string “2006.01.01” with the key installdate for the virtual machine Fedora5, and “2006.02.02” on the machine SUSE10. You could retrieve theinformation as follows:VBoxManage getextradata Fedora5 installdatewhich would returnVirtualBox Command Line Management Interface Version 1.4.0(C) 2005-2007 innotek GmbHAll rights reserved.
Value: 2006.01.01
VBoxManage setproperty
This command is used to change global settings which affect the entire VirtualBoxinstallation. Some of these correspond to the settings in the “Global settings” dialog inthe graphical user interface. The following properties are available:
vdifolder This specifies the default folder that is used to keep Virtual Disk Image(VDI) files.
machinefolder This specifies the default folder in which virtual machine definitions are kept.
vrdpauthlibrary This specifies which library to use when “external” VRDP authentication has been selected for a particular virtual machine.
hwvirtexenabled This selects whether or not hardware virtualization support is enabled by default. Note: This feature may still be experimental at the time youread this.
VBoxManage usbfilter add/modify/remove
The usbfilter commands are used for working with USB filters in virtual machines,or global filters which affect the whole VirtualBox setup. Global filters are applied before machine-specific filters, and may be used to prevent devices from being capturedby any virtual machine. Global filters are always applied in a particular order, and onlythe first filter which fits a device is applied. So for example, if the first global filter saysto hold (make available) a particular Kingston memory stick device and the second toignore all Kingston devices, that memory stick will be available to any machine withan appropriate filter, but no other Kingston device will.
When creating a USB filter using usbfilter add, you must supply three or fourmandatory parameters. The index specifies the position in the list at which the filtershould be placed. If there is already a filter at that position, then it and the followingones will be shifted back one place. Otherwise the new filter will be added onto theend of the list. The target parameter selects the virtual machine that the filter shouldbe attached to or use “global” to apply it to all virtual machines. name is a name forthe new filter and for global filters, action says whether to allow machines accessto devices that fit the filter description (“hold”) or not to give them access (“ignore”).
In addition, you should specify parameters to filter by. You can find the parametersfor devices attached to your system using VBoxManage list usbhost. Finally, youcan specify whether the filter should be active, and for local filters, whether they arefor local devices, remote (over an RDP connection) or either.
When you modify a USB filter using usbfilter modify, you must specify thefilter by index (see the output of VBoxManage list usbfilters to find globalfilter indexes and that of VBoxManage howvminfo to find indexes for individualmachines) and by target, which is either a virtual machine or “global”. The propertieswhich can be changed are the same as for usbfilter add. To remove a filter, useusbfilter remove and specify the index and the target.
VBoxManage sharedfolder add/remove
This command allows you to share folders on the host computer with guest operating systems. For this, the guest systems must have a version of the VirtualBox guestadditions installed which supports this functionality.
VBoxManage updatesettings
The updatesettings command updates all VirtualBox configuration files from anearlier to the current version. You will need this when you upgrade your version ofVirtualBox, but should not need it apart from that.
0 comments:
Post a Comment