8 VBoxManage
Introduction
As briefly mentioned in Alternative Front-Ends, VBoxManage is the command-line interface to Oracle VM VirtualBox. With it, you can completely control Oracle VM VirtualBox from the command line of your host operating system. VBoxManage supports all the features that the graphical user interface gives you access to, but it supports a lot more than that. It exposes all the features of the virtualization engine, even those that cannot be accessed from the GUI.
You will need to use the command line if you want to do the following:
-
Use a different user interface than the main GUI such as the VBoxHeadless server.
-
Control some of the more advanced and experimental configuration settings for a VM.
There are two main things to keep in mind when using VBoxManage. First, VBoxManage must always be used with a specific subcommand, such as list or createvm or startvm. All the subcommands that VBoxManage supports are described in detail in VBoxManage.
Second, most of these subcommands require that you specify a particular virtual machine after the subcommand. There are two ways you can do this:
-
You can specify the VM name, as it is shown in the Oracle VM VirtualBox GUI. Note that if that name contains spaces, then you must enclose the entire name in double quotes. This is always required with command line arguments that contain spaces. For example:
VBoxManage startvm "Windows XP"
-
You can specify the UUID, which is the internal unique identifier that Oracle VM VirtualBox uses to refer to the virtual machine. Assuming that the VM called "Windows XP" has the UUID shown below, the following command has the same effect as the previous example:
VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5
You can enter VBoxManage list vms to have all currently registered VMs listed with all their settings, including their respective names and UUIDs.
Some typical examples of how to control Oracle VM VirtualBox from the command line are listed below:
-
To create a new virtual machine from the command line and immediately register it with Oracle VM VirtualBox, use VBoxManage createvm with the --register option, as follows:
$ VBoxManage createvm --name "SUSE 10.2" --register VirtualBox Command Line Management Interface Version version-number (C) 2005-2018 Oracle Corporation All rights reserved. Virtual machine 'SUSE 10.2' is created. UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5 Settings file: '/home/username/.config/VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'As can be seen from the above output, a new virtual machine has been created with a new UUID and a new XML settings file.
For more details, see VBoxManage createvm.
-
To show the configuration of a particular VM, use VBoxManage showvminfo. See VBoxManage showvminfo for details and an example.
-
To change settings while a VM is powered off, use VBoxManage modifyvm. For example:
VBoxManage modifyvm "Windows XP" --memory 512
See also VBoxManage modifyvm.
-
To change the storage configuration, such as to add a storage controller and then a virtual disk, use VBoxManage storagectl and VBoxManage storageattach. See VBoxManage storagectl and VBoxManage storageattach.
-
To control VM operation, use one of the following:
-
To start a VM that is currently powered off, use VBoxManage startvm. See VBoxManage startvm.
-
To pause or save a VM that is currently running or change some of its settings, use VBoxManage controlvm. See VBoxManage controlvm.
-
Commands Overview
When running VBoxManage without parameters or when supplying an invalid command line, the following command syntax list is shown. Note that the output will be slightly different depending on the host platform. If in doubt, check the output of VBoxManage for the commands available on your particular host.
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 then different commands.
General Options
-
-v|--version: Show the version of this tool and exit.
-
--nologo: Suppress the output of the logo information. This option is useful for scripts.
-
--settingspw: Specify a settings password.
-
--settingspwfile: Specify a file containing the settings password.
The settings password is used for certain settings which need to be stored in encrypted form for security reasons. At the moment, the only encrypted setting is the iSCSI initiator secret, see VBoxManage storageattach. As long as no settings password is specified, this information is stored in plain text. After using the --settingspw|--settingspwfile option once, it must be always used. Otherwise, the encrypted setting cannot be unencrypted.
VBoxManage
Oracle VM VirtualBox command-line interface
Synopsis
Description
The VBoxManage command is the command-line
interface (CLI) for the Oracle VM VirtualBox software. The CLI supports
all the features that are available with the Oracle VM VirtualBox
graphical user interface (GUI). In addition, you can use the
VBoxManage command to manage the features of
the virtualization engine that cannot be managed by the GUI.
Each time you invoke the VBoxManage command,
only one command is executed. Note that some
VBoxManage subcommands invoke several
subcommands.
Run the VBoxManage command from the command
line of the host operating system (OS) to control Oracle VM VirtualBox
software.
The VBoxManage command is stored in the
following locations on the host system:
-
Linux:
/usr/bin/VBoxManage -
Mac OS X:
/Applications/VirtualBox.app/Contents/MacOS/VBoxManage -
Oracle Solaris:
/opt/VirtualBox/bin/VBoxManage -
Windows:
C:\Program Files\Oracle\VirtualBox\VBoxManage.exe
In addition to managing virtual machines (VMs) with this CLI or
the GUI, you can use the VBoxHeadless CLI to
manage VMs remotely.
The VBoxManage command performs particular
tasks by using subcommands, such as list,
createvm, and startvm. See
the associated information for each VBoxManage
subcommand.
If required, specify the VM by its name or by its Universally Unique Identifier (UUID).
Use the VBoxManage list vms command to obtain
information about all currently registered VMs, including the VM
names and associated UUIDs.
Note that you must enclose the entire VM name in double quotes if it contains spaces.
General Options
- --nologo
-
Suppresses the output of the logo information, which is useful for scripts.
The short version of this option is -q.
- --settingspw=[ password ]
-
Specifies the settings password. You can optionally specify the password as an argument to this option. If you do not specify the password in this way, the
VBoxManagecommand prompts you for the password.The settings password is a security feature that encrypts stored settings, which are stored as plain text by default.
You cannot unencrypt encrypted settings. So, if the settings are encrypted, you must continue to specify the --settingspw or --settingspwfile option.
Only the iSCSI secret is encrypted at this time.
- --settingspwfile= pw-filename
-
Specifies the file that contains the settings password.
- --version
-
Shows version information about the
VBoxManagecommand.The short version of this option is -V.
- @response-file
-
Loads arguments from the specified Bourne shell response file.
- subcommand
-
Specifies one of the
VBoxManagesubcommands, such ascontrolvm,createvm,list,modifyvm,showvminfo,startvm,storageattach, andstoragectl.Each subcommand is described in its own command topic, some of which are shown in See Also sections.
Examples
The following command creates a virtual machine called
Win8 and registers it with Oracle VM VirtualBox by
using the --register option.
$ VBoxManage createvm --name "Win8" --register Virtual machine 'Win8' is created. UUID: UUID-string Settings file: '/home/username/VirtualBox VMs/Win8/Win8.vbox'
The command output shows that the Win8 VM is
assigned a UUID and an XML machine settings file.
You can use the VBoxManage showvminfo command
to view the configuration information of a VM.
The following example uses the VBoxManage
modifyvm command to change the amount of memory for the
Windows XP VM to be 1024 megabytes:
$ VBoxManage modifyvm "Windows XP" --memory 1024
Note that you can use the VBoxManage modifyvm
command even when the VM is powered off.
You can use the VBoxManage storagectl command
or the VBoxManage storageattach command to
modify the storage configuration for a VM. For example, to create
a SATA storage controller called sata01 and add
it to the ol7 VM:
$ VBoxManage storagectl ol7 --name "sata01" --add sata
Use the VBoxManage startvm command to start a
VM that is currently powered off. For example, to start the
win7 VM:
$ VBoxManage startvm win7
Use the VBoxManage controlvm command to pause
or save a VM that is currently running. You can also use this
command to modify settings for the VM. For example, to enable
audio input for the ol6u9 VM.
$ VBoxManage controlvm ol6u9 audioin on
VBoxManage adoptstate
Change a virtual machine's state based on a saved state file
Description
The VBoxManage adoptstate command enables you
to change the state of a virtual machine (VM) to a state described
in a saved state file (.sav). This action is
referred to as a VM adopting a saved state
file. The saved state file must be separate from the VM
configuration.
When you start the VM after adopting the saved state, the VM restores its state from the saved state file.
Only use this command for custom deployments.
- uuid | vmname
-
Specifies the Universally Unique Identifier (UUID) or name of the VM.
- state-filename
-
Specifies the name of the saved state file.
VBoxManage bandwidthctl
Manage bandwidth groups
Synopsis
Description
The VBoxManage bandwidthctl command enables you
to manage bandwidth groups for virtual machines (VMs). A bandwidth
group specifies the bandwidth limit for the disks or for the
network adapters of a VM.
Note that a network bandwidth limit applies only to the outbound traffic from the VM. The inbound traffic is unlimited.
Create a Bandwidth Group
The VBoxManage bandwidthctl add command
creates a bandwidth group for the specified VM. You must specify
whether the bandwidth group is for disks or for networks, and
specify the bandwidth limit.
- uuid | vmname
-
Specifies the Universally Unique Identifier (UUID) or the name of the VM.
- bandwidth-group-name
-
Specifies the name of the bandwidth group.
- --type=disk|network
-
Specifies the type of the bandwidth group:
diskandnetwork. For more information, see Limiting Bandwidth for Disk Images or Limiting Bandwidth for Network Input/Output. - --limit= bandwidth-limit [k|m|g|K|M|G]
-
Specifies the bandwidth limit for a bandwidth group. The default unit is megabytes per second. You can modify this value while the VM is running.
You can change the unit by appending one of the following unit specifiers to the bandwidth limit:
-
k– kilobits per second -
m– megabits per second -
g– gigabits per second -
K– kilobytes per second -
M– megabytes per second -
G– gigabytes per second
-
List Bandwidth Groups
The VBoxManage bandwidthctl list command
lists the all the bandwidth groups that have been defined for
the specified VM. Use the --machinereadable
option to produce the output in a machine-readable format, which
uses name-value pairs.
- uuid | vmname
-
Specifies the UUID or the name of the VM.
- --machinereadable
-
Outputs the information about the bandwidth groups in name-value pairs.
Remove a Bandwidth Group
The VBoxManage bandwidthctl remove command
removes a bandwidth group.
Note:
To successfully remove a bandwidth group, ensure that it is not referenced by any disk or adapter in the running VM.
- uuid | vmname
-
Specifies the UUID or the name of the VM.
- bandwidth-group-name
-
Specifies the name of the bandwidth group.
Modify the Bandwidth Limit of a Bandwidth Group
The VBoxManage bandwidthctl set command
modifies the bandwidth limit for a bandwidth group.
- uuid | vmname
-
Specifies the UUID or the name of the VM.
- bandwidth-group-name
-
Specifies the name of the bandwidth group.
- --limit= bandwidth-limit [k|m|g|K|M|G]
-
Specifies the bandwidth limit for a bandwidth group. The default unit is megabytes per second. You can modify this value while the VM is running.
You can change the unit by appending one of the following unit specifiers to the bandwidth limit:
-
k– kilobits per second -
m– megabits per second -
g– gigabits per second -
K– kilobytes per second -
M– megabytes per second -
G– gigabytes per second
-
Examples
The following example shows how to use the VBoxManage
bandwidthctl command to create the
Limit bandwidth group and set the limit to 20
Mbps. Then use the VBoxManage modifyvm command
to assign this bandwidth group to the first and second adapters of
the vm1 VM.
$ VBoxManage bandwidthctl "vm1" add Limit --type network --limit 20m $ VBoxManage modifyvm "vm1" --nicbandwidthgroup1 Limit $ VBoxManage modifyvm "vm1" --nicbandwidthgroup2 Limit
You can dynamically modify the limit of a bandwidth group while
the VM is running. The following example shows how to modify the
limit for the Limit bandwidth group from 20
Mbps to 100 kbps:
$ VBoxManage bandwidthctl "vm1" set Limit --limit 100k
The following command disables shaping for all adapters in the
Limit bandwidth group by specifying a limit of
zero (0):
$ VBoxManage bandwidthctl "vm1" set Limit --limit 0
VBoxManage checkmediumpwd
Check encryption password on a DEK-encrypted medium or a disk image
Description
The VBoxManage checkmediumpwd command checks
the current encryption password on a DEK-encrypted medium or a
disk image. See Encrypting Disk Images.
The command response indicates if the specified password is correct.
- uuid | filename
-
Specifies the Universally Unique Identifier (UUID) or the absolute path name of the medium or image.
- password-file
-
Specifies the password to check. The password can be the absolute path name of a password file on the host OS or the dash character (
-) to prompt you for the password on the command line.
Examples
The following example checks the encryption password for the
ol7u4-1.vdi disk image. The password
is contained in a file called pwfile.
The command returns a message indicating that the specified password is correct.
$ VBoxManage checkmediumpwd "$HOME/VirtualBox VMs/ol7u4/ol7u4-1.vdi" /home/user/pwfile The given password is correct
VBoxManage clonemedium
Create a clone of a medium
Synopsis
Description
The VBoxManage clonemedium command enables you
to clone an existing medium (virtual disk, DVD, or floppy), which
is typically an image file. Only the Universally Unique Identifier
(UUID) differs between the original image and the cloned image.
You can use the Virtual Media Manager to transfer the cloned image to another host system or reimport it into Oracle VM VirtualBox. See The Virtual Media Manager and Cloning Disk Images.
- uuid | source-medium
-
Specifies the UUID or the absolute or relative file name of the source medium to clone. You can specify the UUID of the medium only if it is registered. Use the
VBoxManage list hddscommand to list registered images. - uuid | target-medium
-
Specifies the UUID or the absolute or relative file name of the target (clone) medium. You can specify the UUID of the target medium only if it is registered. Use the
VBoxManage list hddscommand to list registered images. disk|dvd|floppy-
Specifies the type of the medium to clone. Valid values are
disk,dvd, andfloppy. The default value isdisk. - --existing
-
Performs the clone operation by overwriting an existing target medium. The result is that only the portion of the source medium that fits into the existing target medium is copied.
If the target medium is smaller than the source, only the portion of the source medium up to the size of the target medium is copied.
If the target medium is larger than the source, the remaining part of the target medium is unchanged.
- --format
-
Specifies the file format of the target medium if it differs from the format of the source medium. Valid values are
VDI,VMDK,VHD,RAW, and other. - --variant=Standard | Fixed | Split2G | Stream | ESX [,...]
-
Specifies the file format variant for the target medium, which is a comma-separated list of variants. Following are the valid values:
-
Standardis the default disk image type, which has a dynamically allocated file size. -
Fixeduses a disk image that has a fixed file size. -
Split2Gindicates that the disk image is split into 2GB segments. This value is for VMDK only. -
Streamoptimizes the disk image for downloading. This value is for VMDK only. -
ESXis used for some VMWare products. This value is for VMDK only.
Note that not all variant combinations are valid. Specifying incompatible variant values in the list will produce an error message.
-
Note:
For compatibility with earlier versions of Oracle VM VirtualBox, you
can use the clonevdi and
clonehd commands instead of the
clonemedium command.
Examples
The following command creates a clone of the
disk01.vdi disk image file. The clone is
called disk02.vdi.
$ VBoxManage clonemedium disk01.vdi disk02.vdi
The following command creates a clone of the
disk01.vdi disk image file. The clone is in
VMDK format and is called disk02.vmdk.
$ VBoxManage clonemedium disk01.vdi disk02.vmdk --format VMDK
VBoxManage clonevm
Create a clone of an existing virtual machine
Synopsis
Description
The VBoxManage clonevm command creates a clone
of an existing virtual machine (VM). The clone can be a full copy
of the VM or a linked copy of a VM.
You must specify the name or the universal unique identifier (UUID) of the VM you want to clone.
Command Operand and Options
The following list describes the operand and the options that you
can use with the VBoxManage clonevm command:
- vmname|uuid
-
Specifies the name or UUID of the VM to clone.
- --basefolder= basefolder
-
Specifies the name of the folder in which to save the configuration for the new VM.
- --groups= group ,...
-
Assigns the clone to the specified group or groups. If you specify more than one group, separate each group name with a comma.
Note that each group is identified by a group ID that starts with a slash character (/) so that groups can be nested. By default, a clone is always assigned membership to the / group.
- --mode=machine|machineandchildren|all
-
Specifies which of the following cloning modes to use:
-
machine mode clones the current state of the existing VM without any snapshots. This is the default mode.
-
machineandchildren mode clones the snapshot specified by by the --snapshot option and all child snapshots.
-
all mode clones all snapshots and the current state of the existing VM.
-
- --name= name
-
Specifies a new name for the new VM. The default value is original-name Clone where original-name is the original name of the VM.
- --options= option ,...
-
Specifies how to create the new clone.
The --options argument can be used multiple times to enable multiple options, or the options can be given as a comma separated list. The options are case insensitive.
The following options (case-insensitive) are recognized:
- Link
-
Creates a linked clone from a snapshot only.
- KeepAllMACs
-
Specifies that the new clone reuses the MAC addresses of each virtual network card from the existing VM.
If you do not specify this option or the --options=keepnatmacs option, the default behavior is to reinitialize the MAC addresses of each virtual network card.
- KeepNATMACs
-
Specifies that the new clone reuses the MAC addresses of each virtual network card from the existing VM when the network type is NAT.
If you do not specify this option or the KeepAllMACs option, the default behavior is to reinitialize the MAC addresses of each virtual network card.
- KeepDiskNames
-
Specifies that the new clone reuses the disk image names from the existing VM. By default, disk images are renamed.
- KeepHwUUIDs
-
Specifies that the new clone reuses the hardware IDs from the existing VM. By default, new UUIDs are used.
- --register
-
Automatically registers the new clone in this Oracle VM VirtualBox installation. You can manually register the new VM later by using the
VBoxManage registervmcommand. See VBoxManage registervm. - --snapshot= snapshot-name
-
Specifies the snapshot on which to base the new VM. By default, the clone is created from the current state of the specified VM.
- --uuid= uuid
-
Specifies the UUID for the new VM. Ensure that this ID is unique for the Oracle VM VirtualBox instance if you decide to register this new VM. By default, Oracle VM VirtualBox provides a new UUID.
Examples
The following command creates and registers an exact clone of the ol7 VM. The clone is called ol7-dev-001.
The new clone includes all of the source VM's snapshots. The new VM also reuses all network interface MAC addresses, disk names, and UUIDs from the source VM.
$ VBoxManage clonevm ol7 --name="ol7-dev-001" --register --mode=all \
--options=keepallmacs --options=keepdisknames --options=keephwuuids
The following command creates and registers a clone of the Snapshot 1 snapshot of the ol7 VM. The clone is called ol7-dev-002.
$ VBoxManage clonevm ol7 --name="ol7-dev-002" --register --snapshot="Snapshot 1"
VBoxManage closemedium
Remove a hard disk, DVD, or floppy image from the media registry
Description
The VBoxManage closemedium command removes a
hard disk, DVD, or floppy image from the list of known media used
by Oracle VM VirtualBox. The image is then unavailable for selection in
the Virtual Media Manager.
To use this command, the image must not be attached to any VMs.
Optionally, you can request that the image be deleted.
- disk|dvd|floppy
-
Specifies the type of medium. Valid values are
disk(hard drive),dvd, orfloppy. - uuid|filename
-
Specifies the Universally Unique Identifier (UUID) or absolute path name of the medium or image.
- --delete
-
Deletes the image file.
VBoxManage cloud
Manage the cloud entities
Synopsis
Description
Common options
The word "cloud" is an umbrella for all commands related to the interconnection with the Cloud. The next common options must be placed between the "cloud" and the following sub-commands:
- --provider=name
-
Short cloud provider name.
- --profile=name
-
Cloud profile name.
cloud list instances
Displays the list of the instances for a specified compartment.
- --state"running/paused/terminated"
-
The state of cloud instance. The possible states are "running/paused/terminated" at moment. If the state isn't provided the list of instances with all possible states is returned.
- --compartment-id
-
A compartment is the logical container used to organize and isolate cloud resources. The different cloud providers can have the different names for this entity.
cloud list images
Displays the list of the images for a specified compartment.
- --state=available|disabled|deleted
-
The state of cloud image. The possible states are
available,disabledanddeletedat moment. If the state isn't provided the list of images with all possible states is returned. - --compartment-id
-
A compartment is the logical container used to organize and isolate cloud resources. The different cloud providers can have the different names for this entity.
cloud list vnic attachments
Displays the list of the vnic attachments for a specified compartment.
- --filter={instanceId|vnicId|domainName}=string
-
Filters are used to narrow down the set of Vnic attachments of interest. This parameter is repeatible. The possible filter types are "instanceId" or "vnicId" or "availabilityDomain" at moment. The form is "type=[value]" and can be repeated. In instance, "--filter instanceId=ocid1.instance.oc1.iad.anuwcl...js6 --filter vnicId=ocid1.vnic.oc1.iad.abuwcl...jsm --filter domainName=ergw:US-ASHBURN-AD-2". But in most cases, this is redundant and one filter is enough. If the filter isn't provided the whole list of vnic attachments for a specified compartment is returned.
- --compartment-id
-
A compartment is the logical container used to organize and isolate cloud resources. The different cloud providers can have the different names for this entity.
cloud instance create
Creates new instance in the Cloud. There are two standard ways to create an instance in the Cloud: 1. Create an instance from an existing custom image. 2. Create an instance from an existing bootable volume. This bootable volume shouldn't be attached to any instance. For the 1st approach next parameters are required: image-id, boot-disk-size. For the 2nd approach next parameters are required: boot-volume-id. The rest parameters are common for both cases: display-name, launch-mode, subnet-id, publicIP, privateIP, shape, domain.
- --domain-name
-
Cloud domain where new instance is created.
- --image-id
-
Unique identifier which fully identifies a custom image in the Cloud.
- --boot-volume-id
-
Unique identifier which fully identifies a boot volume in the Cloud.
- --display-name
-
Name for new instance in the Cloud.
- --shape
-
The shape of instance, defines the number of CPUs and RAM memory.
- --subnet
-
Unique identifier which fully identifies an existing subnet in the Cloud which will be used by the instance.
- --boot-disk-size
-
The size of bootable image in GB. Default is 50GB.
- --publicip
-
Whether the instance will have a public IP or not.
- --privateip
-
Private IP address for the created instance.
- --public-ssh-key
-
Public SSH key used to connect to the instance via SSH. This parameter may be repeated if you plan to use more than one key as: "--public-ssh-key=firstSSHKey --public-ssh-key=secondSSHKey".
- --launch-mode
-
The most known values here may be EMULATED, NATIVE, PARAVIRTUALIZED.
- --cloud-init-script-path
-
Absolute path to the user cloud-init script.
cloud instance info
Display information about a cloud instance with a specified id.
- --id
-
Unique identifier which fully identify the instance in the Cloud.
cloud instance termination
Delete a cloud instance with a specified id.
- --id
-
Unique identifier which fully identify the instance in the Cloud.
cloud instance start
Start a cloud instance with a specified id.
- --id
-
Unique identifier which fully identify the instance in the Cloud.
cloud instance pause
Pause a cloud instance with a specified id.
- --id
-
Unique identifier which fully identify the instance in the Cloud.
cloud instance reset
Force reset a cloud instance with a specified id.
- --id
-
Unique identifier which fully identify the instance in the Cloud.
cloud image create
Creates new image in the Cloud. There are two standard ways to create an image in the Cloud: 1. Create an image from an object in the Cloud Storage; 2. Create an image from an existing cloud instance. For the 1st approach next parameters are required: bucket-name - cloud bucket name where an object is located; object-name - name of object in the bucket; display-name - name for new image in the Cloud. For the 2d approach next parameters are required: instance-id - Id of instance in the Cloud; display-name - name for new image in the Cloud.
- --display-name
-
Name for new image in the Cloud.
- --bucket-name
-
Cloud bucket name where an object is located.
- --object-name
-
Name of object in the bucket.
- --instance-id
-
Unique identifier which fully identifies the instance in the Cloud.
cloud image info
Display information about a cloud image with a specified id.
- --id
-
Unique identifier which fully identifies the image in the Cloud.
cloud image delete
Delete an image with a specified id from the Cloud.
- --id
-
Unique identifier which fully identifies the image in the Cloud.
cloud image import
Import an image with a specified id from the Cloud to a local host. The result is an object in the local "temp" folder on the local host. Possible approach may have two general steps: 1. Create an object from an image in the Cloud Storage; 2. Download the object to the local host. So the next parameters may be required: bucket-name - cloud bucket name where the object will be created; object-name - name of object in the bucket. if parameter "object-name" is absent a displayed image name is used. If the first step isn't needed only the parameter "id" is required.
- --id
-
Unique identifier which fully identifies the image in the Cloud.
- --bucket-name
-
Cloud bucket name where an object will be created.
- --object-name
-
Name of created object in the bucket. The downloaded object will have this name.
cloud image export
Export an existing VBox image with a specified uuid from a local host to the Cloud. The result is new image in the Cloud. Possible approach may have two general steps: 1. Upload VBox image to the Cloud Storage; 2. Create an image from the uploaded object. So the next parameters may be required: bucket-name -cloud bucket name where the object will be uploaded; object-name - name of object in the bucket. If parameter "object-name" is absent the image id is used; display-name - name for new image in the Cloud. If the first step isn't needed the parameters "id" and "display-name" are required only.
- --id
-
Unique identifier of the image in the VirtualBox.
- --display-name
-
Name for new image in the Cloud.
- --bucket-name
-
Cloud bucket name where the image (object) will be uploaded.
- --object-name
-
Name of object in the bucket.
cloud network setup
Set up a cloud network environment for the specified cloud profile.
- --gateway-os-name
-
The name of OS to use for a cloud gateway.
- --gateway-os-version
-
The version of OS to use for a cloud gateway.
- --gateway-shape
-
The instance shape to use for a cloud gateway.
- --tunnel-network-name
-
The name of VCN/subnet to use for tunneling.
- --tunnel-network-range
-
The IP address range to use for tunneling.
- --proxy
-
The proxy URL to be used in local gateway installation.
- --compartment-id
-
The compartment to create the tunnel network in.
cloud network create
Create a new cloud network descriptor associated with an existing cloud subnet.
- --name
-
The name to assign to the cloud network descriptor.
- --network-id
-
The unique identifier of an existing subnet in the cloud.
- --enable, --disable
-
Whether to enable the network descriptor or disable it. If not specified, the network will be enabled.
cloud network update
Modify an existing cloud network descriptor.
- --name
-
The name of an existing cloud network descriptor.
- --network-id
-
The unique identifier of an existing subnet in the cloud.
- --enable, --disable
-
Whether to enable the network descriptor or disable it.
VBoxManage cloudprofile
Manage the cloud profiles
Synopsis
Description
Common options
The subcommands of cloudprofile implement the standard CRUD operations for a cloud profile.
The next common options must be placed between the "cloud" and the following sub-commands:
- --provider=name
-
Short cloud provider name.
- --profile=name
-
Cloud profile name.
cloudprofile add
Add new cloud profile for a specified cloud provider.
- --clouduser= unique id
-
The name which fully identifies the user in the specified cloud provider.
- --fingerprint= MD5 string
-
Fingerprint for the key pair being used.
- --keyfile= path
-
Full path and filename of the private key.
- --passphrase= string
-
Passphrase used for the key, if it is encrypted.
- --tenancy= unique id
-
ID of your tenancy.
- --compartment= unique id
-
ID of your compartment.
- --region= string
-
Region name. Region is where you plan to deploy an application.
cloudprofile show
Display information about a cloud profile for a specified cloud provider.
cloudprofile update
Modify a cloud profile for the specified cloud provider.
- --clouduser= unique id
-
The name which fully identifies the user in the specified cloud provider.
- --fingerprint= MD5 string
-
Fingerprint for the key pair being used.
- --keyfile= path
-
Full path and filename of the private key.
- --passphrase= string
-
Passphrase used for the key, if it is encrypted.
- --tenancy= unique id
-
ID of your tenancy.
- --compartment= unique id
-
ID of your compartment.
- --region= string
-
Region name. Region is where you plan to deploy an application.
VBoxManage controlvm
Change state and settings for a running virtual machine
Synopsis
Description
The VBoxManage controlvm command enables you to
change the state of a running virtual machine (VM). The following
sections describe the subcommands that you can use:
Pause a Virtual Machine
The VBoxManage controlvm
vmname pause command
temporarily stops the execution of a VM. When paused, the VM's
state is not permanently changed.
The VM window appears as gray and the title bar of the window indicates that the VM is currently Paused. This action is equivalent to selecting Pause from the Machine menu of the GUI.
Resume a Paused Virtual Machine
The VBoxManage controlvm
vmname resume command
restarts the execution of a paused VM. This action is equivalent
to selecting Resume from the
Machine menu of the GUI.
Reset a Virtual Machine
The VBoxManage controlvm
vmname reset command
performs a cold reset the VM. This command has the same effect
on a VM as pressing the Reset button on a physical computer.
The cold reboot immediately restarts and reboots the guest operating system (OS). The state of the VM is not saved prior to the reset, so data might be lost. This action is equivalent to selecting Reset from the Machine menu of the GUI.
Power Off a Virtual Machine
The VBoxManage controlvm
vmname poweroff command
powers off the VM. This command has the same effect on a VM as
pulling the power cable on a physical computer.
The state of the VM is not saved prior to poweroff, so data might be lost. This action is equivalent to selecting Close from the Machine menu of the GUI or to clicking the VM window's Close button, and then selecting Power Off the Machine.
When in the powered off state, you can restart the VM. See VBoxManage startvm.
Save the State of a Virtual Machine
The VBoxManage controlvm
vmname savestate command
saves the current state of the VM to disk and then stops the VM.
This action is equivalent to selecting Close from the Machine menu of the GUI or to clicking the VM window's Close button, and then selecting Save the Machine State.
When in the saved state, you can restart the VM. It will continue exactly in the state you saved.
Send an APCI Shutdown Signal to a Virtual Machine
The VBoxManage controlvm
vmname acpipowerbutton
command sends an ACPI shutdown signal to the VM. This command
has the same effect on a VM as pressing the Power button on a
physical computer.
So long as the VM runs a guest OS that provides appropriately configured ACPI support, this command triggers an operating system shutdown from within the VM.
Send an APCI Sleep Signal to a Virtual Machine
The VBoxManage controlvm
vmname acpisleepbutton
command sends an ACPI sleep signal to the VM.
So long as the VM runs a guest OS that provides appropriately configured ACPI support, this command triggers a sleep mechanism from within the VM.
Reboot the guest OS
The VBoxManage controlvm
vmname reboot
command asks the guest OS to reboot itself.
This commands requires Guest Additions to be installed in the VM.
Shut down the guest OS
The VBoxManage controlvm
vmname shutdown
command asks the guest OS to halt + shutdown, optionally forcing
the shutdown.
This commands requires Guest Additions to be installed in the VM.
Send Keyboard Scancodes to a Virtual Machine
The VBoxManage controlvm
vmname keyboardputscancode
command sends keyboard scancode commands to the VM.
For information about keyboard scancodes, see http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html.
Send Keyboard Strings to a Virtual Machine
The VBoxManage controlvm
vmname keyboardputstring
command sends keyboard strings to the VM.
Send a File to a Virtual Machine
The VBoxManage controlvm
vmname keyboardputfile
command sends a file to the VM.
Set the Link State for a Virtual Machine
VBoxManage controlvm vmname
setlinkstateN command
enables you to connect or disconnect the virtual network cable
from the network interface instance
(N). Valid values are
on and off. The default
value is on.
Set the Type of Networking to Use for a Virtual Machine
The VBoxManage controlvm
vmname
nicN command specifies the
type of networking to use on the specified VM's virtual network
card. N numbering begins with
1.
The following valid network types are also described in Introduction to Networking Modes:
-
nullspecifies that the VM is is not connected to the host system. -
natspecifies that the VM uses network address translation (NAT). -
bridgedspecifies that the VM uses bridged networking. -
intnetspecifies that the VM communicates with other VMs by using internal networking. -
hostonlyspecifies that the VM uses host-only networking. -
natnetworkspecifies that the VM uses NAT networking. -
genericspecifies that the VM has access to rarely used submodes
Trace the Network Traffic of a Virtual Machine
The VBoxManage controlvm
vmname
nictraceN command enables
you to trace the network traffic on the specified virtual
network card (N).
N numbering begins with
1. Valid values are on and
off. The default value is
off.
If you did not configure a file name for the trace file then a default one is used, placing it in the VM subdirectory.
Specify the Network Traffic Trace Log File for a Virtual Machine
The VBoxManage controlvm
vmname
nictracefileN command
enables you to specify the name of the network traffic trace log
file for the specified virtual network card
(N). N
numbering begins with 1.
Specify the Promiscuous Mode to Use for a Virtual Machine
The VBoxManage controlvm
vmname
nicpromiscN command enables
you to specify how to handle promiscuous mode for a bridged
network. The default value of deny hides any
traffic that is not intended for this VM. The
allow-vms value hides all host traffic from
this VM but enables the VM to see traffic to and from other VMs.
The allow-all value removes this restriction
completely.
Specify the Network Backend Property Values for a Virtual Machine
The VBoxManage controlvm
vmname
nicpropertyN
prop-name=prop-value
command, in combination with nicgenericdrv,
enables you to pass property values to rarely-used network
backends.
Those properties are backend engine-specific, and are different between UDP Tunnel and the VDE backend drivers. See UDP Tunnel Networking.
Specify a NAT Port Forwarding Rule for a Virtual Machine
The VBoxManage controlvm
vmname
natpfN command specifies a
NAT port-forwarding rule. See Configuring Port Forwarding with NAT.
Delete a NAT Port Forwarding Rule for a Virtual Machine
The VBoxManage controlvm
vmname
natpfN delete command deletes
the specified NAT port-forwarding rule. See
Configuring Port Forwarding with NAT.
Change Size of a Virtual Machine's Guest Memory Balloon
The VBoxManage controlvm
vmname guestmemoryballoon
command changes the size of the guest memory balloon. The guest
memory balloon is the memory allocated by the Oracle VM VirtualBox
Guest Additions from the guest OS and returned to the hypervisor
for reuse by other VMs. The value you specify is in megabytes.
See Memory Ballooning.
Make a Host System USB Device Visible to a Virtual Machine
The VBoxManage controlvm
vmname usbattach command
dynamically attaches a host USB device to the VM, which makes it
visible. You do not need to create a filter.
Specify a USB device by its Universally Unique Identifier (UUID)
or by its address on the host system. Use the
VBoxManage list usbhost command to obtain
information about USB devices on the host system.
Use the --capturefile option to specify the absolute path of a file in which to write logging data.
Make a Host System USB Device Invisible to a Virtual Machine
The VBoxManage controlvm
vmname usbdetach command
dynamically detaches a host USB device from the VM, which makes
it invisible. You do not need to create a filter.
Specify a USB device by its UUID or by its address on the host
system. Use the VBoxManage list usbhost
command to obtain information about USB devices on the host
system.
Enable or Disable Audio Capture From the Host System
The VBoxManage controlvm
vmname audioin command
specifies whether to enable or disable audio capture from the
host system. Valid values are on, which
enables audio capture and off, which disables
audio capture. The default value is off.
Enable or Disable Audio Playback From a Virtual Machine
The VBoxManage controlvm
vmname audioout command
specifies whether to enable or disable audio playback from the
guest VM. Valid values are on, which enables
audio playback and off, which disables audio
playback. The default value is off.
Specify How to Share the Host OS or Guest OS Clipboard
The VBoxManage controlvm
vmname clipboard mode command
specifies how to share the guest or host OS's clipboard with the
host system or VM. Valid values are disabled,
hosttoguest, guesttohost,
and bidirectional. The default value is
disabled. See
General Settings.
This feature requires that the Oracle VM VirtualBox Guest Additions are installed in the VM.
Specify If Files Can Be Transferred Through the Clipboard
The VBoxManage controlvm
vmname clipboard filetransfers
command specifies if it is possible to transfer files through the
clipboard between the host and VM, in the direction which is allowed.
Valid values are off and on.
The default value is off.
This feature requires that the Oracle VM VirtualBox Guest Additions are installed in the VM.
Set the Drag and Drop Mode Between the Host System and a Virtual Machine
The VBoxManage controlvm
vmname draganddrop command
specifies the current drag and drop mode to use between the host
system and the VM. Valid values are disabled,
hosttoguest, guesttohost,
and bidirectional. The default value is
disabled. See
Drag and Drop.
This feature requires that the Oracle VM VirtualBox Guest Additions are installed in the VM.
Enable or Disable the VRDE Server
The VBoxManage controlvm
vmname vrde command enables
or disables the VirtualBox Remote Desktop Extension (VRDE)
server, if installed. Valid values are on and
off. The default value is
off.
Specify VRDE Server Ports
The VBoxManage controlvm
vmname vrdeport command
specifies the port or range of ports to which the VRDE server
can bind. The default value is default or
0, which is the standard RDP port,
3389.
Also see the --vrde-port option description in Remote Machine Settings.
Specify VRDE Server Port Numbers and IP Addresses
The VBoxManage controlvm
vmname vrdeproperty command
specifies the port numbers and IP address on the VM to which the
VRDE server can bind.
-
TCP/Portsspecifies a port or a range of ports to which the VRDE server can bind. The default value isdefaultor0, which is the standard RDP port,3389.Also see the --vrde-port option description in Remote Machine Settings.
-
TCP/Addressspecifies the IP address of the host network interface to which the VRDE server binds. When specified, the server accepts to connect only on the specified host network interface.Also see the --vrde-address option description in Remote Machine Settings.
-
VideoChannel/Enabledspecifies whether to enable the VirtualBox Remote Desktop Protocol (VRDP) video channel. Valid values are1to enable the video channel and0to disable the video channel. The default value isoff. See VRDP Video Redirection. -
VideoChannel/Qualityspecifies the JPEG compression level on the VRDE server video channel. Valid values are between 10% and 100%, inclusive. Lower values mean lower quality but higher compression. The default value is100. See VRDP Video Redirection. -
VideoChannel/DownscaleProtectionspecifies whether to enable the video channel downscale protection feature. Specify1to enable the feature. This feature is disabled by default.When enabled, if the video's size equals the shadow buffer size, the video is shown in full-screen mode. If the video's size is between full-screen mode and the downscale threshold, the video is not shown as it might be an application window that is unreadable when downscaled. When disabled, the downscale protection feature always attempts to show videos.
-
Client/DisableDisplayspecifies whether to disable the VRDE server display feature. Valid values are1to disable the feature and an empty string ("") to enable the feature. The default value is an empty string. See VRDP Customization. -
Client/DisableInputspecifies whether to disable the VRDE server input feature. Valid values are1to disable the feature and an empty string ("") to enable the feature. The default value is1. See VRDP Customization. -
Client/DisableAudiospecifies whether to disable the VRDE server audio feature. Valid values are1to disable the feature and an empty string ("") to enable the feature. The default value is1. See VRDP Customization. -
Client/DisableUSBspecifies whether to disable the VRDE server USB feature. Valid values are1to disable the feature and an empty string ("") to enable the feature. The default value is1. See VRDP Customization. -
Client/DisableClipboardspecifies whether to disable the VRDE clipboard feature. Valid values are1to disable the feature and an empty string ("") to enable the feature. To reenable the feature, useClient/DisableClipboard=. The default value is1. See VRDP Customization. -
Client/DisableUpstreamAudiospecifies whether to disable the VRDE upstream audio feature. Valid values are1to disable the feature and an empty string ("") to enable the feature. To reenable the feature, useClient/DisableUpstreamAudio=. The default value is1. See VRDP Customization. -
Client/DisableRDPDRspecifies whether to disable the RDP Device Redirection For Smart Cards feature on the VRDE server. Valid values are1to disable the feature and an empty string ("") to enable the feature. The default value is1. See VRDP Customization. -
H3DRedirect/Enabledspecifies whether to enable the VRDE server 3D redirection feature. Valid values are1to enable the feature and an empty string ("") to disable the feature. See VRDP Customization. -
Security/Methodspecifies the security method to use for a connection. See RDP Encryption.-
Negotiateaccepts both enhanced (TLS) and standard RDP security connections. The security method is negotiated with the client. This is the default value. -
RDPaccepts only standard RDP security connections. -
TLSaccepts only enhanced RDP security connections. The client must support TLS.
-
-
Security/ServerCertificatespecifies the absolute path of the server certificate to use for a connection. See RDP Encryption. -
Security/ServerPrivateKeyspecifies the absolute path of the server private key. See RDP Encryption. -
Security/CACertificatespecifies the absolute path of the CA self-signed certificate. See RDP Encryption. -
Audio/RateCorrectionModespecifies the rate correction mode to use.-
VRDP_AUDIO_MODE_VOIDindicates that no mode is specified. Use this value to unset any audio mode that is already set. -
VRDP_AUDIO_MODE_RCspecifies to use the rate correction mode. -
VRDP_AUDIO_MODE_LPFspecifies to use the low pass filter mode. -
VRDP_AUDIO_MODE_CSspecifies to use the client sync mode to prevent underflow or overflow of the client queue.
-
-
Audio/LogPathspecifies the absolute path of the audio log file.
Specify the Image Quality for VRDP Video Redirection
The VBoxManage controlvm
vmname
vrdevideochannelquality command sets the image
quality, as a JPEG compression level value, for video
redirection. Valid values are between 10% and 100%, inclusive.
Lower values mean lower quality but higher compression. See
VRDP Video Redirection.
Specify the Video Mode for the Guest VM
The VBoxManage controlvm
vmname setvideomodehint
command specifies the video mode for the guest VM to use. You
must have the Oracle VM VirtualBox Guest Additions installed. Note
that this feature does not work for all guest systems.
Specify the Screen Layout for a Display on the Guest VM
The VBoxManage controlvm
vmname setscreenlayout
command can be used to configure multiscreen displays. The
specified screen on the guest VM can be enabled or disabled, or
a custom screen layout can be configured.
Take a Screen Shot of the Virtual Machine Display
The VBoxManage controlvm
vmname screenshotpng
command takes a screenshot of the guest display and saves it as
PNG in the specified file.
-
filename specifies the name of the PNG file to create.
-
display specifies the display number for the screen shot. For a single monitor guest display, this is
0.
Enable or Disable the Recording of a Virtual Machine Session
The VBoxManage controlvm
vmname recording command
enables or disables the recording of a VM session into a
WebM/VP8 file. Valid values are on, which
begins recording when the VM session starts and
off, which disables recording. The default
value is off.
Specify the Virtual Machine Screens to Record
The VBoxManage controlvm
vmname recording screens
command enables you to specify which VM screens to record. The
recording for each screen that you specify is saved to its own
file in the machine folder. You cannot modify this setting while
recording is enabled.
-
allspecifies that you record all VM screens. -
nonespecifies that you do not record any VM screens. -
screen-ID specifies one or more VM screens to record.
Specify the File in Which to Save Virtual Machine Recording
The VBoxManage controlvm
vmname recording filename
command specifies the file in which to save the recording. You
cannot modify this setting while recording is enabled.
The default setting is to store a recording in the machine
folder, using the VM name as the file name, with a
webm file name extension.
Specify the Resolution of the Recorded Video
VBoxManage controlvm vmname
recording videores command specifies the resolution of
the recorded video in pixels. You cannot modify this setting
while recording is enabled.
Use the Settings tool to view the video recording settings, which are based on the resolution (frame size). See the Frame Size field on the Recording tab of the Display page to view the default value.
Specify the resolution as
widthxheight:
-
width specifies the width in pixels.
-
height specifies the height in pixels.
Specify the Bit Rate of the Video
The VBoxManage controlvm
vmname recording videorate
command specifies the bit rate,
bit-rate, of the video in kilobits
per second. Increasing this value improves the appearance of the
video at the cost of an increased file size. You cannot modify
this setting while recording is enabled.
Use the Settings tool to view the video recording settings, which are based on the frame size. See the Video Quality field on the Recording tab of the Display page to view the default value.
Specify the Maximum Frequency of the Video
The VBoxManage controlvm
vmname recording videofps
command specifies the maximum frequency of the video to record.
Video frequency is measured in frames per second (FPS). The
recording skips any frames that have a frequency higher than the
specified maximum. Increasing the frequency reduces the number
of skipped frames and increases the file size. You cannot modify
this setting while recording is enabled.
Use the Settings tool to view the video recording settings, which are based on the frame size. See the Frame Rate field on the Recording tab of the Display page to view the default value.
Specify the Maximum Amount of Time to Record Video
The VBoxManage controlvm
vmname recording maxtime
command specifies the maximum amount time to record in seconds.
The recording stops after the specified number of seconds
elapses. If this value is zero, the recording continues until
you stop the recording.
Specify the Maximum Size of the Recorded Video
The VBoxManage controlvm
vmname recording
maxfilesize command specifies the maximum size of the
recorded video file in megabytes. The recording stops when the
file reaches the specified size. If this value is zero, the
recording continues until you stop the recording. You cannot
modify this setting while recording is enabled.
Specify Credentials for Remote Logins on Windows Virtual Machines
The setcredentials command enables you to
specify the credentials for remotely logging in to Windows VMs.
See Automated Guest Logins.
-
username specifies the user name with which to log in to the Windows VM.
-
--passwordfile=filename specifies the file from which to obtain the password for username.
The --passwordfile is mutually exclusive with the --password option.
-
--password=password specifies the password for username.
The --password is mutually exclusive with the --passwordfile option.
-
--allowlocallogin specifies whether to enable or disable local logins. Valid values are
onto enable local logins andoffto disable local logins.
Configure a Virtual Machine Target for Teleporting
The VBoxManage controlvm
vmname teleport command
initiates a teleporting operation between the specified VM and
the specified host system. See Teleporting.
If you specify a password, it must match the password you
specified when you issued the VBoxManage
modifyvm command for the target machine.
- --host= hostname
-
Specifies the name of the VM.
- --port= port
-
Specifies the port on the VM that should listen for a teleporting request from other VMs. The port number can be any free TCP/IP port number, such as
6000. - --maxdowntime= msec
-
Specifies the maximum downtime, in milliseconds, for the teleporting target VM.
- --password= password
-
Specifies the password that the source machine uses for the teleporting request. The request succeeds only if the source machine specifies the same password.
The --password is mutually exclusive with the --passwordfile option.
- --passwordfile= filename
-
Specifies the file from which to obtain the password that the source machine uses for the teleporting request. The request succeeds only if the source machine specifies the same password.
When you specify a file name of
stdin, you can read the password from standard input.The --passwordfile is mutually exclusive with the --password option.
Add a Virtual CPU to a Virtual Machine
The VBoxManage controlvm
vmname plugcpu command adds
a virtual CPU to the specified VM if CPU hot-plugging is
enabled. ID specifies the index of
the virtual CPU to be added and must be a number from 0 to the
maximum number of CPUs configured.
Remove a Virtual CPU From a Virtual Machine
The VBoxManage controlvm
vmname unplugcpu command
removes a virtual CPU from the specified VM if CPU hot-plugging
is enabled. ID specifies the index of
the virtual CPU to be removed and must be a number from 0 to the
maximum number of CPUs configured. You cannot remove CPU 0.
Set the Maximum Amount of Physical CPU Time Used by a Virtual CPU
The VBoxManage controlvm
vmname cpuexecutioncap
command specifies how the maximum amount of physical CPU time
used by a virtual CPU. Valid values are a percentage between
1 and 100. A value of
50 specifies that a single virtual CPU can
use up to 50% of a physical CPU. The default value is
100.
Use this feature with caution, it can have unexpected results including timekeeping problems and lower performance than specified. If you want to limit the resource usage of a VM it is more reliable to pick an appropriate number of VCPUs.
Change the Priority of a VM Process
The VBoxManage controlvm
vmname vm-process-priority
command specifies the priority scheme of the VM process to use
when starting the specified VM and while the VM runs.
Valid values are:
-
default– Default process priority determined by the OS. -
flat– Assumes a scheduling policy which puts the process at the default priority and with all threads at the same priority. -
low– Assumes a scheduling policy which puts the process mostly below the default priority of the host OS. -
normal– Assume a scheduling policy which shares the CPU resources fairly with other processes running with the default priority of the host OS. -
high– Assumes a scheduling policy which puts the task above the default priority of the host OS. This policy might easily cause other tasks in the system to starve.
Attach a Webcam to a Virtual Machine
The VBoxManage controlvm
vmname webcam attach
command attaches a webcam to a running VM. Specify the webcam as
the absolute path of the webcam on the host OS or as an alias.
Use the VBoxManage list webcams command to
obtain the webcam alias.
Note that the .0 alias is the default video
input device on the host OS. .1 is the first
video input device, .2 is the second video
input device, and so on. The order of the devices is specific to
the host system.
You can specify optional settings in the form of
semi-colon-separated (;) name-value pairs.
These properties enable you to configure the emulated webcam
device.
The following settings are supported:
-
MaxFramerate -
Specifies the highest rate at which to send video frames to the VM. The rate is in frames per second. Higher frame rates increase CPU load, so you can use this setting to reduce CPU load. The default value is
no maximum limit. This value enables the VM to use any frame rate supported by the webcam. -
MaxPayloadTransferSize -
Specifies the maximum number of bytes that the VM receives from the emulated webcam in one buffer. The default setting is
3060bytes, which is used by some webcams. If the VM is able to use larger buffers, higher values might reduce CPU load slightly. Note that some guest OSes might not suppport higherMaxPayloadTransferSizevalues.
Detach a Webcam From a Virtual Machine
The VBoxManage controlvm
vmname webcam detach
command detaches a webcam from a running VM. Specify the webcam
as the absolute path of the webcam on the host OS or as an
alias. Use the VBoxManage list webcams to
obtain the webcam alias.
When a webcam device is detached from the host, the host OS determines how the emulated webcam behaves.
-
Windows hosts: The emulated webcam device is detached from the VM automatically.
-
Mac OS X hosts that run at least OS X 10.7: The emulated webcam device remains attached to the VM and you must detach it manually by using the
VBoxManage controlvm webcam detachcommand. -
Linux hosts: The emulated webcam device is detached from the VM automatically only if the webcam is actively streaming video. If the emulated webcam is inactive, manually detach it by using the
VBoxManage controlvmvmnamewebcam detachcommand.
List the Webcams Attached to a Virtual Machine
The VBoxManage controlvm
vmname webcam list command
lists webcams that are attached to the running VM. The output
shows a list of absolute paths or aliases that attached the
webcams to the VM by using the VBoxManage controlvm
vmname webcam attach
command.
Set an Encryption Password for a Virtual Machine
The VBoxManage controlvm
vmname addencpassword
command provides the vmname encrypted
VM with the encryption password to enable a headless start.
Specify the absolute path of a password file on the host system.
If filename is -,
VBoxManage prompts for the encryption
password.
Use the --removeonsuspend option to specify whether to save the passsword or clear it from VM memory when the VM is suspended.
If the VM is suspended and the password is cleared, use the
VBoxManage controlvm vmname
addencpassword to provide the password to resume
execution on the VM. Use this feature when you do not want to
store the password in VM memory while the VM is suspended by a
host suspend event.
Note:
You can encrypt data stored on hard disk images used by the VM. Oracle VM VirtualBox uses the AES algorithm in XTS mode and supports 128-bit or 256-bit data encryption keys (DEK). The encrypted DEK is stored in the medium properties and is decrypted during VM startup when you provide the encryption password.
Use the VBoxManage encryptmedium command to
create a DEK encrypted medium. See
Encrypting Disk Images.
The Oracle VM VirtualBox GUI prompts you for the encryption password when you start an encrypted VM.
Use the following command to perform a headless start of an encrypted VM:
$ VBoxManage startvm vmname --type headless
Then, use the following command to provide the encryption password:
$ VBoxManage vmname controlvm addencpassword vmname -
Password: encryption-password
Disable an Encryption Password for a Virtual Machine
The VBoxManage controlvm
vmname removeencpassword
command disables a specific encryption password for all
encrypted media attached to the VM.
ID is the password identifier for the encryption password that you want to disable.
Disable All Encryption Passwords for a Virtual Machine
The VBoxManage controlvm
vmname
removeallencpasswords command disables all encryption
passwords for all encrypted media attached to the VM.
Change the Connection Mode for a Virtual Serial Port on a Virtual Machine
The VBoxManage controlvm
vmname changeuartmode
command changes the connection mode for the specified virtual
serial port. Valid serial port values are integers that start
from 1.
- disconnected
-
Disconnects the device.
- server pipe-name
-
Specifies the pipe name of the server.
- client pipe-name
-
Specifies the pipe name of the client.
- tcpserver port
-
Specifies the port number of the TCP server.
- tcpclient hostname:port
-
Specifies the host name and port number of the TCP client.
- file filename
-
Specifies the name of the file.
- device-name
-
Specifies the name of the device.
Enabling autostart the VM during host system boot
The VBoxManage controlvm
vmname autostart-enabled
command specifies whether to enable or disable automatically
start the VM at host system boot-up. You must do some host
system configuration before you can use this feature.
See Starting Virtual Machines During System Boot. Valid values are
on, which enables autostart feature for
the VM and off, which disables it. The
default value is off.
Setting the delay of starting the VM on host system boot
The VBoxManage controlvm
vmname autostart-delay
command specifies the delay in seconds before the VM starts
on host system boot-up. See Starting Virtual Machines During System Boot.
Examples
The following command temporarily stops the execution of the
ol7 VM.
$ VBoxManage controlvm ol7 pause
The following command configures shared clipboard operation for
the ol7 VM. Copying of clipboard data is
allowed in both directions between the host and guest.
$ VBoxManage controlvm ol7 clipboard mode bidirectional
VBoxManage convertfromraw
Convert a raw disk image to a virtual disk image
Synopsis
Description
The VBoxManage convertfromraw command enables
you to convert a raw disk image to an Oracle VM VirtualBox virtual disk
image (VDI).
Note:
For compatibility with earlier versions of Oracle VM VirtualBox, you
can use the VBoxManage convertdd command
instead of the VBoxManage convertfromraw
command.
Convert a Raw Disk File to a Virtual Disk Image File
The VBoxManage convertfromraw command
converts the specified raw disk image input file to an
Oracle VM VirtualBox VDI file.
- inputfile
-
Specifies the name of the raw disk image file to convert.
- outputfile
-
Specifies the name of the file in which to write the VDI output.
- --format=VDI | VMDK | VHD
-
Specifies the format of the disk image to create. Valid values are
VDI,VMDK, andVHD. The default format isVDI. - --uuid= uuid
-
Specifies the Universally Unique Identifier (UUID) of the output file.
- --variant=Standard | Fixed | Split2G | Stream | ESX[,...]
-
Specifies any required file format variants for the output file. This is a comma-separated list of variant values. Following are the valid values:
-
Standardis the default disk image type, which has a dynamically allocated file size. -
Fixeduses a disk image that has a fixed file size. -
Split2Gindicates that the disk image is split into 2GB segments. This value is for VMDK only. -
Streamoptimizes the disk image for downloading. This value is for VMDK only. -
ESXis used for some VMWare products. This value is for VMDK only.
Note that not all variant combinations are valid. Specifying incompatible variant values in the list will produce an error message.
-
Convert Raw Data From Standard Input to a Virtual Disk Image File
The VBoxManage convertfromraw stdin command
reads the content of the disk image from standard input.
Consider using this form of the command in a pipe sequence.
- outputfile
-
Specifies the name of the file in which to write the VDI output.
- --format=VDI | VMDK | VHD
-
Specifies the format of the disk image to create. Valid values are
VDI,VMDK, andVHD. The default format isVDI. - --uuid= uuid
-
Specifies the UUID of the output file.
- --variant=Standard,Fixed,Split2G,Stream,ESX
-
Specifies any required file format variants for the output file. This is a comma-separated list of variant values. Following are the valid values:
-
Standardis the default disk image type, which has a dynamically allocated file size. -
Fixeduses a disk image that has a fixed file size. -
Split2Gindicates that the disk image is split into 2GB segments. This value is for VMDK only. -
Streamoptimizes the disk image for downloading. This value is for VMDK only. -
ESXis used for some VMWare products. This value is for VMDK only.
Note that not all variant combinations are valid. Specifying incompatible variant values in the list will produce an error message.
-
Examples
The following command converts the raw disk image input file
disk01.raw. The output file is a VDI disk
image called disk02.vdi.
$ VBoxManage convertfromraw disk01.raw disk02.vdi
The following command converts the raw disk image input file
disk01.raw. The output file is a VMDK disk
image called disk02.vmdk.
$ VBoxManage convertfromraw disk01.raw disk02.vmdk --format VMDK
VBoxManage createmedium
Create a new medium
Synopsis
Description
The VBoxManage createmedium command creates a
new medium, such as a disk image file.
Note:
For compatibility with earlier versions of Oracle VM VirtualBox, you
can use the createvdi and
createhd commands instead of the
createmedium command.
- disk | dvd | floppy
-
Specifies the media type. The default value is
disk. - --filename= filename
-
Specifies the absolute path name to a file on the host file system.
- --size= megabytes
-
Specifies the image capacity in one megabyte units.
- --sizebyte= bytes
-
Specifies the image capacity in one byte units.
- --diffparent= UUID | filename
-
Specifies the Universally Unique Identifier (UUID) or absolute path name of a differencing image parent file on the host file system.
Use this file to share a base box disk image among VMs.
- --format=VDI | VMDK | VHD
-
Specifies the file format of the output file. Valid formats are
VDI,VMDK, andVHD. The default format isVDI. - --variant=Standard | Fixed | Split2G | Stream | ESX | Formatted | RawDisk [,...]
-
Specifies the file format variant for the target medium, which is a comma-separated list of variants. Following are the valid values:
-
Standardis the default disk image type, which has a dynamically allocated file size. -
Fixeduses a disk image that has a fixed file size. -
Split2Gindicates that the disk image is split into 2GB segments. This value is valid for VMDK disk images only. -
Streamoptimizes the disk image for downloading. This value is valid for VMDK disk images only. -
ESXis used for some VMWare products. This value is valid for VMDK disk images only. -
Formattedformats the medium automatically. This value is valid for floppy images only. -
RawDiskis used for creating a VMDK image which provides direct access to the hard disk on the host using its raw interface. This value is valid for VMDK disk images only. For detailed information about raw disk access, see Advanced Storage Configuration.
Note that not all variant combinations are valid. Specifying incompatible variant values in the list will produce an error message.
-
- --property= name = value
-
Specifies any required file format dependent parameters in
key=valueform. Optional. - --property-file= name = /path/to/file/with/value
-
Specifies any required file format dependent parameters in
key=file/with/valueform. The value is taken from the file. Optional.
Examples
The following command creates a new disk image file named
disk01.vdi. The file size is 1024 megabytes.
$ VBoxManage createmedium --filename disk01.vdi --size 1024
The following command creates a new floppy disk image file named
floppy01.vdi. The file size is 1 megabyte.
$ VBoxManage createmedium floppy --filename floppy01.img --size 1
The following command creates a raw disk image of an entire physical disk on a Linux host.
$ VBoxManage createmedium disk --filename=/path/to/rawdisk.vmdk --variant=RawDisk --format=VMDK --property RawDrive=/dev/sda
VBoxManage createvm
Create a new virtual machine
Synopsis
Description
The VBoxManage createvm command creates a new
XML virtual machine (VM) definition file.
You must specify the name of the VM by using --name
name. This name is used by
default as the name of the settings file that has the
.vbox extension and the machine folder, which
is a subfolder of the $HOME/VirtualBox VMs
directory.
The actual file name may not correspond directly to the VM name if it violates the host OS file name requirements (such as using the path separator or other reserved characters, they will be substituted with a placeholder). If you later rename the VM, the file and folder names will be updated to match the new name automatically.
Command Options
In addition to specifying the name or UUID of the VM, which is required, you can specify any of the following options:
- --basefolder= basefolder
-
Specifies the name of the folder in which to save the machine configuration file for the new VM.
Note that the names of the file and the folder do not change if you rename the VM.
- --default
-
Applies a default hardware configuration for the specified guest OS. By default, the VM is created with minimal hardware.
- --group= group-ID [,...]
-
Assigns the VM to the specified groups. If you specify more than one group, separate each group name with a comma.
Note that each group is identified by a group ID that starts with a slash character (
/) so that groups can be nested. By default, a VM is always assigned membership to the/group. - --ostype= ostype
-
Specifies the guest OS to run in the VM. Run the
VBoxManage list ostypescommand to see the available OS types. - --register
-
Registers the VM with your Oracle VM VirtualBox installation. By default, the
VBoxManage createvmcommand creates only the XML configuration for the VM but does not register the VM. If you do not register the VM at creation, you can run theVBoxManage registervmcommand after you create the VM. - --uuid= uuid
-
Specifies the Universally Unique Identifier (UUID) of the VM. Ensure that this UUID is unique within the Oracle VM VirtualBox namespace of the host or of its VM group memberships if you decide to register the VM. By default, Oracle VM VirtualBox provides the UUID.
- --cipher= cipher
-
Specifies the cipher to use for encryption. Valid values are
AES-128orAES-256.This option enables you to set up encryption on VM.
- --password-id= password-id
-
Specifies a new password identifier that is used for correct identification when supplying multiple passwords for the VM.
This option enables you to set up encryption on VM.
- --password= file
-
Use the --password to supply the encryption password of the VM. Either specify the absolute pathname of a password file on the host operating system, or
-to prompt you for the password on the command line.This option enables you to set up encryption on VM.
VBoxManage debugvm
Introspection and guest debugging
Synopsis
Description
The "debugvm" commands are for experts who want to tinker with the exact details of virtual machine execution. Like the VM debugger described in The Built-In VM Debugger, these commands are only useful if you are very familiar with the details of the PC architecture and how to debug software.
Common options
The subcommands of debugvm all operate on a running virtual
machine:
- uuid | vmname
-
Either the UUID or the name (case sensitive) of a VM.
debugvm dumpvmcore
Creates a system dump file of the specified VM. This file will have the standard ELF core format (with custom sections); see VM Core Format.
This corresponds to the writecore command in the debugger.
- --filename= filename
-
The name of the output file.
debugvm info
Displays info items relating to the VMM, device emulations and associated drivers.
This corresponds to the info command in the debugger.
- item
-
Name of the info item to display. The special name help will list all the available info items and hints about optional arguments.
- args
-
Optional argument string for the info item handler. Most info items does not take any extra arguments. Arguments not recognized are generally ignored.
debugvm injectnmi
Causes a non-maskable interrupt (NMI) to be injected into the guest. This might be useful for certain debugging scenarios. What happens exactly is dependent on the guest operating system, but an NMI can crash the whole guest operating system. Do not use unless you know what you're doing.
debugvm log
Changes the group settings for either debug (--debug) or release (--release) logger of the VM process.
The group-settings are typically strings on the form em.e.f.l, hm=~0 and -em.f. Basic wildcards are supported for group matching. The all group is an alias for all the groups.
Please do keep in mind that the group settings are applied as modifications to the current ones.
This corresponds to the log command in the debugger.
debugvm logdest
Changes the destination settings for either debug (--debug) or release (--release) logger of the VM process. For details on the destination format, the best source is src/VBox/Runtime/common/log/log.cpp.
The destinations is one or more mnemonics, optionally prefixed by "no" to disable them. Some of them take values after a ":" or "=" separator. Multiple mnemonics can be separated by space or given as separate arguments on the command line.
List of available destination:
- file[= file ], nofile
-
Specifies a log file. If no filename is given, one will be generated based on the current UTC time and VM process name and placed in the current directory of the VM process. Note that this will currently not have any effect if the log file has already been opened.
- dir= directory , nodir
-
Specifies the output directory for log files. Note that this will currently not have any effect if the log file has already been opened.
- history= count , nohistory
-
A non-zero value enables log historization, with the value specifying how many old log files to keep.
- histsize= bytes
-
The max size of a log file before it is historized. Default is infinite.
- histtime= seconds
-
The max age (in seconds) of a log file before it is historized. Default is infinite.
- ringbuffer, noringbuffer
-
Only log to the log buffer until an explicit flush (e.g. via an assertion) occurs. This is fast and saves diskspace.
- stdout, nostdout
-
Write the log content to standard output.
- stdout, nostdout
-
Write the log content to standard error.
- debugger, nodebugger
-
Write the log content to the debugger, if supported by the host OS.
- com, nocom
-
Writes logging to the COM port. This is only applicable for raw-mode and ring-0 logging.
- user, nouser
-
Custom destination which has no meaning to VM processes..
This corresponds to the logdest command in the debugger.
debugvm logflags
Changes the flags on either debug (--debug) or release (--release) logger of the VM process. Please note that the modifications are applied onto the existing changes, they are not replacing them.
The flags are a list of flag mnemonics, optionally prefixed by a "no", "!", "~" or "-" to negate their meaning. The "+" prefix can be used to undo previous negation or use as a separator, though better use whitespace or separate arguments for that.
List of log flag mnemonics, with their counter form where applicable (asterisk indicates defaults):
- enabled*, disabled
-
Enables or disables logging.
- buffered, unbuffered*
-
Enabling buffering of log output before it hits the destinations.
- writethrough(/writethru)
-
Whether to open the destination file with writethru buffering settings or not.
- flush
-
Enables flushing of the output file (to disk) after each log statement.
- lockcnts
-
Prefix each log line with lock counts for the current thread.
- cpuid
-
Prefix each log line with the ID of the current CPU.
- pid
-
Prefix each log line with the current process ID.
- flagno
-
Prefix each log line with the numberic flags corresponding to the log statement.
- flag
-
Prefix each log line with the flag mnemonics corresponding to the log statement.
- groupno
-
Prefix each log line with the log group number for the log statement producing it.
- group
-
Prefix each log line with the log group name for the log statement producing it.
- tid
-
Prefix each log line with the current thread identifier.
- thread
-
Prefix each log line with the current thread name.
- time
-
Prefix each log line with the current UTC wall time.
- timeprog
-
Prefix each log line with the current monotonic time since the start of the program.
- msprog
-
Prefix each log line with the current monotonic timestamp value in milliseconds since the start of the program.
- ts
-
Prefix each log line with the current monotonic timestamp value in nanoseconds.
- tsc
-
Prefix each log line with the current CPU timestamp counter (TSC) value.
- rel, abs*
-
Selects the whether ts and tsc prefixes should be displayed as relative to the previous log line or as absolute time.
- hex*, dec
-
Selects the whether the ts and tsc prefixes should be formatted as hexadecimal or decimal.
- custom
-
Custom log prefix, has by default no meaning for VM processes.
- usecrlf, uself*
-
Output with DOS style (CRLF) or just UNIX style (LF) line endings.
- overwrite*, append
-
Overwrite the destination file or append to it.
This corresponds to the logflags command in the debugger.
debugvm osdetect
Make the VMM's debugger facility (re)-detect the guest operating system (OS). This will first load all debugger plug-ins.
This corresponds to the detect command in the debugger.
debugvm osinfo
Displays information about the guest operating system (OS) previously detected by the VMM's debugger facility.
debugvm osdmesg
Displays the guest OS kernel log, if detected and supported.
- --lines= lines
-
Number of lines of the log to display, counting from the end. The default is infinite.
debugvm getregisters
Retrieves register values for guest CPUs and emulated devices.
- reg-set.reg-name
-
One of more registers, each having one of the following forms:
-
register-set.register-name.sub-field
-
register-set.register-name
-
cpu-register-name.sub-field
-
cpu-register-name
-
all
The all form will cause all registers to be shown (no sub-fields). The registers names are case-insensitive.
-
- --cpu= id
-
Selects the CPU register set when specifying just a CPU register (3rd and 4th form). The default is 0.
debugvm setregisters
Changes register values for guest CPUs and emulated devices.
- reg-set.reg-name=value
-
One of more register assignment, each having one of the following forms:
-
register-set.register-name.sub-field=value
-
register-set.register-name=value
-
cpu-register-name.sub-field=value
-
cpu-register-name=value
The value format should be in the same style as what
getregistersdisplays, with the exception that both octal and decimal can be used instead of hexadecimal. -
- --cpu= id
-
Selects the CPU register set when specifying just a CPU register (3rd and 4th form). The default is 0.
debugvm show
Shows logging settings for the VM.
- --human-readable
-
Selects human readable output.
- --sh-export
-
Selects output format as bourne shell style
exportcommands. - --sh-eval
-
Selects output format as bourne shell style
evalcommand input. - --cmd-set
-
Selects output format as DOS style
SETcommands. - settings-item
-
What to display. One or more of the following:
-
logdbg-settings - debug log settings.
-
logrel-settings - release log settings.
-
log-settings - alias for both debug and release log settings.
-
debugvm stack
Unwinds the guest CPU stacks to the best of our ability. It is
recommended to first run the osdetect command, as this
gives both symbols and perhaps unwind information.
- --cpu= id
-
Selects a single guest CPU to display the stack for. The default is all CPUs.
debugvm statistics
Displays or resets VMM statistics.
Retrieves register values for guest CPUs and emulated devices.
- --pattern= pattern
-
DOS/NT-style wildcards patterns for selecting statistics. Multiple patterns can be specified by using the '|' (pipe) character as separator.
- --reset
-
Select reset instead of display mode.
debugvm guestsample
Creates a sample report of the guest activity.
Retrieves the filename to dump the report to.
- --filename= filename
-
The filename to dump the sample report to.
- --sample-interval-us= interval
-
The interval in microseconds between guest samples.
- --sample-time-us= time
-
The amount of microseconds to take guest samples.
VBoxManage dhcpserver
DHCP server management
Synopsis