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
VBoxManage
command 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
VBoxManage
command.The short version of this option is -V.
- @response-file
-
Loads arguments from the specified Bourne shell response file.
- subcommand
-
Specifies one of the
VBoxManage
subcommands, 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:
disk
andnetwork
. 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 hdds
command 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 hdds
command 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:
-
Standard
is the default disk image type, which has a dynamically allocated file size. -
Fixed
uses a disk image that has a fixed file size. -
Split2G
indicates that the disk image is split into 2GB segments. This value is for VMDK only. -
Stream
optimizes the disk image for downloading. This value is for VMDK only. -
ESX
is 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 registervm
command. 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
,disabled
anddeleted
at 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
setlinkstate
N 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
nic
N 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:
-
null
specifies that the VM is is not connected to the host system. -
nat
specifies that the VM uses network address translation (NAT). -
bridged
specifies that the VM uses bridged networking. -
intnet
specifies that the VM communicates with other VMs by using internal networking. -
hostonly
specifies that the VM uses host-only networking. -
natnetwork
specifies that the VM uses NAT networking. -
generic
specifies that the VM has access to rarely used submodes
Trace the Network Traffic of a Virtual Machine
The VBoxManage controlvm
vmname
nictrace
N 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
nictracefile
N 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
nicpromisc
N 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
nicproperty
N
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
natpf
N 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
natpf
N 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/Ports
specifies a port or a range of ports to which the VRDE server can bind. The default value isdefault
or0
, which is the standard RDP port,3389
.Also see the --vrde-port option description in Remote Machine Settings.
-
TCP/Address
specifies 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/Enabled
specifies whether to enable the VirtualBox Remote Desktop Protocol (VRDP) video channel. Valid values are1
to enable the video channel and0
to disable the video channel. The default value isoff
. See VRDP Video Redirection. -
VideoChannel/Quality
specifies 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/DownscaleProtection
specifies whether to enable the video channel downscale protection feature. Specify1
to 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/DisableDisplay
specifies whether to disable the VRDE server display feature. Valid values are1
to disable the feature and an empty string (""
) to enable the feature. The default value is an empty string. See VRDP Customization. -
Client/DisableInput
specifies whether to disable the VRDE server input feature. Valid values are1
to disable the feature and an empty string (""
) to enable the feature. The default value is1
. See VRDP Customization. -
Client/DisableAudio
specifies whether to disable the VRDE server audio feature. Valid values are1
to disable the feature and an empty string (""
) to enable the feature. The default value is1
. See VRDP Customization. -
Client/DisableUSB
specifies whether to disable the VRDE server USB feature. Valid values are1
to disable the feature and an empty string (""
) to enable the feature. The default value is1
. See VRDP Customization. -
Client/DisableClipboard
specifies whether to disable the VRDE clipboard feature. Valid values are1
to 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/DisableUpstreamAudio
specifies whether to disable the VRDE upstream audio feature. Valid values are1
to 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/DisableRDPDR
specifies whether to disable the RDP Device Redirection For Smart Cards feature on the VRDE server. Valid values are1
to disable the feature and an empty string (""
) to enable the feature. The default value is1
. See VRDP Customization. -
H3DRedirect/Enabled
specifies whether to enable the VRDE server 3D redirection feature. Valid values are1
to enable the feature and an empty string (""
) to disable the feature. See VRDP Customization. -
Security/Method
specifies the security method to use for a connection. See RDP Encryption.-
Negotiate
accepts both enhanced (TLS) and standard RDP security connections. The security method is negotiated with the client. This is the default value. -
RDP
accepts only standard RDP security connections. -
TLS
accepts only enhanced RDP security connections. The client must support TLS.
-
-
Security/ServerCertificate
specifies the absolute path of the server certificate to use for a connection. See RDP Encryption. -
Security/ServerPrivateKey
specifies the absolute path of the server private key. See RDP Encryption. -
Security/CACertificate
specifies the absolute path of the CA self-signed certificate. See RDP Encryption. -
Audio/RateCorrectionMode
specifies the rate correction mode to use.-
VRDP_AUDIO_MODE_VOID
indicates that no mode is specified. Use this value to unset any audio mode that is already set. -
VRDP_AUDIO_MODE_RC
specifies to use the rate correction mode. -
VRDP_AUDIO_MODE_LPF
specifies to use the low pass filter mode. -
VRDP_AUDIO_MODE_CS
specifies to use the client sync mode to prevent underflow or overflow of the client queue.
-
-
Audio/LogPath
specifies 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.
-
all
specifies that you record all VM screens. -
none
specifies 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
widthx
height:
-
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
on
to enable local logins andoff
to 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
3060
bytes, 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 higherMaxPayloadTransferSize
values.
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 detach
command. -
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 controlvm
vmnamewebcam detach
command.
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:
-
Standard
is the default disk image type, which has a dynamically allocated file size. -
Fixed
uses a disk image that has a fixed file size. -
Split2G
indicates that the disk image is split into 2GB segments. This value is for VMDK only. -
Stream
optimizes the disk image for downloading. This value is for VMDK only. -
ESX
is 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 disk image output.
- bytes
-
Specifies the capacity of the targe image name. Needs to be given explicitly, because generally pipes do not support querying the overall size of the data stream.
- --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:
-
Standard
is the default disk image type, which has a dynamically allocated file size. -
Fixed
uses a disk image that has a fixed file size. -
Split2G
indicates that the disk image is split into 2GB segments. This value is for VMDK only. -
Stream
optimizes the disk image for downloading. This value is for VMDK only. -
ESX
is 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
The following command reads from disk /dev/sda
using a pipe and therefore needs the exact disk size in bytes as an
additional parameter, which is assumed to be 10737418240
.
The output file is a VDI disk image called disk.vdi
.
$ dd if=/dev/sda bs=512 | VBoxManage convertfromraw stdin disk.vdi 10737418240
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:
-
Standard
is the default disk image type, which has a dynamically allocated file size. -
Fixed
uses a disk image that has a fixed file size. -
Split2G
indicates that the disk image is split into 2GB segments. This value is valid for VMDK disk images only. -
Stream
optimizes the disk image for downloading. This value is valid for VMDK disk images only. -
ESX
is used for some VMWare products. This value is valid for VMDK disk images only. -
Formatted
formats the medium automatically. This value is valid for floppy images only. -
RawDisk
is 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=value
form. Optional. - --property-file= name = /path/to/file/with/value
-
Specifies any required file format dependent parameters in
key=file/with/value
form. 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.
- --groups= 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 ostypes
command to see the available OS types. - --register
-
Registers the VM with your Oracle VM VirtualBox installation. By default, the
VBoxManage createvm
command 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 registervm
command 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-128
orAES-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
getregisters
displays, 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
export
commands. - --sh-eval
-
Selects output format as bourne shell style
eval
command input. - --cmd-set
-
Selects output format as DOS style
SET
commands. - 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
Description
The dhcpserver
commands enable you to control the DHCP
server that is built into VirtualBox. You may find this useful when
using internal or host-only networking. Theoretically, you can also
enable it for a bridged network, but that may cause conflicts with other
DHCP servers in your physical network.
Common options
The subcommands of dhcpserver
all operate on an
internal network that can be identified via its name or in the host-only
case via the host-only interface name:
- --network=netname
-
The internal network name. This is the same as you would use as value to the
VBoxManage modifyvm --intnet
option when configuring a VM for internal networking. Or you see as VBoxNetworkName in the output fromVBoxManage list intnets
,VBoxManage list natnets
, orVBoxManage list hostonlyifs
. - --interface=ifname
-
The host only interface name. This would be same value as you would use for the
VBoxManage modifyvm --host-only-adapter
option when configuring a VM to use a host-only network. The value can also be found in the Name row inVBoxManage list hostonlyifs
.
dhcpserver add
Adds a new DHCP server to a network or host-only interface.
Options configuring the DHCP server core:
- --server-ip= address
-
The IP address the DHCP server should use.
- --lower-ip=address, --upper-ip=address
-
The IP address range for the DHCP server to manage. This should not include the address of the DHCP server itself, but it must be in the same network as it. The boundraries are inclusive, so both the lower and upper addresses will be handed out to clients.
- --netmask= mask
-
The network mask. Typically 255.255.255.0.
- --enable, --disable
-
Whether to enable the DHCP server or disable it. If not specified, the server will be created in disabled state and no IP addresses handed out.
Options selecting the scope:
- --global
-
Set the configuration scope to global. Any subsequent --set-opt options will be apply to all the DHCP clients.
- --vm= vmname|uuid
-
Set the configuration scope to the first NIC of the specified VM. Any subsequent --set-opt options will apply just to that interface, nothing else.
- --nic= 1-N
-
Set the configuration scope to a NIC other than first of the VM specified the in --vm.
- --mac-address= address
-
Set the configuration scope to the specified MAC address.
- --group= name
-
Set the configuration scope to the specified group.
Options configuring the currently selected scope:
- --set-opt= dhcp-opt-no value
-
Adds the specified DHCP option number (0-255) and value. The value format is option specific (typically human readable) and will be validated by the API and the DHCP server.
- --set-opt-hex= dhcp-opt-no hexstring
-
Adds the specified DHCP option number (0-255) and value. The option value is specified as a raw series of hex bytes, optionally separated by colons. No validation is performed on these by the API or the DHCP server, they will be pass as specified to the client.
- --force-opt= dhcp-opt-no
-
Forces the specified DHCP option number (0-255) onto to be sent to the client whether it requested it or not (provided the option is configured with a value at some level).
- --suppress-opt= dhcp-opt-no
-
Prevents the specified DHCP option number (0-255) from being sent to the client when present in this or a high configuration scope.
- --min-lease-time= seconds
-
Sets the minimum lease time for the current scope in seconds. Zero means taking the value from a higher option level or use default.
- --default-lease-time= seconds
-
Sets the default lease time for the current scope in seconds. Zero means taking the value from a higher option level or use default.
- --max-lease-time= seconds
-
Sets the maximum lease time for the current scope in seconds. Zero means taking the value from a higher option level or use default.
- --fixed-address= address
-
Fixed address assignment for a --vm or --mac-address configuration scope. Any empty address turns it back to dynamic address assignment.
Options configuring group membership conditions (excludes overrides includes):
- --incl-mac= address
-
Include the specific MAC address in the group.
- --excl-mac= address
-
Exclude the specific MAC address from the group.
- --incl-mac-wild= pattern
-
Include the specific MAC address pattern in the group.
- --excl-mac-wild= pattern
-
Exclude the specific MAC address pattern from the group.
- --incl-vendor= string
-
Include the specific vendor class ID in the group.
- --excl-vendor= string
-
Exclude the specific vendor class ID from the group.
- --incl-vendor-wild= pattern
-
Include the specific vendor class ID pattern in the group.
- --excl-vendor-wild= pattern
-
Exclude the specific vendor class ID pattern from the group.
- --incl-user= string
-
Include the specific user class ID in the group.
- --excl-user= string
-
Exclude the specific user class ID from the group.
- --incl-user-wild= pattern
-
Include the specific user class ID pattern in the group.
- --excl-user-wild= pattern
-
Exclude the specific user class ID pattern from the group.
dhcpserver modify
This modifies an existing DHCP server configuration. It takes the same
options as the add
command with the addition of the following
on scope configuration:
- --del-opt= dhcp-opt-no
-
Counterpart to --set-opt that will cause the specified DHCP option number (0-255) to be deleted from the server settings. Like with --set-opt the scope of the deletion is governed by the --global, --vm, --mac-address and --group options.
- --unforce-opt= dhcp-opt-no
-
Removes the specified DHCP option number (0-255) from the forced option list (i.e. the reverse of --force-opt). Like with --set-opt the scope of the deletion is governed by the --global, --vm, --mac-address and --group options.
- --unsuppress-opt= dhcp-opt-no
-
Removes the specified DHCP option number (0-255) from the supressed option list (i.e. the reverse of --suppress-opt). Like with --set-opt the scope of the deletion is governed by the --global, --vm, --mac-address and --group options.
- --remove-config
-
Removes the configuration currently being scoped. The --global scope is not removable. The configuration scope will change to --global after this option.
And the addition of these group membership condition options:
- --del-mac= address
-
Delete the specific MAC address from the group conditions.
- --del-mac-wild= pattern
-
Delete the specific MAC address pattern from the group conditions.
- --del-vendor= string
-
Delete the specific vendor class ID from the group conditions.
- --del-vendor-wild= pattern
-
Delete the specific vendor class ID pattern from the group conditions.
- --del-user= string
-
Delete the specific user class ID from the group conditions.
- --del-user-wild= pattern
-
Delete the specific user class ID pattern from the group conditions.
- --zap-conditions
-
Deletes all the group conditions.
dhcpserver remove
Removes the specified DHCP server.
dhcpserver start
Start the specified DHCP server.
dhcpserver restart
Restarts the specified DHCP server. The DHCP server must be running.
dhcpserver stop
Stops the specified DHCP server.
dhcpserver findlease
Performs a lease database lookup. This is mainly for getting the IP address of a running VM.
- --mac-address= mac
-
The MAC address to lookup in the lease database.
Common DHCP Options:
- 1 - SubnetMask
-
IPv4 netmask. Set to the value of the --netmask option by default.
- 2 - TimeOffset
-
UTC offset in seconds (32-bit decimal value).
- 3 - Routers
-
Space separated list of IPv4 router addresses.
- 4 - TimeServers
-
Space separated list of IPv4 time server (RFC 868) addresses.
- 5 - NameServers
-
Space separated list of IPv4 name server (IEN 116) addresses.
- 6 - DomainNameServers
-
Space separated list of IPv4 DNS addresses.
- 7 - LogServers
-
Space separated list of IPv4 log server addresses.
- 8 - CookieServers
-
Space separated list of IPv4 cookie server (RFC 865) addresses.
- 9 - LPRServers
-
Space separated list of IPv4 line printer server (RFC 1179) addresses.
- 10 - ImpressServers
-
Space separated list of IPv4 imagen impress server addresses.
- 11 - ResourseLocationServers
-
Space separated list of IPv4 resource location (RFC 887) addresses.
- 12 - HostName
-
The client name. See RFC 1035 for character limits.
- 13 - BootFileSize
-
Number of 512 byte blocks making up the boot file (16-bit decimal value).
- 14 - MeritDumpFile
-
Client core file.
- 15 - DomainName
-
Domain name for the client.
- 16 - SwapServer
-
IPv4 address of the swap server that the client should use.
- 17 - RootPath
-
The path to the root disk the client should use.
- 18 - ExtensionPath
-
Path to a file containing additional DHCP options (RFC2123).
- 19 - IPForwarding
-
Whether IP forwarding should be enabled by the client (boolean).
- 20 - OptNonLocalSourceRouting
-
Whether non-local datagrams should be forwarded by the client (boolean)
- 21 - PolicyFilter
-
List of IPv4 addresses and masks paris controlling non-local source routing.
- 22 - MaxDgramReassemblySize
-
The maximum datagram size the client should reassemble (16-bit decimal value).
- 23 - DefaultIPTTL
-
The default time-to-leave on outgoing (IP) datagrams (8-bit decimal value).
- 24 - PathMTUAgingTimeout
-
RFC1191 path MTU discovery timeout value in seconds (32-bit decimal value).
- 25 - PathMTUPlateauTable
-
RFC1191 path MTU discovery size table, sorted in ascending order (list of 16-bit decimal values).
- 26 - InterfaceMTU
-
The MTU size for the interface (16-bit decimal value).
- 27 - AllSubnetsAreLocal
-
Indicates whether the MTU size is the same for all subnets (boolean).
- 28 - BroadcastAddress
-
Broadcast address (RFC1122) for the client to use (IPv4 address).
- 29 - PerformMaskDiscovery
-
Whether to perform subnet mask discovery via ICMP (boolean).
- 30 - MaskSupplier
-
Whether to respond to subnet mask requests via ICMP (boolean).
- 31 - PerformRouterDiscovery
-
Whether to perform router discovery (RFC1256) (boolean).
- 32 - RouterSolicitationAddress
-
Where to send router solicitation requests (RFC1256) (IPv4 address).
- 33 - StaticRoute
-
List of network and router address pairs addresses.
- 34 - TrailerEncapsulation
-
Whether to negotiate the use of trailers for ARP (RTF893) (boolean).
- 35 - ARPCacheTimeout
-
The timeout in seconds for ARP cache entries (32-bit decimal value).
- 36 - EthernetEncapsulation
-
Whether to use IEEE 802.3 (RTF1042) rather than of v2 (RFC894) ethernet encapsulation (boolean).
- 37 - TCPDefaultTTL
-
Default time-to-live for TCP sends (non-zero 8-bit decimal value).
- 38 - TCPKeepaliveInterval
-
The interface in seconds between TCP keepalive messages (32-bit decimal value).
- 39 - TCPKeepaliveGarbage
-
Whether to include a byte of garbage in TCP keepalive messages for backward compatibility (boolean).
- 40 - NISDomain
-
The NIS (Sun Network Information Services) domain name (string).
- 41 - NISServers
-
Space separated list of IPv4 NIS server addresses.
- 42 - NTPServers
-
Space separated list of IPv4 NTP (RFC1035) server addresses.
- 43 - VendorSpecificInfo
-
Vendor specific information. Only accessible using --set-opt-hex.
- 44 - NetBIOSNameServers
-
Space separated list of IPv4 NetBIOS name server (NBNS) addresses (RFC1001,RFC1002).
- 45 - NetBIOSDatagramServers
-
Space separated list of IPv4 NetBIOS datagram distribution server (NBDD) addresses (RFC1001,RFC1002).
- 46 - NetBIOSNodeType
-
NetBIOS node type (RFC1001,RFC1002): 1=B-node, 2=P-node, 4=M-node, and 8=H-node (8-bit decimal value).
- 47 - NetBIOSScope
-
NetBIOS scope (RFC1001,RFC1002). Only accessible using --set-opt-hex.
- 48 - XWindowsFontServers
-
Space separated list of IPv4 X windows font server addresses.
- 49 - XWindowsDisplayManager
-
Space separated list of IPv4 X windows display manager addresses.
- 62 - NetWareIPDomainName
-
Netware IP domain name (RFC2242) (string).
- 63 - NetWareIPInformation
-
Netware IP information (RFC2242). Only accessible using --set-opt-hex.
- 64 - NISPlusDomain
-
The NIS+ domain name (string).
- 65 - NISPlusServers
-
Space separated list of IPv4 NIS+ server addresses.
- 66 - TFTPServerName
-
TFTP server name (string).
- 67 - BootfileName
-
Bootfile name (string).
- 68 - MobileIPHomeAgents
-
Space separated list of IPv4 mobile IP agent addresses.
- 69 - SMTPServers
-
Space separated list of IPv4 simple mail transport protocol (SMPT) server addresses.
- 70 - POP3Servers
-
Space separated list of IPv4 post office protocol 3 (POP3) server addresses.
- 71 - NNTPServers
-
Space separated list of IPv4 network news transport protocol (NTTP) server addresses.
- 72 - WWWServers
-
Space separated list of default IPv4 world wide web (WWW) server addresses.
- 73 - FingerServers
-
Space separated list of default IPv4 finger server addresses.
- 74 - IRCServers
-
Space separated list of default IPv4 internet relay chat (IRC) server addresses.
- 75 - StreetTalkServers
-
Space separated list of IPv4 StreetTalk server addresses.
- 76 - STDAServers
-
Space separated list of IPv4 StreetTalk directory assistance (STDA) server addresses.
- 78 - SLPDirectoryAgent
-
Addresses of one or more service location protocol (SLP) directory agent, and an indicator of whether their use is mandatory. Only accessible using --set-opt-hex.
- 79 - SLPServiceScope
-
List of service scopes for the service location protocol (SLP) and whether using the list is mandator. Only accessible using --set-opt-hex.
- 119 - DomainSearch
-
Domain search list, see RFC3397 and section 4.1.4 in RFC1035 for encoding. Only accessible using --set-opt-hex.
VBoxManage discardstate
Discard the saved state of a virtual machine
Description
The VBoxManage discardstate
command discards
the saved state of a virtual machine (VM) that is not currently
running. This command causes the VM's operating system to restart
the next time you start the VM.
Note:
Where possible, avoid performing this action. The effects of this command are equivalent to unplugging the power cable on a physical machine.
- uuid | vmname
-
Specifies the Universally Unique Identifier (UUID) or name of the VM.
VBoxManage encryptmedium
Manage a DEK-encrypted medium or image
Synopsis
Description
The VBoxManage encryptmedium
command enables
you to create and manage a DEK-encrypted medium or image. You can
encrypt an image, decrypt an image, and change the encryption
password of an image. See
Encrypting Disk Images.
- uuid | filename
-
Specifies the Universally Unique Identifier (UUID) or the absolute path name of the medium or image to encrypt.
- --newpassword= password
-
Specifies the new encryption password. password is either the absolute path name of a password file on the host operating system or
-
, which prompts you for the password.You must use the --newpasswordid option with this --newpassword option.
- --oldpassword= password
-
Specifies the original encryption password. password is either the absolute path name of a password file on the host operating system or
-
, which prompts you for the original password.This option enables you to gain access to an encrypted medium or image to do the following:
-
Decrypt an encrypted image by using this option by itself.
-
Change the password of the encrypted image by using the --newpassword option.
-
Change the encryption cipher of the image by using the --cipher option.
-
- --cipher= cipher-ID
-
Specifies the cipher to use for encryption. Valid values are
AES-XTS128-PLAIN64
orAES-XTS256-PLAIN64
.This option enables you to set up or change encryption on the medium or image.
- --newpasswordid= password-ID
-
Specifies a new password identifier that is used for correct identification when supplying multiple passwords during VM startup.
If you use the same password and password identifier when encrypting multiple images, you need to supply the password only one time during VM startup.
Examples
The following example shows how to encrypt the
ol7u4-1.vdi
image by using the
AES-XTS128-PLAIN64
cipher, specifying a
password identifier of 1001
, and using the
$HOME/pwfile
password file:
$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-1.vdi" \ --cipher="AES-XTS128-PLAIN64" --newpasswordid="1001" --newpassword=$HOME/pwfile
The following example shows how to decrypt an encrypted image
called ol7u4-2.vdi
:
$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-2.vdi" \
--oldpassword=-
Password: original-password
The following example shows how to change the password for an
encrypted image called ol7u4-3.vdi
. The
command reads the original password from the
$HOME/pwfile.orig
file, reads the new
password from the $HOME/pwfile
file, and
assigns a password identifier of 1001
.
$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-3.vdi" \ --oldpassword=$HOME/pwfile.orig --newpassword=$HOME/pwfile --newpasswordid="1001"
VBoxManage encryptvm
Change encryption and passwords of the VM
Synopsis
Description
The VBoxManage encryptvm
command enables you to
change the encryption or add and remove user passwords for the
virtual machine (VM). The following sections describe the subcommands
that you can use:
Set encryption of the Virtual Machine
The VBoxManage encryptvm
vmname setencryption
command
changes encryption of a VM.
Use the --old-password to supply old encryption
password. Either specify the absolute pathname of a password file
on the host operating system, or -
to prompt
you for the old password.
Use the --cipher option to specify the
new cipher for encryption of the VM. Only AES-128
and AES-256
are supported. Appropriate mode
GCM, CTR or XTS will be selected by VM depending on encrypting
component.
Use the --new-password option to specify the
new password for encryption of the VM. Either specify the absolute
pathname of a password file on the host operating system, or
-
to prompt you for the new password.
Use the --new-password-id option to specify the new id for the password for encryption of the VM.
Use the --force option to make the system to reencrypt the VM instead of simple changing the password.
Check the supplied password is correct
The VBoxManage encryptvm
vmname checkpassword
command
checks the correctness of the supplied password.
The password can be supplied from file. Specify the absolute
pathname of a password file on the host operating system. Also,
you can specify -
to prompt you for the password.
Add password for decrypting the Virtual Machine
The VBoxManage encryptvm
vmname addpassword
command
adds a password for decrypting the VM.
Use the --password to supply the encryption
password. Either specify the absolute pathname of a password file
on the host operating system, or -
to prompt
you for the password.
Use the --password-id option to specify the id the password is supplied for.
Remove password used for decrypting the Virtual Machine
The VBoxManage encryptvm
vmname removepassword
command
removes a password used for decrypting the VM.
Specify the password identifier for removing. The password becomes unknown and the VM can not be decrypted.
VBoxManage export
Export one or more virtual machines to a virtual appliance or to a cloud service
Synopsis
Description
The VBoxManage export
command enables you to
export one or more virtual machines (VMs) from Oracle VM VirtualBox. You
can export the VM to one of the following:
-
Virtual appliance in OVF format. Includes the copying of its virtual disk images to compressed VMDK.
-
Cloud service such as Oracle Cloud Infrastructure. Exports a single VM.
For more information about exporting VMs from Oracle VM VirtualBox, see Importing and Exporting Virtual Machines
Export a Virtual Machine to an OVF Virtual Appliance
The VBoxManage export
command enables you to
export a VM as a virtual appliance in OVF format.
- machines
-
Specifies a comma-separated list of one or more machines to export to the same OVF file.
- --output= filename
-
Specifies the target OVF file. The file can be OVF, OVA, or a ZIP file compressed with the
gzip
command. Because the directory that contains the target OVF file will also store the exported disk images in the compressed VMDK format, ensure that this directory has sufficient disk space in which to store the images.The short form of this option is -o.
- --legacy09
-
Exports in OVF 0.9 legacy mode if the virtualization product is not fully compatible with the OVF 1.0 standard.
- --ovf09
-
Exports in OVF 0.9 format.
- --ovf10
-
Exports in OVF 1.0 format.
- --ovf20
-
Exports in OVF 2.0 format.
- --manifest
-
Creates a manifest of the exported files.
- --options= argument ,...
-
Specifies information to control the exact content of the appliance file. Specify one or more comma-separated arguments:
-
manifest
-
Produces a manifest file that detects corrupted appliances on import.
-
iso
-
Exports DVD images in an ISO file.
-
nomacs
-
Excludes all MAC addresses.
-
nomacsbutnat
-
Excludes all MAC addresses except for those in a NAT network.
-
- --description= description-info
-
Specifies a description of the VM.
- --eula= license-text
-
Specifies end-user license text.
- --eulafile= filename
-
Specifies an end-user license file.
- --product= product-name
-
Specifies a product name.
- --producturl= product-URL
-
Specifies a product URL.
- --vendor= vendor-name
-
Specifies a vendor name.
- --vendorurl= vendor-URL
-
Specifies a vendor URL.
- --version= version-info
-
Specifies version information.
- --vmname= vmname
-
Specifies the name of the exported VM.
- --vsys= virtual-system-number
-
Specifies the number of the virtual system.
Export a Virtual Machine to Oracle Cloud Infrastructure
The VBoxManage export
command enables you to
export a VM to a cloud service provider such as Oracle Cloud Infrastructure. By
default, the exported disk image is converted into compressed VMDK
format. This minimizes the amount of data to transfer to the cloud
service.
Some of the following options are configuration settings for the VM instance. As a result, specify an Oracle Cloud Identifier (OCID) for a resource. Use the Oracle Cloud Infrastructure Console to view OCIDs.
- --output= cloud-service-provider
-
Specifies the short name of the cloud service provider to which you export the VM. For Oracle Cloud Infrastructure, specify
OCI://
.The short form of this option is -o.
- --opc10
-
Exports in Oracle Cloud Infrastructure format.
- --cloud= number-of-virtual-system
-
Specifies a number that identifies the VM to export. Numbering starts at
0
for the first VM. - --vmname= vmname
-
Specifies the name of the exported VM, which is used as the VM instance name in Oracle Cloud Infrastructure.
- --cloudprofile= cloud-profile-name
-
Specifies the cloud profile to use to connect to the cloud service provider. The cloud profile contains your Oracle Cloud Infrastructure account details, such as your user OCID and the fingerprint for your public key.
To use a cloud profile, you must have the required permissions on Oracle Cloud Infrastructure.
- --cloudshape= cloud-shape-name
-
Specifies the shape used by the VM instance. The shape defines the number of CPUs and the amount of memory that is allocated to the VM instance. Ensure that the shape is compatible with the exported image.
- --clouddomain= cloud-domain
-
Specifies the availability domain to use for the VM instance. Enter the full name of the availability domain.
- --clouddisksize= disk-size-in-GB
-
Specifies the amount of disk space, in gigabytes, to use for the exported disk image. Valid values are from 50 GB to 300 GB.
- --cloudbucket= bucket-name
-
Specifies the bucket in which to store uploaded files. In Oracle Cloud Infrastructure, a bucket is a logical container for storing objects.
- --cloudocivcn= OCI-VCN-ID
-
Specifies the OCID of the virtual cloud network (VCN) to use for the VM instance.
- --cloudocisubnet= OCI-subnet-ID
-
Specifies the OCID of the VCN subnet to use for the VM instance.
- --cloudkeepobject=true | false
-
Specifies whether to store the exported disk image in Oracle Object Storage.
- --cloudlaunchinstance=true | false
-
Specifies whether to start the VM instance after the export to Oracle Cloud Infrastructure completes.
- --cloudlaunchinstance=EMULATED | PARAVIRTUALIZED
-
Specifies the launch mode used for the instance. Paravirtualized mode gives improved performance.
- --cloudpublicip=true | false
-
Specifies whether to enable a public IP address for the VM instance.
Example
The following example shows how to export the
myVM
VM to Oracle Cloud Infrastructure. The command's option
arguments describe the configuration of the
myVM_Cloud
VM in Oracle Cloud Infrastructure.
# VBoxManage export myVM --output=OCI:// --cloud=0 --vmname=myVM_Cloud \ --cloudprofile="standard user" --cloudbucket=myBucket \ --cloudshape=VM.Standard2.1 --clouddomain=US-ASHBURN-AD-1 --clouddisksize=50 \ --cloudocivcn=ocid1.vcn.oc1.iad.aaaa... --cloudocisubnet=ocid1.subnet.oc1.iad.aaaa... \ --cloudkeepobject=true --cloudlaunchinstance=true --cloudpublicip=true
VBoxManage extpack
Extension package management
Synopsis
Description
extpack install
Installs a new extension pack on the system. This command will fail if an older version of the same extension pack is already installed. The --replace option can be used to uninstall any old package before the new one is installed.
- --replace
-
Uninstall existing extension pack version.
- --accept-license= sha256
-
Accept the license text with the given SHA-256 hash value.
VBoxManage will display the SHA-256 value when performing a manual installation. The hash can of course be calculated by looking inside the extension pack and using sha256sum or similar on the license file.
- tarball
-
The file containing the extension pack to be installed.
extpack uninstall
Uninstalls an extension pack from the system. The subcommand will also succeed in the case where the specified extension pack is not present on the system. You can use VBoxManage list extpacks to show the names of the extension packs which are currently installed.
- --force
-
Overrides most refusals to uninstall an extension pack
- name
-
The name of the extension pack to be uninstalled.
Examples
$ VBoxManage list extpacks Extension Packs: 1 Pack no. 0: Oracle VM VirtualBox Extension Pack Version: 4.1.12 Revision: 77218 Edition: Description: USB 2.0 Host Controller, VirtualBox RDP, PXE ROM with E1000 support. VRDE Module: VBoxVRDP Usable: true Why unusable:
$ VBoxManage extpack uninstall "Oracle VM VirtualBox Extension Pack" 0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% Successfully uninstalled "Oracle VM VirtualBox Extension Pack".
VBoxManage getextradata
View keyword values that are associated with a virtual machine or configuration
Description
The VBoxManage getextradata
command enables you
to retrieve keyword data that is associated with a virtual machine
(VM) or with an Oracle VM VirtualBox configuration.
-
global
-
Specifies to retrieve information about the configuration rather than a VM.
- uuid | vmname
-
Specifies the Universally Unique Identifier (UUID) or name of the VM.
-
enumerate
-
Shows all keyword values for the specified VM or configuration.
- keyword
-
Specifies the keyword for which to retrieve its value.
Examples
The following command retrieves the installdate
keyword value for the Fedora5
VM:
$ VBoxManage getextradata Fedora5 installdate
VirtualBox Command Line Management Interface Version version-number
Copyright (C) 2005-2023 Oracle and/or its affiliates
Value: 2006.01.01
The following command retrieves the information for all keywords
of the OracleLinux7u4
VM:
$ VBoxManage getextradata OracleLinux7u4 enumerate Key: GUI/LastCloseAction, Value: PowerOff Key: GUI/LastGuestSizeHint, Value: 1048,696 Key: GUI/LastNormalWindowPosition, Value: 851,286,1048,738
The following command retrieves the information for all keywords in the configuration:
$ VBoxManage getextradata global enumerate Key: GUI/Details/Elements, Value: general,system,preview,display,storage,audio,network,usb,sharedFolders,description Key: GUI/DetailsPageBoxes, Value: general,system,preview,display,storage,audio,network,usb,sharedFolders,description Key: GUI/GroupDefinitions/, Value: m=43349dd8-2aa3-41b8-988f-0e255ce68090,m=9ebcd81e-5231-48ce-a27d-28218757f3fe,m=c690e8b1-93a0-4c95-9cd7-6437fff93251,m=f7c1e10d-3722-4891-887e-07b3c4104946 Key: GUI/HideDescriptionForWizards, Value: NewVM Key: GUI/LastItemSelected, Value: m=ol7u4 Key: GUI/LastWindowPosition, Value: 951,510,960,520 Key: GUI/RecentFolderCD, Value: C:/Users/user1 Key: GUI/RecentListCD, Value: C:\Users\user1\V1.iso,C:\Users\user1\V2.iso,C:\Users\user1\V3.iso Key: GUI/SplitterSizes, Value: 318,637 Key: GUI/SuppressMessages, Value: remindAboutMouseIntegration,remindAboutAutoCapture Key: GUI/Toolbar/MachineTools/Order, Value: Details Key: GUI/Tools/LastItemsSelected, Value: Welcome,Details Key: GUI/UpdateCheckCount, Value: 71 Key: GUI/UpdateDate, Value: 1 d, 2019-04-10, stable, 5.2.22 Key: GUI/VirtualMediaManager/Details/Expanded, Value: true
VBoxManage guestcontrol
Control a virtual machine from the host system
Synopsis
Description
The VBoxManage guestcontrol
command enables you
to control a guest (VM) from the host system. See
Guest Control of Applications.
Common Options and Operands
The following options can be used by any of the
VBoxManage guestcontrol
subcommands:
- uuid | vmname
-
Specifies the Universally Unique Identifier (UUID) or name of the VM.
- --quiet
-
Specifies that the command produce quieter output.
The short form of this option is -q.
- --verbose
-
Specifies that the command produce more detailed output.
The short form of this option is -v.
Some of the VBoxManage guestcontrol
subcommands require that you provide guest credentials for
authentication. The subcommands are:
copyfrom
, copyto
,
fsinfo
,
mkdir
, mktemp
,
mv
, rmdir
,
rm
, run
,
start
, and stat
.
While you cannot perform anonymous executions, a user account password is optional and depends on the guest's OS security policy. If a user account does not have an associated password, specify an empty password. On OSes such as Windows, you might need to adjust the security policy to permit user accounts with an empty password. In additional, global domain rules might apply and therefore cannot be changed.
The following options are used for authentication on the guest VM:
- --domain= domainname
-
Specifies the user domain for Windows guest VMs.
- --password= password
-
Specifies the password for the specified user. If you do not specify a password on the command line or if the password file is empty, the specified user needs to have an empty password.
- --passwordfile= filename
-
Specifies the absolute path to a file on the guest OS that contains the password for the specified user. If the password file is empty or if you do not specify a password on the command line, the specified user needs to have an empty password.
- --username= username
-
Specifies an existing user on the guest OS that runs the process. If unspecified, the host user runs the process.
Guest Process Restrictions
By default, you can run up to five guest processes simultaneously. If a new guest process starts and would exceed this limit, the oldest not-running guest process is discarded to run the new process. You cannot retrieve output from a discarded guest process. If all five guest processes are active and running, attempting to start a new guest process fails.
You can modify the guest process execution limit in two ways:
-
Use the
VBoxManage setproperty
command to update the/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept
guest property value. -
Use the
VBoxService
command and specify the --control-procs-max-kept=value option.
After you change the limit, you must restart the guest OS.
You can serve an unlimited number guest processes by specifing a
value of 0
, however this action is not
recommended.
Run a Command on the guest
The VBoxManage guestcontrol
vmname run
command enables
you to execute a program on the guest VM. Standard input,
standard output, and standard error are redirected from the VM
to the host system until the program completes.
Note:
The Windows OS imposes certain limitations for graphical applications. See Known Limitations.
- --exe= path-to-executable
-
Specifies the absolute path of the executable program to run on the guest VM. For example:
C:\Windows\System32\calc.exe
. - --cwd= path-to-directory
-
Specifies the absolute path of a directory in which to start the program. Optional. The directory must exist and be accessible to the guest user. For example:
C:\Users\production\work_area
.The short form of this option is -C.
- --timeout= msec
-
Specifies the maximum amount of time, in milliseconds, that the program can run. While the program runs,
VBoxManage
receives its output.If you do not specify a timeout value,
VBoxManage
waits indefinitely for the process to end, or for an error to occur. - --putenv= NAME =[ value ]
-
Sets, modifies, and unsets environment variables in the guest VM environment.
When you create a guest process, it runs with the default standard guest OS environment. Use this option to modify environment variables in that default environment.
Use the --putenv=NAME=[value] option to set or modify the environment variable specified by NAME.
Use the --putenv=NAME=[value] option to unset the environment variable specified by NAME.
Ensure that any environment variable name or value that includes spaces is enclosed by quotes.
Specify a --putenv option for each environment variable that you want to modify.
The short form of this option is -E.
- --unquoted-args
-
Disables the escaped double quoting of arguments that you pass to the program. For example,
\"fred\"
. - --ignore-orphaned-processes
-
Ignores orphaned processes. Not yet implemented.
- --profile
-
Uses a shell profile to specify the environment to use. Not yet implemented.
- --no-wait-stdout
-
Does not wait for the guest process to end or receive its exit code and any failure explanation.
- --wait-stdout
-
Waits for the guest process to end to receive its exit code and any failure explanation. The
VBoxManage
command receives the standard output of the guest process while the process runs. - --no-wait-stderr
-
Does not wait for the guest process to end to receive its exit code, error messages, and flags.
- --wait-stderr
-
Waits for the guest process to end to receive its exit code, error messages, and flags. The
VBoxManage
command receives the standard error of the guest process while the process runs. - --dos2unix
-
Transform DOS or Windows guest output to UNIX or Linux output. This transformation changes CR + LF line endings to LF. Not yet implemented.
- --unix2dos
-
Transform UNIX or Linux guest output to DOS or Windows output. This transformation changes LF line endings to CR + LF.
- --[ argument ...]
-
Specifies the name of the program and any arguments to pass to the program.
Ensure that any command argument that includes spaces is enclosed by quotes.
Start a Command on the guest
The VBoxManage guestcontrol
vmname start
command
enables you to execute a guest program until it completes.
Note:
The Windows OS imposes certain limitations for graphical applications. See Known Limitations.
Copy a file from the guest to the host.
The VBoxManage guestcontrol
vmname copyfrom
command
enables you to copy a file from the guest VM to the host system.
- --dereference
-
Enables following of symbolic links on the guest file system.
- --no-replace
-
Only copies a file if it does not exist on the host yet.
The short form of this option is -n.
- --recursive
-
Recursively copies files and directories from the specified guest directory to the host.
The short form of this option is -R.
- --target-directory= host-dst-dir
-
Specifies the absolute path of the destination directory on the host system. For example,
C:\Temp
. - --update
-
Only copies a file if the guest file is newer than on the host.
The short form of this option is -u.
- guest-source0 [ guest-source1 [...]]
-
Specifies the absolute path of one or more files to copy from the guest VM. For example,
C:\Windows\System32\calc.exe
. You can use wildcards to specify multiple files. For example,C:\Windows\System*\*.dll
.
Copy a file from the host to the guest.
The VBoxManage guestcontrol
vmname copyto
command
enables you to copy a file from the host system to the guest VM.
- --dereference
-
Enables following of symbolic links on the host system.
- --no-replace
-
Only copies a file if it does not exist on the guest yet.
The short form of this option is -n.
- --recursive
-
Recursively copies files and directories from the specified host directory to the guest.
The short form of this option is -R.
- --target-directory= guest-dst-dir
-
Specifies the absolute path of the destination directory on the guest. For example,
/home/myuser/fromhost
. - --update
-
Only copies a file if the host file is newer than on the guest.
The short form of this option is -u.
- host-source0 [ host-source1 [...]]
-
Specifies the absolute path of a file to copy from the host system. For example,
C:\Windows\System32\calc.exe
. You can use wildcards to specify multiple files. For example,C:\Windows\System*\*.dll
.
Show guest filesystem information.
The VBoxManage guestcontrol
vmname fsinfo
command
enables you to show filesystem information of the guest VM.
An alternate form of this subcommand is df
.
- --human-readable
-
Shows the disk sizes in a human readable form.
- --total
-
Produces a grand total of all disk sizes.
- guest-path [ guest-path ...]
-
Specifies an absolute path to show guest filesystem information for.
Create a directory on the guest.
The VBoxManage guestcontrol
vmname mkdir
command
enables you to create one or more directories on the guest VM.
Alternate forms of this subcommand are md
,
createdir
, and
createdirectory
.
- --parents
-
Creates any of the missing parent directories of the specified directory.
For example, if you attempt to create the
D:\Foo\Bar
directory and theD:\Foo
directory does not exist, using the --parents creates the missingD:\Foo
directory. However, if you attempt to create theD:\Foo\Bar
and do not specify the --parents option, the command fails. - --mode= mode
-
Specifies the permission mode to use for the specified directory. If you specify the --parents option, the mode is used for the associated parent directories, as well. mode is a four-digit octal mode such as
0755
. - guest-dir [ guest-dir ...]
-
Specifies an absolute path of one or more directories to create on the guest VM. For example,
D:\Foo\Bar
.If all of the associated parent directories do not exist on the guest VM, you must specify the --parents option.
You must have sufficient rights on the guest VM to create the specified directory and its parent directories.
Remove a directory from the guest.
The VBoxManage guestcontrol
vmname rmdir
command
enables you to delete the specified directory from the guest VM.
Alternate forms of this subcommand are
removedir
and
removedirectory
.
- --recursive
-
Recursively removes directories from the specified from the guest VM.
The short form of this option is -R.
- guest-dir [ guest-dir ...]
-
Specifies an absolute path of one or more directories to remove from the guest VM. You can use wildcards to specify the directory names. For example,
D:\Foo\*Bar
.You must have sufficient rights on the guest VM to remove the specified directory and its parent directories.
Remove a file from the guest.
The VBoxManage guestcontrol
vmname rm
command enables
you to delete the specified files from the guest VM.
The alternate form of this subcommand is
removefile
.
- --force
-
Forces the operation and overrides any confirmation requests.
The short form of this option is -f.
- guest-file [ guest-file ...]
-
Specifies an absolute path of one or more file to remove from the guest VM. You can use wildcards to specify the file names. For example,
D:\Foo\Bar\text*.txt
.You must have sufficient rights on the guest VM to remove the specified file.
Rename a file or Directory on the guest
The VBoxManage guestcontrol
vmname mv
command enables
you to rename files and directories on the guest VM.
Alternate forms of this subcommand are move
,
ren
, and rename
.
- guest-source [ guest-source ...]
-
Specifies an absolute path of a file or a single directory to move or rename on the guest VM. You can use wildcards to specify the file names.
You must have sufficient rights on the guest VM to access the specified file or directory.
- dest
-
Specifies the absolute path of the renamed file or directory, or the destination directory to which to move the files. If you move only one file, dest can be a file or a directory, otherwise dest must be a directory.
You must have sufficient rights on the guest VM to access the destination file or directory.
Create a Temporary File or Directory on the guest
The VBoxManage guestcontrol
vmname mktemp
command
enables you to create a temporary file or temporary directory on
the guest VM. You can use this command to assist with the
subsequent copying of files from the host system to the guest
VM. By default, this command creates the file or directory in
the guest VM's platform-specific temp
directory.
Alternate forms of this subcommand are
createtemp
and
createtemporary
.
- --directory
-
Creates a temporary directory that is specified by the template operand.
- --secure
-
Enforces secure file and directory creation by setting the permission mode to
0755
. Any operation that cannot be performed securely fails. - --mode= mode
-
Specifies the permission mode to use for the specified directory. mode is a four-digit octal mode such as
0755
. - --tmpdir= directory
-
Specifies the absolute path of the directory on the guest VM in which to create the specified file or directory. If unspecified, directory is the platform-specific
temp
directory. - template
-
Specifies a template file name for the temporary file, without a directory path. The template file name must contain at least one sequence of three consecutive X characters, or must end in X.
Show a file or File System Status on the guest
The VBoxManage guestcontrol
vmname stat
command enables
you to show the status of files or file systems on the guest VM.
- file [ file ...]
-
Specifies an absolute path of a file or file system on the guest VM. For example,
/home/foo/a.out
.You must have sufficient rights on the guest VM to access the specified files or file systems.
List the Configuration and Status Information for a Guest Virtual Machine
The VBoxManage guestcontrol
vmname list
command enables
you to list guest control configuration and status information.
For example, the output shows open guest sessions, guest
processes, and files.
all
|sessions
|processes
|files
-
Indicates the type of information to show.
all
shows all available data,sessions
shows guest sessions,processes
shows processes, andfiles
shows files.
Terminate a Process in a guest Session
The VBoxManage guestcontrol
vmname closeprocess
command
enables you to terminate a guest process that runs in a guest
session. Specify the process by using a process identifier (PID)
and the session by using the session ID or name.
- --session-id= ID
-
Specifies the ID of the guest session.
- --session-name= name | pattern
-
Specifies the name of the guest session. Use a pattern that contains wildcards to specify multiple sessions.
- PID [ PID ...]
-
Specifies the list of PIDs of guest processes to terminate.
Close a guest Session
The VBoxManage guestcontrol
vmname closesession
command
enables you to close a guest session. Specify the guest session
either by session ID or by name.
- --session-id= ID
-
Specifies the ID of the guest session.
- --session-name= name | pattern
-
Specifies the name of the guest session. Use a pattern that contains wildcards to specify multiple sessions.
- --all
-
Closes all guest sessions.
Update the Guest Additions Software on the guest
The VBoxManage guestcontrol
vmname updatega
command
enables you to update the Guest Additions software installed in
the specified guest VM.
Alternate forms of this subcommand are
updateadditions
and
updateguestadditions
.
- --source= new-iso-path
-
Specifies the absolute path of the Guest Additions update
.ISO
file on the guest VM. - --reboot
-
Automatically reboots the guest after a successful Guest Additions update.
- --timeout= ms
-
Sets the timeout (in ms) to wait for the overall Guest Additions update to complete. By default no timeout is being used.
- --verify
-
Verifies whether the Guest Additions were updated successfully after a successful installation. A guest reboot is mandatory.
- --wait-ready
-
Waits for the current Guest Additions being ready to handle the Guest Additions update.
- --wait-start
-
Starts the
VBoxManage
update process on the guest VM and then waits for the Guest Additions update to begin before terminating theVBoxManage
process.By default, the
VBoxManage
command waits for the Guest Additions update to complete before it terminates. Use this option when a runningVBoxManage
process affects the interaction between the installer and the guest OS. - -- argument [ argument ...]
-
Specifies optional command-line arguments to pass to the Guest Additions updater. You might use the -- option to pass the appropriate updater arguments to retrofit features that are not yet installed.
Ensure that any command argument that includes spaces is enclosed by quotes.
Wait for a guest run level
The VBoxManage guestcontrol
vmname waitrunlevel
command
enables you to wait for a guest run level being reached.
- --timeout= ms
-
Sets the timeout (in ms) to wait for reaching the run level. By default no timeout is being used.
- system | userland | desktop
-
Specifies the run level to wait for.
Examples
The following VBoxManage guestcontrol run
command executes the ls -l /usr
command on the
My OL VM
Oracle Linux VM as the
user1
user.
$ VBoxManage --nologo guestcontrol "My OL VM" run --exe "/bin/ls" \ --username user1 --passwordfile pw.txt --wait-stdout -- -l /usr
The --exe option specifies the absolute path of
the command to run in the guest VM, /bin/ls
.
Use the -- option to pass any arguments that
follow it to the ls
command.
Use the --username option to specify the user
name, user1
and use the
--passwordfile option to specify the name of a
file that includes the password for the user1
user, pw.txt
.
The --wait-stdout option waits for the
ls
guest process to complete before providing
the exit code and the command output. The
--nologo option suppresses the output of the logo
information.
The following VBoxManage guestcontrol run
command executes the ipconfig
command on the
My Win VM
Windows VM as the
user1
user. Standard input, standard output,
and standard error are redirected from the VM to the host system
until the program completes.
$ VBoxManage --nologo guestcontrol "My Win VM" run \ --exe "c:\\windows\\system32\\ipconfig.exe" \ --username user1 --passwordfile pw.txt --wait-stdout
The --exe specifies the absolute path of command
to run in the guest VM,
c:\windows\system32\ipconfig.exe
. The double
backslashes shown in this example are required only on UNIX host
systems.
Use the --username option to specify the user
name, user1
and use the
--passwordfile option to specify the name of a
file that includes the password for the user1
user, pw.txt
.
The --wait-stdout option waits for the
ls
guest process to complete before providing
the exit code and the command output. The
--nologo option to suppress the output of the
logo information.
The following VBoxManage guestcontrol start
command executes the ls -l /usr
command on the
My OL VM
Oracle Linux VM until the program
completes.
$ VBoxManage --nologo guestcontrol "My Win VM" start \ --exe "c:\\windows\\system32\\ipconfig.exe" \ --username user1 --passwordfile pw.txt
The following VBoxManage guestcontrol run
command executes a /usr/bin/busybox -l /usr
command on the My OL VM
Oracle Linux VM as the
user1
user, explicitly using ls
as argument 0.
$ VBoxManage --nologo guestcontrol "My OL VM" run --exe "/usr/bin/busybox" \ --username user1 --passwordfile pw.txt --wait-stdout --arg0 ls -- -l /usr
The --exe option specifies the absolute path of
the command to run in the guest VM, /usr/bin/busybox
.
Use the -- option to pass any arguments that
follow it to the busybox
command.
Use the --username option to specify the user
name, user1
and use the
--passwordfile option to specify the name of a
file that includes the password for the user1
user, pw.txt
.
The --wait-stdout option waits for the
ls
guest process to complete before providing
the exit code and the command output. The
--nologo option suppresses the output of the logo
information.
The --arg0 option explicitly specifies the argument 0 to use for the command to execute.
Note:
If this option is not set, argument 0 will be taken from the value of --exe, or, if --exe is also not set, the first value passed after --.
Use --verbose to see the effective command line passed to the guest.
The default behavior of argument 0 is to either use the value from --exe, or, if not set, the first value passed after --.
VBoxManage guestproperty
Manage virtual machine guest properties
Synopsis
Description
The VBoxManage guestproperty
command enables
you to set or retrieve the properties of a running virtual machine
(VM). See Guest Properties. Guest properties
are arbitrary name-value string pairs that can be written to and
read from by either the guest or the host. As a result, these
properties can be used as a low-volume communication channel for
strings provided that a guest is running and has the Guest
Additions installed. In addition, the Guest Additions
automatically set and maintain values whose keywords begin with
/VirtualBox/
.
General Command Operand
- uuid | vmname
-
Specifies the Universally Unique Identifier (UUID) or name of the VM.
List All Properties for a Virtual Machine
The VBoxManage guestproperty enumerate
command
lists each guest property and value for the specified
VM. Note that the output is limited if the guest's service is
not updating the properties, for example because the VM is not
running or because the Guest Additions are not installed.
- --relative
-
Display the timestamp relative to current time.
- --no-timestamp
-
Do not display the timestamp of the last update.
- --no-flags
-
Do not display the flags.
- --old-format
-
Use the output format from VirtualBox 6.1 and earlier.
- pattern
-
Filters the list of properties based on the specified pattern, which can contain the following wildcard characters:
*
(asterisk)-
Represents any number of characters. For example, the
/VirtualBox*
pattern matches all properties that begin with/VirtualBox
. ?
(question mark)-
Represents a single arbitrary character. For example, the
fo?
pattern matches bothfoo
andfor
. |
(pipe)-
Specifies multiple alternative patterns. For example, the
s*|t*
pattern matches any property that begins withs
ort
.
Retrieve a Property Value for a Virtual Machine
The VBoxManage guestproperty get
command
retrieves the value of the specified property. If the property
cannot be found, for example because the guest is not running,
the command issues the following message:
No value set!
- property-name
-
Specifies the name of the property.
- --verbose
-
Provides the property value, timestamp, and any specified value attributes.
Set a Property Value for a Virtual Machine
The VBoxManage guestproperty set
command
enables you to set a guest property by specifying the property
and its value. If you omit the value, the property is deleted.
- property-name
-
Specifies the name of the property.
- property-value
-
Specifies the value of the property. If no value is specified, any existing value is removed.
- --flags= flags
-
Specify the additional attributes of the value. The following attributes can be specified as a comma-separated list:
-
TRANSIENT
-
Removes the value with the VM data when the VM exits.
-
TRANSRESET
-
Removes the value when the VM restarts or exits.
-
RDONLYGUEST
-
Specifies that the value can be changed only by the host and that the guest can read the value.
-
RDONLYHOST
-
Specifies that the value can be changed only by the guest and that the host can read the value.
-
READONLY
-
Specifies that the value cannot be changed.
-
Wait for a Property Value to Be Created, Deleted, or Changed
The VBoxManage guestproperty wait
command
waits for a particular value that is described by the pattern
string to change, to be deleted, or to be created.
- patterns
-
Specifies a pattern that matches the properties on which you want to wait. For information about the pattern wildcards, see the description of the --patterns option.
- --timeout msec
-
Specifies the number of microseconds to wait.
- --fail-on-timeout
-
Specifies that the command fails if the timeout is reached.
Examples
The following command lists the guest properties and their values
for the win8
VM.
$ VBoxManage guestproperty enumerate win8
The following command creates a guest property called
region
for the win8
VM. The
value of the property is set to west
.
$ VBoxManage guestproperty set win8 region west
VBoxManage hostonlyif
Manage host-only network interfaces
Synopsis
Description
The VBoxManage hostonlyif
command enables you
to change the IP configuration of a host-only network interface.
For a description of host-only networking, see
Host-Only Networking. Each host-only network
interface is identified by a name and can either use the internal
DHCP server or a manual IP configuration, both IPv4 and IPv6.
Configure a Host-Only Interface
The VBoxManage hostonlyif ipconfig
command
configures a host-only interface.
- ifname
-
Specifies the name of the network interface. The name is of the form
vboxnet
N where N is the interface instance. - --dhcp
-
Uses DHCP for the network interface.
You cannot use this option with the --ip, --ipv6, --netmask, and --netmasklengthv6 options.
- --ip= IPv4-address
-
Specifies the IPv4 IP address for the network interface.
You cannot use this option with the --dhcp, --ipv6, and --netmasklengthv6 options.
- --netmask= IPv4-netmask
-
Specifies the IPv4 netmask of the network interface. The default value is
255.255.255.0
.You can use this option only with the --ip option.
- --ipv6= IPv6-address
-
Specifies the IPv6 IP address for the network interface.
You cannot use this option with the --dhcp, --ip, and --netmask options.
- --netmasklengthv6= length
-
Specifies the length of the IPv6 network interface. The default value is
64
.You can use this option only with the --ipv6 option.
Create a Network Interface on the Host System
The VBoxManage hostonlyif create
command
creates a new host-only network interface on the host operating
system (OS). The network interface name is of the form
vboxnet
N where
N is the interface instance. You must
run this command before you can attach virtual machines (VMs) to
the host-only network.
Remove a Network Interface From the Host System
The VBoxManage hostonlyif remove
command
removes the specified host-only network interface from the host
OS.
- ifname
-
Specifies the name of the network interface. The name is of the form
vboxnet
N where N is the interface instance.
Examples
The following command creates a new host-only network interface.
$ VBoxManage hostonlyif create 0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% Interface 'vboxnet2' was successfully created
The following command configures the IPv4 address for the
vboxnet2
host-only network interface.
$ VBoxManage hostonlyif ipconfig vboxnet2 --ip 10.0.2.18
VBoxManage hostonlynet
Host Only Network management
Synopsis
Description
The hostonlynet
commands enable you to control
host-only networks.
Common options
The subcommands of hostonlynet
all operate on an
host-only network that can be identified via its name or uuid:
- --name=netname
-
The host-only network name. You see it as VBoxNetworkName in the output from
VBoxManage list hostonlynets
. - --id=netid
-
The host-only network uuid. If not specified when adding a new network, one will be generated automatically.
hostonlynet add
Adds a new host-only network.
Options configuring the host-only network:
- --netmask= mask
-
The network mask. Typically 255.255.255.0.
- --lower-ip=address, --upper-ip=address
-
The IP address range for handing out via DHCP. The upper boundrary is inclusive while the lower one is not, so the upper address will be handed out to a client, while the lower address will be used by the host itself.
- --enable, --disable
-
Whether to enable the host-only network or disable it. If not specified, the network will be created in enabled state.
VBoxManage import
Import a virtual appliance in OVF format or from a cloud service and create virtual machines
Synopsis
Description
The VBoxManage import
command imports a virtual
appliance either in OVF format or from a cloud service such as Oracle Cloud Infrastructure.
The import is performed by copying virtual disk images (by default using
the VMDK image format) and by creating virtual machines (VMs) in
Oracle VM VirtualBox. See Importing and Exporting Virtual Machines.
You must specify the path name of an OVF file or OVA archive to use as input, or a placeholder for the cloud case. For OVF appliances ensure that any disk images are in the same directory as the OVF file.
Note that any options you specify to control the imported virtual appliance or to modify the import parameters rely on the contents of the OVF file or the information from the cloud service.
Before you use the import operation to create the VM, perform a dry run to verify the correctness of your configuration. This is more useful with an OVF or OVA appliance, because with a cloud service even a dry run needs to perform most of the time consuming steps.
The import from a cloud service downloads a temporary file containing both the boot image and some metadata describing the details of the VM instance. The temporary file is deleted after successful import.
Common Options
- ovfname | ovaname
-
Specifies the name of the OVF file or OVA archive that describes the appliance. In the cloud case this is usually a fixed string such as
OCI://
. - --dry-run
-
Performs a dry run of the
VBoxManage import
command before you perform the actual import operation. A dry run operation does the following:-
Outputs a description of the appliance's contents based on the specified OVF or OVA file.
-
Shows how the appliance would be imported into Oracle VM VirtualBox. In addition, the output shows any options that you can use to change the import behavior.
The shortened form of this option is -n.
-
- --options=keepallmacs | keepnatmacs | importtovdi
-
Enables you to fine tune the import operation.
Valid arguments are as follows:
-
keepallmacs
: Specifies that the MAC addresses of every virtual network card are left unchanged. -
keepnatmacs
: Specifies that the MAC addresses of every virtual network card are left unchanged if the network type is NAT. -
importtovdi
: Specifies that all new disk images are in VDI file format.
-
- --ostype= ostype
-
Specifies the guest operating system (OS) information for the VM. Use the
VBoxManage list ostypes
command to view the OS type identifiers. - --vmname= name
-
Specifies the name of the VM to be used by Oracle VM VirtualBox.
- --basefolder= folder
-
Specifies the folder where the files of the imported VM are stored.
- --memory= MB
-
Specifies the memory size in Megabytes for the imported VM.
- --cpus= n
-
Specifies the number of CPUs for the imported VM.
- --description= text
-
Specifies the description text visible in the GUI and CLI when checking the VM details.
OVF / OVA Import Options
The following options are specific for importing a virtual appliance in OVF or OVA format. Such an appliance can contain one or more VMs, which requires specifying which VM configuration should be adjusted in case you want to change it. See Importing an Appliance in OVF Format.
- --vsys= n
-
Specifies the index selecting a specific VM within the appliance. Affects the following options.
- --unit= n
-
Specifies the index selecting a specific unit of a VM within the appliance. Affects the following options.
- --settingsfile= file
-
Specifies the name (with or without path) of the VM config file which will be created as part of the import. Usually the preferred way is overriding the VM name with --vmname and if necessary specify the folder in which to create the VM with --basefolder.
- --group= group
-
Specifies the primary group of the imported VM.
- --eula=show | accept
-
Enables you to show or accept the license conditions of a VM within the appliance,
Valid arguments are as follows:
-
show
: Shows the EULA of a VM. -
accepts
: Accepts the EULA of a VM. Any VMs in an appliance which have an EULA require accepting it, otherwise the import will fail.
-
- --ignore
-
Ignores the current unit of an imported VM, effectively removing the associated hardware.
- --scsitype=BusLogic | LsiLogic
-
Enables you to select the type of the SCSI controller for the current unit of an imported VM.
Valid arguments are as follows:
-
BusLogic
: Uses the (very old) BusLogic SCSI controller type. -
LsiLogic
: Uses the (more modern) LsiLogic SCSI controller type.
-
Cloud Import Options
The following options are specific for importing a VM instance from a cloud service provider. It always deals with a single VM. See Importing an Instance from Oracle Cloud Infrastructure.
- --cloud
-
Specifies that the import should be from the cloud.
- --cloudprofile= profile
-
Specifies the cloud profile which is used to connect to the cloud service provider. The cloud profile contains your Oracle Cloud Infrastructure account details, such as your user OCID and the fingerprint for your public key. To use a cloud profile, you must have the required permissions on Oracle Cloud Infrastructure.
- --cloudinstanceid= id
-
Specifies the ID of an existing instance in the cloud.
- --cloudbucket= bucket
-
Specifies the bucket name in which to store the object created from the instance. In Oracle Cloud Infrastructure, a bucket is a logical container for storing objects. By default the first bucket available with the cloud profile is used.
Examples
The following example performs the dry run of an OVF import operation for a sample appliance that contains a Windows 10 guest:
$ VBoxManage import Windows10.ovf --dry-run Interpreting Windows10.ovf... OK. Virtual system 0: 0: Suggested OS type: "Windows10_64" (change with "--vsys 0 --ostype <type>"; use "list ostypes" to list all) 1: Suggested VM name "win10-appliance" (change with "--vsys 0 --vmname <name>") 2: Suggested VM group "/" (change with "--vsys 0 --group <group>") 3: Suggested VM settings file name "/home/user1/VirtualBox VMs/win10-appliance/win10-appliance.vbox" (change with "--vsys 0 --settingsfile <filename>") 4: Suggested VM base folder "/home/user1/VirtualBox VMs" (change with "--vsys 0 --basefolder <path>") 5: End-user license agreement (display with "--vsys 0 --eula show"; accept with "--vsys 0 --eula accept") 6: Number of CPUs: 1 (change with "--vsys 0 --cpus <n>") 7: Guest memory: 2048 MB (change with "--vsys 0 --memory <MB>") 8: Sound card (appliance expects "ensoniq1371", can change on import) (disable with "--vsys 0 --unit 8 --ignore") 9: USB controller (disable with "--vsys 0 --unit 9 --ignore") 10: Network adapter: orig bridged, config 2, extra type=bridged 11: Floppy (disable with "--vsys 0 --unit 11 --ignore") 12: SCSI controller, type BusLogic (change with "--vsys 0 --unit 12 --scsitype {BusLogic|LsiLogic}"; disable with "--vsys 0 --unit 12 --ignore") 13: IDE controller, type PIIX4 (disable with "--vsys 0 --unit 13 --ignore") 14: Hard disk image: source image=Windows10.vmdk, target path=/home/user1/disks/Windows10.vmdk, controller=12;channel=0 (change target path with "--vsys 0 --unit 14 --disk <path>"; change controller with "--vsys 0 --unit 14 --controller <index>"; change controller port with "--vsys 0 --unit 14 --port <n>"; disable with "--vsys 0 --unit 14 --ignore")
The dry run output lists and numbers the individual configuration
items that are described in the Windows10.ovf
file. Some of the items include information about how to disable
or change the configuration of the item.
You can disable many of the items by using the --vsys
X --unit Y
--ignore options. X is the
number of the virtual system. The value is 0
unless the appliance includes several virtual system descriptions.
Y is the configuration item number.
Item 1 in the example command output specifies the name of the target machine. Items 12 and 13 specify the IDE and SCSI hard disk controllers, respectively.
Item 14 indicates the hard disk image and the --disk option specifies the target path where the image will be stored, the --controller option specifies which controller the disk will be attached to, and the --port option specifies which port on the controller the disk will be attached to. The default values are specified in the OVF file.
You can combine several items for the same virtual system by specifying the same value for the --vsys option. For example use the following command to import a machine as described in the OVF, exclude the sound card and USB controller and specify that the disk image is stored with a different name.
$ VBoxManage import Windows10.ovf --vsys 0 --unit 8 --ignore \ --unit 9 --ignore --unit 14 --disk Windows10_disk0.vmdk
The following example illustrates how to import a VM from Oracle Cloud Infrastructure. To find the Oracle Cloud Infrastructure VM instances and its ID you can list all available instances with:
$ VBoxManage cloud --provider=OCI --profile=cloud-profile-name list instances
Once you know the ID the following command imports the instance from Oracle Cloud Infrastructure:
$ VBoxManage import OCI:// --cloud --vmname OCI_FreeBSD_VM --memory 4000 \ --cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user" \ --cloudinstanceid ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket
VBoxManage list
View system information and VM configuration details
Synopsis
Description
The VBoxManage list
subcommands enable you to
obtain information about the Oracle VM VirtualBox software, the VMs
and associated services that you create.
Common Options
- --long
-
Shows detailed information about each information entry if available. The short form of this option is -l.
- --sorted
-
Sorts the list of information entries alphabetically. The short form of this option is -s.
List the Bridged Network Interfaces on the Host System
The VBoxManage list bridgedifs
command lists
the bridged network interfaces that are currently available on
the host system. The output shows detailed configuration
information about each interface. See Virtual Networking.
List the Cloud Network Interfaces
The VBoxManage list cloudnets
command
lists the cloud network interfaces that have been configured. A cloud
network interface provides connectivity between local VMs and a
cloud network.
List the Cloud Profiles
The VBoxManage list cloudprofiles
command
lists the cloud profiles that have been configured. A cloud
profile contains settings for a cloud service account.
List the Cloud Providers
The VBoxManage list cloudproviders
command
lists the cloud providers that are supported by Oracle VM VirtualBox.
Oracle Cloud Infrastructure is an example of a cloud provider.
List the known CPU Profiles
The VBoxManage list cpu-profiles
command
lists the CPU profiles that are known by Oracle VM VirtualBox.
List the DHCP Servers on the Host System
The VBoxManage list dhcpservers
command lists
the DHCP servers that are currently available on the host
system. The output shows detailed configuration information
about each DHCP server. See Virtual Networking.
List the DVD Virtual Disk Images
The VBoxManage list dvds
command shows
information about the DVD virtual disk images that are currently
in use by the Oracle VM VirtualBox software. For each image, the
output shows all the settings, the UUIDs associated with the
image by Oracle VM VirtualBox, and all files associated with the
image.
This command performs the same function as the Virtual Media Manager. See The Virtual Media Manager.
List the Installed Oracle VM VirtualBox Extension Packs
The VBoxManage list extpacks
command shows
all Oracle VM VirtualBox extension packs that are currently installed.
See Installing Oracle VM VirtualBox and Extension Packs and
VBoxManage extpack.
List the Floppy Disk Virtual Disk Images
The VBoxManage list floppies
command shows
information about the floppy disk images that are currently in
use by the Oracle VM VirtualBox software. For each image, the output
shows all the settings, the UUIDs associated with the image by
Oracle VM VirtualBox, and all files associated with the image.
This command performs the same function as the Virtual Media Manager. See The Virtual Media Manager.
List the Virtual Disk Backends
The VBoxManage list hddbackends
command lists
all known virtual disk backends of the Oracle VM VirtualBox software.
For each such format, such as VDI, VMDK, or RAW, this command
lists the backend's capabilities and configuration.
List the Hard Disk Virtual Disk Images
The VBoxManage list hdds
command shows
information about the hard disk virtual disk images that are
currently in use by the Oracle VM VirtualBox software. For each image,
the output shows all the settings, the UUIDs associated with the
image by Oracle VM VirtualBox, and all files associated with the
image.
This command performs the same function as the Virtual Media Manager. See The Virtual Media Manager.
List the CPUID Information for the Host System CPUs
The VBoxManage list hostcpuids
command lists
CPUID information for each CPU on the host system. Use this
information to perform a more fine grained analyis of the host
system's virtualization capabilities.
List the Storage Drives on the Host System
The VBoxManage list hostdrives
command lists
the disk drives on the host system potentially useful for creating
a VMDK raw disk image. Each entry includes the name used to
reference them from within Oracle VM VirtualBox.
List the DVD Drives on the Host System
The VBoxManage list hostdvds
command lists
the DVD drives on the host system. Each DVD entry includes
the name used to access them from within Oracle VM VirtualBox.
List the Floppy Disk Drives on the Host System
The VBoxManage list hostfloppies
command
lists the floppy disk drives on the host system. Each floppy
disk entry includes the name used to access them from within
Oracle VM VirtualBox.
List Information About the Host System
The VBoxManage list hostinfo
command shows
information about the host system. The output includes
information about the CPUs, memory, and the OS version.
List the Host-Only Network Interfaces on the Host System
The VBoxManage list hostonlyifs
command lists
the host-only network interfaces that are currently available on
the host system. The output shows detailed configuration
information about each interface. See Virtual Networking.
List Host-Only Networks
The VBoxManage list hostonlynets
command
lists the host-only networks that have been configured. A
host-only network provides connectivity between the host and
local VMs. See Virtual Networking.
List Internal Networks
The VBoxManage list intnets
command shows
information about the internal networks. See
Virtual Networking.
List the NAT Network Interfaces on the Host System
The VBoxManage list natnets
command lists the
NAT network interfaces that are currently available on the host
system. See Virtual Networking.
List the Guest Operating Systems
The VBoxManage list ostypes
command lists all
guest operating systems (OSes) that are known to Oracle VM VirtualBox.
Each OS entry includes an identifier, a description, a family
identifier, a family description, and whether the OS has 64-bit
support.
You can use these identifiers with the VBoxManage
modifyvm
command.
List the Running Virtual Machines
The VBoxManage list runningvms
command lists
all virtual machines (VMs) that are currently running. By
default this displays a compact list that shows the name and
UUID of each VM.
List the Available Screen Shot Formats
The VBoxManage list screenshotformats
command
shows the list of available screen shot formats.
List System Properties
The VBoxManage list systemproperties
command
shows a large collection of global Oracle VM VirtualBox settings and
limits, such as minimum and maximum guest RAM, virtual hard disk
size, folder settings, and the current authentication library in
use.
List the Registered Global USB Filters
The VBoxManage list usbfilters
command lists
all global USB filters registered with Oracle VM VirtualBox and
displays the filter parameters. Global USB filters are for
devices which are accessible to all virtual machines.
List the USB Devices on the Host System
The VBoxManage list usbhost
command shows
information about the USB devices that are attached to the host
system. The output includes information that you can use to
construct USB filters and indicates whether the device is
currently in use by the host system.
List Virtual Machines
The VBoxManage list vms
command lists all
virtual machines (VMs) that are currently registered with
Oracle VM VirtualBox. By default this command displays a compact list
that shows the name and UUID of each VM.
List the Webcams Attached to a Running Virtual Machine
The VBoxManage list webcams
command shows the
list of webcams that are attached to the running VM.
The output is a list of absolute paths or aliases that are used
to attach the webcams to the VM by using the VBoxManage
webcam attach
command.
VBoxManage mediumio
Medium content access
Synopsis
Description
Common options
The subcommands of mediumio
all operate on a medium which need to be specified, optionally
with an encryption password. The following common options can be placed before or after the sub-command:
- --disk=uuid|filename
-
Either the UUID or filename of a harddisk image, e.g. VDI, VMDK, VHD, ++.
- --dvd=uuid|filename
-
Either the UUID or filename of a DVD image, e.g. ISO, DMG, CUE.
- --floppy=uuid|filename
-
Either the UUID or filename of a floppy image, e.g. IMG.
- --password-file=-|filename
-
The name of a file containing the medium encryption password. If - is specified, the password will be read from stdin.
mediumio formatfat
Formats a floppy medium with the FAT file system. This will erase the content of the medium.
- --quick
-
Quickformat the medium.
mediumio cat
Dumps the medium content to stdout or the specified file.
- --hex
-
Dump as hex bytes.
- --offset
-
The byte offset in the medium to start.
- --size
-
The number of bytes to dump.
- --output
-
The output filename. As usual - is take to mean stdout.
mediumio stream
Converts the medium to a streamable format and dumps it to the given output.
- --format
-
The format of the destination image.
- --variant
-
The medium variant for the destination.
- --output
-
The output filename. As usual - is take to mean stdout.
VBoxManage mediumproperty
Manage medium properties
Synopsis
Description
The VBoxManage mediumproperty
command enables
you to set, retrieve, or delete a medium property.
Set a Medium Property
The VBoxManage mediumproperty set
command
enables you to set a medium property.
-
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.
- property-name
-
Specifies the name of the property.
- property-value
-
Specifies the value of the specified property.
Retrieve a Medium Property Value
The VBoxManage mediumproperty get
command
enables you to retrieve the value of a medium property.
-
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.
- property-name
-
Specifies the name of the property.
Delete a Medium Property
The VBoxManage mediumproperty delete
command
enables you to delete a medium property.
-
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.
- property-name
-
Specifies the name of the property.
VBoxManage metrics
Monitor system resource usage
Synopsis
Description
The VBoxManage metrics
command enables you to
monitor system resource usage for the host system and for virtual
machines (VMs). For example, you can monitor particular metrics,
such as the percentage of time CPUs spend executing in user mode
(CPU/Load/User
) over a specified sampling
period.
While it runs, the VBoxSVC
process collects and
saves the specified metric data internally. The
VBoxSVC
process runs until shortly after you
close all VMs and frontends. Use the VBoxManage metrics
query
command to retrieve data at any time.
By default, metrics are not collected unless you run the
VBoxManage metrics setup
command to specify a
sampling interval in seconds and the number of metrics to save.
Note that you can enable metric collection only for started VMs. Collected data and collection settings for a VM are discarded when the VM shuts down.
Metrics
The host and VMs have different sets of associated metrics,
which you can view by running the VBoxManage metrics
list
command.
Each metric is represented as a string that is composed of a category and a metric. Optionally, the metric string can include any of the following: a submetric, a sub-submetric, and an aggregate. The metric string has the following format:
category/metric[/submetric[/sub-submetric]][:aggregate]
-
category is the resource type, such as
CPU
,RAM
,FS
,Net
. -
metric is a measurement type that is associated with the resource category. For example, the
Load
andMHz
metrics are associated with theCPU
resource category. -
submetric is an optional measurement type that is associated with the metric. For example, the
User
,Kernel
, andIdle
submetrics are associated with theLoad
metric. -
sub-submetric is an optional measurement type that is associated with the submetric. For example, the
Rx
andTx
sub-submetrics are associated with theRate
submetric of theNet
resource category. The associated metric is the network interface. -
aggregate is an optional function to provide minimum, maximum, and average measurements for a resource category. For example, the
RAM/Usage/Free:min
metric represents the minimum amount of available memory found in all saved data on the host system.
By default, the VBoxManage metrics
commands
operate on the host system and all VMs, and report on all
metrics. You can optionally limit these commands to operate on
the host system or on a particular VM, and report on a list of
one or more metrics.
Common Options
*
|host
| vmname-
Specifies the component on which to operate. By default, this command operates on the host system and all running VMs.
If you specify
host
, theVBoxManage metrics
command operates on the host system only. If you specify an asterisk (*
), the command operates on all VMs. If you specify the name of a VM, theVBoxManage metrics
command operates on that VM. - metric-list
-
Specifies a comma-separated list of one or more metrics.
The form of the metric must include the category and metric part of the metric string separated by a slash.
Note that the
VBoxManage metrics enable
andVBoxManage metrics disable
commands require that you specify metrics as parameters. The metrics must include only the resource category and metric part, such asCPU/Load
andRAM/Usage
.
Collect Data Metrics
The VBoxManage metrics collect
command
collects and outputs data periodically until you stop the
process by pressing Ctrl+C.
- --detach
-
Disables the collection of metric data, so no data is output. Using this option is the same as running the
VBoxManage metrics setup
command. - --list
-
Shows which metrics match the specified filter.
- --period= seconds
-
Specifies the number of seconds to wait between collecting metric data samples. The default value is 1.
- --samples= count
-
Specifies the number of metric data samples to save. To view the saved data, use the
VBoxManage metrics query
command. The default value is 1.
Disable Metric Data Collection
The VBoxManage metrics disable
command
suspends data collection. This action does not affect the data
collection properties or the collected data. Note that
specifying a submetric in the metric list does not disable its
underlying metrics.
Note that the VBoxManage metrics disable
command requires that you specify metrics as parameters. The
metrics must include only the resource category and metric part,
such as CPU/Load
and
RAM/Usage
.
- --list
-
Shows whether the command succeeded as expected.
Enable Metric Data Collection
The VBoxManage metrics enable
command resumes
data collection after it has been suspended by using the
VBoxManage metrics disable
command. Note that
specifying a submetric in the metric list does not enable its
underlying metrics.
Unlike the VBoxManage metrics setup
command,
the VBoxManage metrics enable
command does
not discard previously collected samples for the specified set
of objects and metrics.
Note that the VBoxManage metrics enable
command requires that you specify metrics as parameters. The
metrics must include only the resource category and metric part,
such as CPU/Load
and
RAM/Usage
.
- --list
-
Shows whether the command succeeded as expected.
List Metric Values
The VBoxManage metrics list
command shows the
metrics that are currently available. Note that VM-specific
metrics are shown only when that VM is running.
List Saved Metric Data
The VBoxManage metrics query
command
retrieves and shows the saved metric data.
Note that the VBoxManage metrics query
command does not remove or flush saved data but older samples
are replaced by newer samples over time.
Configure Metric-Gathering Properties
The VBoxManage metrics setup
command
configures metric-gathering properties.
Note that this command discards any previously collected samples
for the specified set of objects and metrics. To enable or
disable metrics collection without discarding the data, use the
VBoxManage metrics enable
command or the
VBoxManage metrics disable
command,
respectively.
- --list
-
Shows which metrics have been modified as a result of the command execution.
- --period= seconds
-
Specifies the number of seconds to wait between collecting metric data samples. The default value is 1.
- --samples= count
-
Specifies the number of metric data samples to save. To view the saved data, use the
VBoxManage metrics query
command. The default value is 1.
Examples
The following example command enables the collection of host processor and memory usage metrics every second. The --samples option saves the five latest samples.
$ VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage
The following command lists the metrics that are available to the host system and VMs:
$ VBoxManage metrics list
Note that the host system and VMs have different sets of metrics.
The following example shows how to query metric data about the CPU
time spent in user and kernel modes for the
test
VM:
$ VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel
VBoxManage modifymedium
Change the characteristics of an existing disk image
Synopsis
Description
The VBoxManage modifymedium
command enables you
to change the characteristics of an existing disk image.
Note:
For compatibility with earlier versions of Oracle VM VirtualBox, you
can use the modifyvdi
and
modifyhd
commands.
- disk | dvd | floppy
-
Specifies the media type of the image.
- filename
-
Specifies the Universally Unique Identifier (UUID) or path name of the disk image on the host file system. You can specify the UUID only if the medium is registered. Use the
VBoxManage list hdds
command to list the registered images. You can specfy an absolute or relative path to the medium. - --autoreset=on | off
-
Specifies whether to automatically reset an immutable hard disk on every virtual machine (VM) startup. This option is only for immutable hard disks and the default value is
on
. See Special Image Write Modes. - --compact
-
Compresses disk images by removing blocks that contain only zeroes. This option shrinks a dynamically allocated image and reduces the physical size of the image without affecting the logical size of the virtual disk.
You can use this option for base images and for differencing images that are created as part of a snapshot.
Note:
Before you compress the image, you must use a suitable software tool to zero out free space in the guest system. For example:
-
Windows guests. Run the
sdelete -z
command. -
Linux guests. Use the
zerofree
utility, which supportsext2
andext3
file systems. -
Mac OS X guests. Use the
diskutil secureErase freespace 0 /
command.
Note that you can only use this option to compress VDI images. To compress non-VID images, you can zero out free blocks and then clone the disk to any other dynamically allocated format.
-
- --description= description
-
Specifies a text description of the medium.
- --move= pathname
-
Specifies a relative or absolute path to a medium on the host system. Use this option to relocate a medium to a different location on the host system.
- --property= name = value
-
Specifies a property name and value for the medium.
- --resize= size
-
Specifes the new capacity of an existing image in MB. You can use this option only to expand the capacity of an image. You can cannot shrink the capacity of an image.
Note that you can resize only dynamically allocated disk images that use the VDI and VHD formats. This option adjusts the logical size of a virtual disk and has only a minor affect on the physical size.
For example, if your dynamically allocated 10 GB disk is full, you can use the --resize 15360 option to increase the capacity of the existing disk to 15 GB (15,360 MB). This operation enables you to avoid having to create a new image and copy all data from within a VM.
Note that using this option only changes the capacity of the drive. So, you might need to subsequently use a partition management tool in the guest to adjust the main partition to fill the drive.
- --resizebyte= size
-
Specifes the new capacity of an existing image in bytes. This option is similar to the --resize option, but you specify the size in bytes instead of megabytes.
- --setlocation= pathname
-
Specifies the new location of the medium on the host system after the medium has been moved. The path name can be relative to the current directory or be absolute to the root.
Note that the
VBoxManage modifymedium
command does not perform any sanity checks on the path name you specify. Ensure that the path name is valid. - --type
-
Specifies the new mode type of an existing image. Valid values are
normal
,immutable
,writethrough
,multi-attach
,shareable
, andreadonly
. For descriptions of these mode types, see Special Image Write Modes.
Examples
The following command modifies the description for the disk image
file called disk01.vdi
.
$ VBoxManage modifymedium disk disk01.vdi --description "Oracle Linux 7 image"
The following command modifies the write mode for the disk image
file called disk01.vdi
.
$ VBoxManage modifymedium disk disk01.vdi --type writethrough
VBoxManage modifynvram
List and modify the NVRAM content of a virtual machine
Synopsis
Description
The "modifynvram" commands are for experts who want to inspect and modify the UEFI variable store of a virtual machine. Any mistakes done here can bring the virtual machine in a non working state.
Common options
The subcommands of modifynvram
all operate on a running virtual
machine:
- uuid | vmname
-
Either the UUID or the name (case sensitive) of a VM.
modifynvram inituefivarstore
Iniitalizes the UEFI variable store to a default state. Any previous existing variable store is deleted. Use with extreme caution!
modifynvram enrollmssignatures
Enrolls the default Microsoft KEK and DB signatures required for UEFI secure boot.
modifynvram enrollorclpk
Enrolls the default platform key provided by Oracle required for UEFI secure boot.
modifynvram enrollpk
Enrolls a custom platform key provided by the user required for UEFI secure boot. The following commands use openssl to generate a new platform key:
$ openssl req -new -x509 -newkey rsa:2048 -keyout PK.key -out PK.crt
$ openssl x509 -in PK.crt -out PK.cer -outform DER
- --platform-key= filename
-
The platform key provided as a DER encoded X.509 signature.
- --owner-uuid= uuid
-
The UUID identifying the owner of the platform key.
modifynvram listvars
Lists all UEFI variables in the virtual machines's store along with their owner UUID.
modifynvram queryvar
Queries the content of a given UEFI variable identified by its name.
- --name= name
-
UEFI variable name to query.
- --filename= filename
-
Where to store the content of the variable upon success. This is optional, if omitted the content will be dumped to the terminal as a hex dump.
VBoxManage modifyvm
Change settings for a virtual machine that is stopped
Synopsis
Description
The VBoxManage modifyvm
command enables you to
change the properties of a registered virtual machine (VM) that is
not running.
Most of these properties correspond to the VM settings that are
shown in each VM's Settings
dialog in the VirtualBox Manager. See
Configuring Virtual Machines. However, some settings can only
be viewed and managed with the VBoxManage
command.
You can use the VBoxManage modifyvm
command to
change VM settings only when the VM is powered off. The VM cannot
be running or in saved state when you use this command.
You can use the VBoxManage controlvm
command to
dynamically change some VM machine settings while the VM is
running. See VBoxManage controlvm.
General Settings
The following options enable you to modify general information about your VM.
The VBoxManage modifyvm
command supports the
following options:
- --name= vmname
-
Changes the name of the VM and its related internal VM files. See VBoxManage createvm.
- --groups= group
-
Changes the group membership of a VM. Group names always begin with a slash character (
/
) and can be nested. By default, VMs are members of the/
group. A VM can be member of multiple groups, but its primary group determines the directory structure where the internal VM files are placed by default. - --description= desc
-
Changes the optional VM description. Use a description to record details about the VM in a meaningful way. The GUI interprets HTML markup while the
VBoxManage modifyvm
command enables you include arbitrary strings that can contain multiple lines. - --os-type= OS-type
-
Specifies the guest operating system (OS) information for the VM. Use the
VBoxManage list ostypes
command to view the OS type identifiers. - --icon-file= filename
-
Specifies the path to the VM icon file in PNG format on the host system. The icon is shown in the VM manager UI and when running the VM with UI.
- --memory= size
-
Specifies the amount of host system RAM to allocate to the VM. The size is in MB. See Creating Your First Virtual Machine.
- --page-fusion=on | off
-
Enables or disables the Page Fusion feature, which is disabled by default. Use the Page Fusion feature to minimize the memory duplication between VMs that have similar configurations and that run on the same host system. See Page Fusion.
- --vram= size
-
Specifies the amount of RAM to allocate to the virtual graphics card. See Display Settings.
- --acpi=on | off
-
Determines whether the VM has ACPI support. See Motherboard Tab.
- --ioapic=on | off
-
Determines whether the VM has I/O APIC support. See Motherboard Tab.
- --hardware-uuid= uuid
-
Specifies the Universally Unique Identifier (UUID) to present to the guest VM in memory tables (DMI/SMBIOS), hardware, and VM properties. By default this hardware UUID is the same as the VM UUID. Cloning a VM and the teleporting feature automatically preserve the hardware UUID value. Likewise for Virtual Appliance export and import, but only if both operations are done by Oracle VM VirtualBox.
- --cpus= CPU-count
-
Specifies the number of virtual CPUs to assign to the VM. See Processor Tab.
If CPU hot-plugging is enabled, this option specifies the maximum number of virtual CPUs that can be plugged into the VMs.
- --cpu-hotplug=on | off
-
Enables or disables CPU hot-plugging. When enabled, you can dynamically add virtual CPUs to a VM or remove virtual CPUs from a VM. See CPU Hot-Plugging.
- --plug-cpu= CPU-ID
-
Adds a virtual CPU to the VM. CPU-ID is the index of the virtual CPU to add. A valid index value is a number from
0
to the maximum number of CPUs that you configured by using the --cpus option.Only use this option if CPU hot-plugging is enabled.
- --unplug-cpu= CPU-ID
-
Removes a virtual CPU from the VM. CPU-ID is the index of the virtual CPU to remove. A valid index value is a number from
1
to the maximum number of CPUs that you configured by using the --cpus option.Only use this option if CPU hot-plugging is enabled.
Note that you cannot remove CPU 0.
- --cpuexectioncap= percentage
-
Specifies how much CPU time a virtual CPU can use. A valid value is from
1
to100
. A value of 50 indicates that a single virtual CPU can use up to 50% of a single host CPU.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.
- --pae=on | off
-
Enables or disables physical address extension (PAE). See Processor Tab.
- --long-mode=on | off
-
Enables or disables long mode. See Processor Tab.
- --ibpb-on-vm-exit=on | off
-
Enables use of Indirect Branch Prediction Barrier (IBPB) on every VM exit.
- --ibpb-on-vm-entry=on | off
-
Enables use of Indirect Branch Prediction Barrier (IBPB) on every VM entry.
- --spec-ctrl=on | off
-
Enables or disables the exposure of speculation control interfaces to the guest VM. These interfaces must be available on the host system.
Depending on the host CPU and the workload, enabling speculation control might significantly reduce performance.
- --l1d-flush-on-sched=on | off
-
Enables or disables level 1 data cache flushing when a thread is scheduled to execute guest code. See CVE-2018-3646.
- --l1d-flush-on-vm-entry=on | off
-
Enables or disables level 1 data cache flushing on every VM entry. See CVE-2018-3646.
- --mds-clear-on-sched=on | off
-
Enables CPU buffer clearing when a thread is scheduled to execute guest code. See CVE-2018-12126, CVE-2018-12127, CVE-2018-12130, CVE-2019-11091.
- --mds-clear-on-vm-entry=on | off
-
Enables CPU buffer clearing on every VM entry. See CVE-2018-12126, CVE-2018-12127, CVE-2018-12130, CVE-2019-11091.
- --cpu-profile=host | Intel 8086 | Intel 80286 | Intel 80386
-
Specifies the profile to use for guest CPU emulation. Specify a value that is based on the host system CPU (
host
) or one of the following older Intel micro-architectures:8086
,80286
, or80386
. - --hpet=on | off
-
Enables or disables a High Precision Event Timer (HPET) that can replace a legacy system timer. This feature is disabled by default. Note HPET is supported on Windows versions starting with Vista.
- --hwvirtex=on | off
-
Enables or disables the use of hardware virtualization extensions in the processor of the host system. Such extensions are Intel VT-x or AMD-V. See Hardware Virtualization.
- --triple-fault-reset=on | off
-
Enables or disables the resetting of the guest VM instead of triggering a Guru Meditation. Some guest VMs raise a triple fault to reset the CPU, so sometimes resetting the guest VM is the best outcome. This option only applies to guests that do not use symmetric multiprocessing (SMP).
- --apic=on | off
-
Enables or disables APIC. With APIC, OSes can use more than 16 interrupt requests (IRQs) to avoid IRQ sharing and to improve reliability. APIC is enabled by default. See Motherboard Tab.
- --x2apic=on | off
-
Enables or disables the CPU x2APIC feature. CPU x2APIC enables an OS to run more efficiently on high core count configurations and to optimize interrupt distribution in virtualized environments. This feature is enabled by default.
Disable this feature when the OS that runs on a host system or a guest VM is incompatible with CPU x2APIC.
- --paravirt-provider=none | default | legacy | minimal | hyperv | kvm
-
Specifies one of the following paravirtualization interfaces to provide to the guest OS:
-
none
does not expose any paravirtualization interface. -
default
selects the appropriate interface based on the guest OS type when starting the VM. This is the default value used when creating new VMs. -
legacy
selects a paravirtual interface for VMs that were created by older Oracle VM VirtualBox versions. -
minimal
is required for Mac OS X guest VMs. -
kvm
is recommended for Linux guest VMs. See Paravirtualization Providers. -
hyperv
is recommended for Windows guest VMs. See Paravirtualization Providers.
-
- --paravirt-debug= property = value
-
Specifies debugging properties that are specific to the paravirtualization provider configured for the specified VM. See Paravirtualized Debugging.
- --nested-paging=on | off
-
Enables or disables the nested paging feature in the processor of the host system. This option is available only when hardware virtualization is enabled. See Hardware Virtualization and CVE-2018-3646.
- --large-pages=on | off
-
Enables or disables the hypervisor's use of large pages, which can improve performance by up to 5%. The use of large pages reduces TLB use and overhead. This option is available only when both hardware virtualization and nested paging are enabled.
- --vtx-vpid=on | off
-
Enables or disables the use of the tagged TLB (VPID) feature in the processor of your host system. See Hardware Virtualization. This option is available only when hardware virtualization is enabled on Intel VT-x.
- --vtx-ux=on | off
-
Enables or disables the use of unrestricted guest mode for executing the guest VM. This option is available only when hardware virtualization is enabled on Intel VT-x.
- --nested-hw-virt=on | off
-
Enables or disables nested virtualization. Enabling makes hardware virtualization features available to the VM. See Nested Virtualization.
- --virt-vmsave-vmload=on | off
-
If hardware virtualization is enabled and the host has an AMD CPU, this setting enables or disables the use of the virtualized vmsave/vmload host feature while executing the VM. It is enabled by default. It is recommended to leave it enabled as it has a drastic impact on performance while executing nested VMs when using the nested hardware virtualization feature. Nested Virtualization.
- --accelerate-3d=on | off
-
Enables or disables hardware 3D acceleration for the graphics adapter variants which support it. This option has an effect only when the Guest Additions are installed. See Hardware 3D Acceleration (OpenGL and Direct3D 8/9).
- --accelerate-2d-video=on | off
-
Enables or disables 2D video acceleration for the graphics adapter variants which support it. This option has an effect only when the Guest Additions are installed. See Hardware 2D Video Acceleration for Windows Guests.
- --chipset=piix3 | ich9
-
Specify the Intel chipset for Oracle VM VirtualBox to emulate. The default value is the Intel PIIX3 chipset (
piix3
).Change this value only if you need to relax some of the chipset constraints. See Motherboard Tab.
- --iommu=none | automatic | amd | intel
-
Specifies the IOMMU type for Oracle VM VirtualBox to emulate. Both Intel and AMD IOMMU emulation currently require the use of the Intel ICH9 chipset (see --chipset option).
Valid values are as follows:
-
none
– No IOMMU is present and is the default value. -
automatic
– An IOMMU is present but its type is automatically chosen to match the host CPU vendor when the VM is powered on. -
amd
– An AMD IOMMU is present. -
intel
– An Intel IOMMU is present.
-
- --tpm-type=none | 1.2 | 2.0 | host | swtpm
-
Specifies the TPM type for Oracle VM VirtualBox to emulate.
Valid values are as follows:
-
none
– No TPM is present and is the default value. -
1.2
– A TPM conforming to the TCG specification version 1.2 is present. -
2.0
– A TPM conforming to the TCG specification version 2.0 is present. -
host
– The host TPM is passed through to the guest. May not be available on all supported host platforms. -
swtpm
– The VM connects to an external TPM emulation compliant to swtpm. Requires to set the TPM location to connect to (see --tpm-location option).
-
- --bios-logo-fade-in=on | off
-
Specifies whether the BIOS logo fades in on VM startup. By default, an Oracle VM VirtualBox logo is shown.
- --bios-logo-fade-out=on | off
-
Specifies whether the BIOS logo fades out on VM startup.
- --bios-logo-display-time= msec
-
Specifies the amount of time in milliseconds that the BIOS logo is visible.
- --bios-logo-image-path= pathname
-
Replaces the existing BIOS logo with a different image. The replacement image must be an uncompressed 16, 256 or 16M color bitmap file (BMP) that does not contain color space information (Windows 3.0 format). Also ensure that the image is no larger than 640 X 480 pixels.
- --bios-boot-menu=disabled | menuonly | messageandmenu
-
Specifies whether the BIOS permits you to select a temporary boot device. Valid values are:
-
disabled
outputs the alternate boot device message and permits you to select a temporary boot device by pressing F12. -
menuonly
suppresses the alternate boot device message, but permits you to select a temporary boot device by pressing F12. -
messageandmenu
suppresses the alternate boot device message and prevents you from selecting a temporary boot device by pressing F12.
-
- --bios-apic=x2apic | apic | disabled
-
Specifies the APIC level of the firmware. Valid values are:
x2apic
,apic
, anddisabled
. When the value isdisabled
, neither theapic
nor thex2apic
version of the firmware is used.Note that if you specify the
x2apic
value and x2APIC is unsupported by the virtual CPU, the APIC level downgrades toapic
, if supported. Otherwise, the APIC level downgrades todisabled
. Similarly, if you specify theapic
value and APIC is unsupported by the virtual CPU, the APIC level downgrades todisabled
. - --bios-system-time-offset= msec
-
Specifies the time offset in milliseconds of the guest VM relative to the time on the host system. If the offset value is positive, the guest VM time runs ahead of the time on the host system.
- --bios-pxe-debug=on | off
-
Enables or disables additional debugging output when using the Intel PXE boot ROM. The debug output is written to the release log file. See Collecting Debugging Information.
- --system-uuid-le=on | off
-
Enables or disables representing the system UUID in little endian form. The default value is
on
for new VMs. For old VMs the setting isoff
to keep the content of the DMI/SMBIOS table unchanged, which can be important for Windows license activation. - --boot N =none | floppy | dvd | disk | net
-
Enables you to specify the boot device order for the VM by assigning one of the device types to each of the four boot device slots that are represented by N in the option name.
A value of 1 for N represents the first boot device slot, and so on.
The device types are
floppy
for floppy disks,dvd
for DVDs or CDs,disk
for hard disks, andnet
for a network device. A value ofnone
indicates that no boot device is associated with the specified slot. - --rtc-use-utc=on | off
-
Specifies whether the real-time clock (RTC) uses coordinated universal time (UTC). See Motherboard Tab.
- --graphicscontroller=none | vboxvga | vmsvga | vboxsvga
-
Specifies the graphics controller type to use. See Screen Tab.
- --snapshot-folder=default | pathname
-
Specifies the name of the VM's snapshot storage folder. If you specify
default
, the folder name isSnapshots/
in the machine folder. - --firmware=bios | efi | efi32 | efi64
-
Specifies the firmware used to boot the VM. Valid values are:
bios
,efi
,efi32
, orefi64
. Use EFI values with care.By default, BIOS firmware is used.
- --guest-memory-balloon= size
-
Specifies the size of the guest memory balloon. The guest memory balloon is the memory allocated by the Guest Additions from the guest OS and returned to the hypervisor for use by other VMs. Specify size in megabytes. The default value is
0
megabytes. See Memory Ballooning. - --default-frontend=default | name
-
Specifies the default frontend to use when starting the specified VM. If you specify
default
, the VM is shown in a window on the user's desktop. See VBoxManage startvm. - --vm-process-priority=default | flat | low | normal | high
-
Specifies the priority scheme of the VM process to use when starting the specified VM and while the VM runs.
The following 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.
-
Networking Settings
The following options enable you to modify networking on your VM. With all these options, N is an integer greater than zero that represents the particular virtual network adapter to configure.
- --nic N =none | null | nat | natnetwork | bridged | intnet | hostonly | generic
-
Configures the network type used by each virtual network card in the VM.
The following valid values correspond to the modes described in Introduction to Networking Modes:
-
none
– No networking present -
null
– Not connected to the host system -
nat
– Use network address translation (NAT) -
natnetwork
– Use a NAT network -
bridged
– Use bridged networking -
intnet
– Use internal networking -
hostonly
– Use host-only networking -
generic
– Access rarely used sub-modes
-
- --nic-type N =Am79C970A | Am79C973 | 82540EM | 82543GC | 82545EM | virtio
-
Identifies the type of networking hardware that Oracle VM VirtualBox presents to the guest VM for the specified virtual network card. See Virtual Networking Hardware.
Valid values are as follows:
-
Am79C970A
represents the AMD PCNet PCI II. -
Am79C973
represents the AMD PCNet FAST III, which is the default value. -
82540EM
represents the Intel PRO/1000 MT Desktop. -
82543GC
represents the Intel PRO/1000 T Server. -
82545EM
represents the Intel PRO/1000 MT Server. -
virtio
represents a paravirtualized network adapter.
-
- --cable-connected N =on | off
-
Temporarily disconnects a virtual network interface, as if you pull a network cable from a physical network card. You might use this option to reset certain software components in the VM.
- --nic-trace N =on | off
-
Enables or disables network tracing for the specified virtual network card.
- --nic-trace-file N = filename
-
Specifies the absolute path of the file in which to write trace log information. Use this option if network tracing is enabled.
- --nic-property N = name = value
-
Enables you to set property values and pass them to rarely used network backends. To use this option, you must also use the --nic-generic-drv option.
These properties are specific to the backend engine and differ between the UDP Tunnel and the VDE backend drivers. For property examples, see UDP Tunnel Networking.
- --nic-speed N = kbps
-
Specifies the throughput rate in kilobits per second for rarely used networking sub-modes such as VDE network and UDP Tunnel. Use this option only if you used the --nic option to enable generic networking for the specified virtual network card.
- --nic-boot-prio N = priority
-
Assigns a priority to each NIC that determines the order in which that NIC is used to perform a PXE network boot. The priority value is an integer in the range from
0
to4
. Priority0
, which is the default value, is the lowest priority. Priority1
is the highest priority, and priorities3
and4
are lower.This option has an effect only when using the Intel PXE boot ROM.
- --nic-promisc N =deny | allow-vms | allow-all
-
Enables you to specify whether to deny or allow promiscuous mode for the specified VM virtual network card. This option is relevant only for bridged networking. Valid values are as follows:
-
deny
hides any traffic that is not intended for the VM. This is the default value. -
allow-vms
hides all host traffic from the VM, but allows the VM to see traffic to and from other VMs. -
allow-all
allows the VM to see all traffic.
-
- --nic-bandwidth-group N =none | name
-
Adds or removes a bandwidth group assignment to the specified virtual network interface. Valid values are as follows:
-
none
removes any current bandwidth group assignment from the specified virtual network interface. -
name adds a bandwidth group assignment to the specified virtual network interface.
-
- --bridge-adapter N =none | device-name
-
Specifies the host interface to use for the specified virtual network interface. See Bridged Networking. Use this option only if you used the --nic option to enable bridged networking for the specified virtual network card.
- --host-only-adapter N =none | device-name
-
Specifies which host-only networking interface to use for the specified virtual network interface. See Host-Only Networking. Use this option only if you used the --nic option to enable host-only networking for the specified virtual network card.
- --intnet N = network-name
-
Specifies the name of the internal network. See Internal Networking. Use this option only if you used the --nic option to enable internal networking for the specified virtual network card.
- --nat-network N = network-name
-
Specifies the name of the NAT network to which this adapter is connected. Use this option only if the networking type is
natnetwork
, notnat
. - --nic-generic-drv N = backend-driver
-
Enables you to access rarely used networking sub-modes, such as VDE networks and UDP Tunnel. Use this option only if you used the --nic option to enable generic networking for a virtual network card.
- --mac-address N =auto | MAC-address
-
Specifies the MAC address of the specified network adapter on the VM. By default, Oracle VM VirtualBox assigns a random MAC address to each network adapter at VM creation.
NAT Networking Settings
The following options use N to specify the particular virtual network adapter to modify.
- --nat-net N =default | network
-
Specifies the IP address range to use for this network. See Fine Tuning the Oracle VM VirtualBox NAT Engine. Use this option only if the networking type is
nat
, notnatnetwork
. - --nat-pf N =[ name ],tcp | udp,[ host-IP ], hostport ,[ guest-IP ], guestport
-
Specifies the NAT port-forwarding rule to use. See Configuring Port Forwarding with NAT.
- --nat-pf N =delete name
-
Specifies the NAT port-forwarding rule to delete. See Configuring Port Forwarding with NAT.
- --nat-tftp-prefix N = prefix
-
Specifies a prefix to use for the built-in TFTP server. For example, you might use a prefix to indicate where the boot file is located. See PXE Booting with NAT and Configuring the Boot Server (Next Server) of a NAT Network Interface.
- --nat-tftp-file N = boot-file
-
Specifies the name of the TFT boot file. See Configuring the Boot Server (Next Server) of a NAT Network Interface.
- --nat-tftp-server N = tftp-server
-
Specifies the address of the TFTP server from which to boot. See Configuring the Boot Server (Next Server) of a NAT Network Interface.
- --nat-bind-ip N = IP-address
-
Specifies an alternate IP address to which the NAT engine binds. See Tuning TCP/IP Buffers for NAT. By default, Oracle VM VirtualBox's NAT engine routes TCP/IP packets through the default interface assigned by the host's TCP/IP stack.
- --nat-dns-pass-domain N =on | off
-
Specifies whether the built-in DHCP server passes the domain name for network name resolution.
- --nat-dns-proxy N =on | off
-
Specifies whether the NAT engine is the proxy for all guest DNS requests to the host system's DNS servers. See Enabling DNS Proxy in NAT Mode.
- --nat-dns-host-resolver N =on | off
-
Specifies whether the NAT engine uses the host system's resolver mechanisms to handle DNS requests. See Enabling DNS Proxy in NAT Mode.
- --nat-localhostreachable N =on | off
-
Specifies whether the NAT engine allows traffic from the guest directed to 10.0.2.2 to pass to the host's loopback interface, i.e. localhost or 127.0.0.1.
- --nat-settings N =[ mtu ],[ socksnd ],[ sockrcv ],[ tcpsnd ],[ tcprcv ]
-
Specifies values for tuning NAT performance. See Tuning TCP/IP Buffers for NAT.
- --nat-alias-mode N =default | [log],[proxyonly],[sameports]
-
Specifies the behavior of the NAT engine core as follows:
-
log
enables logging -
proxyonly
switches off aliasing mode and makes NAT transparent -
sameports
enforces that the NAT engine sends packets through the same port on which they originated -
default
disables all aliasing modes
For more information, see Configuring Aliasing of the NAT Engine.
-
Other Hardware Settings
The following options enable you to configure other hardware, such as the serial port, monitor, audio device, USB ports, and the clipboard, and drag-and-drop features.
- --mouse=ps2 | usb | usbtablet | usbmultitouch | usbmtscreenpluspad
-
Specifies the mode of the mouse to use in the VM. Valid values are:
ps2
,usb
,usbtablet
,usbmultitouch
andusbmtscreenpluspad
. - --keyboard=ps2 | usb
-
Specifies the mode of the keyboard to use in the VM. Valid values are:
ps2
andusb
. - --uart N =off | I/O-base IRQ
-
Configures virtual serial ports for the VM. N represents the serial port to modify. Valid values are
off
to disable the port or an I/O base address and IRQ. For information about the traditional COM port I/O base address and IRQ values, see Serial Ports. - --uart-mode N = mode
-
Specifies how Oracle VM VirtualBox connects the specified virtual serial port to the host system that runs the VM. See Serial Ports.
Ensure that you first configure the virtual serial port by using the --uartN option.
Specify one of the following connection modes for each port:
-
disconnected
indicates that even though the serial port is shown to the guest VM, it is not connected. This state is like a physical COM port without a cable attached. -
server
pipe-name creates the specified named pipe or local domain socket on the host system and connects the virtual serial device to it.On a Windows host system, pipe-name is a named pipe that has a name that uses the following form: \\.\pipe\pipe-name.
On a Linux host system, pipe-name is a local domain socket.
-
client
pipe-name connects the virtual serial device to the specified named pipe or local domain socket.Note that the named pipe or local domain socket must already exist.
-
tcpserver
port creates a TCP socket with the specified TCP port on the host system and connects the virtual serial device to it.For UNIX-like systems, use ports over 1024 for non-root users.
-
tcpclient
hostname:port connects the virtual serial device to the TCP socket.Note that the TCP socket must already exist.
-
file
filename redirects the serial port output to the specified raw file. Ensure that filename is the absolute path of the file on the host system. -
device-name: specifies the device name of a physical hardware serial port on the specified host system to which the virtual serial port connects.
Use this mode to connect a physical serial port to a VM.
On a Windows host system, the device name is a COM port such as
COM1
. On a Linux host system, the device name is similar to/dev/ttyS0
.
-
- --uart-type N = UART-type
-
Configures the UART type for the specified virtual serial port (N). Valid values are
16450
,16550A
, and16750
. The default value is16550A
. - --lpt-mode N = device-name
-
Specifies the device name of the parallel port to use.
For a Windows host system, use a device name such as
lpt1
. For a Linux host system, use a device name such as/dev/lp0
. - --lpt N = I/O-base IRQ
-
Specifies the I/O base address and IRQ of the parallel port.
You can view the I/O base address and IRQ that the VM uses for the parallel port in the Device Manager.
- --audio-controller= controller-type
-
Specifies the audio controller to be used with the VM. Valid audio controller type values are:
ac97
,hda
, andsb16
. - --audio-codec= codec-type
-
Specifies the audio codec to be used with the VM. Valid audio codec type values are:
stac9700
,ad1980
,stac9221
, andsb16
. - --audio-driver= type
-
Specifies whether which audio driver (backend) to use.
none
,default
,null
,dsound
,was
,oss
,alsa
,pulse
, andcoreaudio
.Note that the audio driver are dependent on the host operating system. Use the
VBoxManage modifyvm
command usage output to determine the supported audio types for your host system.For maximum interoperability between hosts, the default audio driver can be used. The VM will then automatically select the most appropriate audio driver for the current host available.
- --audio-enabled=on|off
-
Specifies whether to enable or disable audio for the VM.
This option has precedence over the --audio-on and --audio-off options, i.e. turning off audio via this option will turn off both, input and output, audio.
- --audio-in=on|off
-
Specifies whether to enable or disable audio capture from the host system.
- --audio-out=on|off
-
Specifies whether to enable or disable audio playback from the guest VM.
- --clipboard-mode= value
-
Specifies how to share the guest VM or host system OS's clipboard with the host system or guest VM, respectively. Valid values are:
disabled
,hosttoguest
,guesttohost
, andbidirectional
. See General Settings.The clipboard feature is available only if you have the Guest Additions be installed in the VM.
- --clipboard-file-transfers= value
-
Specifies whether file transfers via clipboard between the guest VM and the host are enabled or not. Valid values are:
disabled
,enabled
. Depends on the current clipboard mode being set.This clipboard file transfer feature is available only if you have the Guest Additions be installed in the VM.
- --drag-and-drop= value
-
Specifies how to use the drag and drop feature between the host system and the VM. Valid values are:
disabled
,hosttoguest
,guesttohost
, andbidirectional
. See Drag and Drop.The drag and drop feature is available only if you have the Guest Additions be installed in the VM.
- --monitor-count= count
-
Enables you to configure multiple monitors. See Display Settings.
- --usb-ohci=on | off
-
Enables or disables the VM's virtual USB 1.1 controller. See USB Settings.
- --usb-ehci=on | off
-
Enables or disables the VM's virtual USB 2.0 controller. See USB Settings.
- --usb-xhci=on | off
-
Enables or disables the VM's virtual USB 3.0 controller. This is the most efficient option if the VM supports it. See USB Settings.
- --usb-rename= old-name new-name
-
Rename's the VM's virtual USB controller from old-name to new-name.
Recording Settings
The following options enable you to modify settings for video recording, audio recording, or both.
- --recording=on | off
-
Enables or disables the recording of a VM session into a WebM or VP8 file. When set to
on
, recording begins when the VM session starts. - --recording-screens=all | none | screen-ID [, screen-ID ...
-
Enables you to specify the VM screens to record. The recording for each screen is output to its own file. Valid values are:
all
, which records all screens,none
, which records no screens, or one or more specified screens. - --recording-file= filename
-
Specifies the name of the file in which to save the recording.
- --recording-max-size= MB
-
Specifies the maximum size of the recorded video file in megabytes. When the file reaches the specified size, recording stops. If the value is
0
, recording continues until you manually stop recording. - --recording-max-time= seconds
-
Specifies the maximum amount of time to record in seconds. When the specified time elapses, recording stops. If the value is
0
, recording continues until you manually stop recording. - --recording-opts= keyword = value
-
Specifies additional video-recording properties as a comma-separated property keyword-value list. For example,
foo=bar,a=b
.Only use this option if you are an advanced user. For information about keywords, see the Oracle VM VirtualBox Programming Guide and Reference.
- --recording-video-fps= fps
-
Specifies the maximum number of video frames per second (FPS) to record. The recording ignores any frames that have a higher frequency. When you increase the FPS, fewer frames are ignored but the recording and the size of the recording file increases.
- --recording-video-rate= bit-rate
-
Specifies the bit rate of the video in kilobits per second. When you increase the bit rate, the recording appearance improves and the size of the recording file increases.
- --recording-video-res= width x height
-
Specifies the video resolution (width and height) of the recorded video in pixels.
Remote Machine Settings
The following options enable you to modify the VirtualBox Remote Desktop Extension (VRDE) behavior.
- --vrde=on | off
-
Enables or disables the VRDE server.
- --vrde-property=TCP/Ports= port
-
port is the port or port range to which the VRDE server binds. The
default
or0
value uses port3389
, which is the standard RDP port.Also see the --vrde-port option description.
- --vrde-property=TCP/Address= IP-address
-
IP-address is the IP address of the host network interface to which the VRDE server binds. When specified, the server accepts connections only on the host network interface at that IP address.
Also see the --vrde-address option description.
- --vrde-property=VideoChannel/Enabled= value
-
Specifies whether the VRDP video channel is on or off.
1
meanson
and0
meansoff
. See VRDP Video Redirection. - --vrde-property=Quality= value
-
Specifies a value between 10% and 100%, inclusive, that represents the JPEG compression level on the VRDE server video channel. A lower value produces lower JPEG quality but higher compression. See VRDP Video Redirection.
- --vrde-property=DownscaleProtection= value
-
Enables or disables the video downscale protection feature. Valid values are
1
to enable the feature and0
to disable the feature.When this feature is enabled, Oracle VM VirtualBox determines whether to display the video:
-
When the video size equals the size of the shadow buffer, the video is considered to be full screen and is displayed.
-
When the video size is between full screen and the downscale threshold, the video is not displayed. Such a video might be an application window, which is unreadable when downscaled.
When this feature is disabled, an attempt is always made to display a video.
-
- --vrde-property=Client/DisableDisplay=1
-
Disables the display VRDE server feature.
To reenable a feature, assign an empty value. For example, to reenable the display feature, specify the
VBoxManage modifyvm --vrde-property=Client/DisableDisplay=
command. See VRDP Customization. - --vrde-property=DisableInput=1
-
Disables the input VRDE server feature.
- --vrde-property=DisableAudio=1
-
Disables the audio VRDE server feature.
- --vrde-property=DisableUSB=1
-
Disables the USB VRDE server feature.
- --vrde-property=Client/DisableClipboard=1
-
Disables the clipboard VRDE server feature. To reenable the feature, assign an empty value. See VRDP Customization.
- --vrde-property=DisableUpstreamAudio=1
-
Disables the upstream audio VRDE server feature. To reenable the feature, assign an empty value. See VRDP Customization.
- --vrde-property=Client/DisableRDPDR=1
-
Disables the RDP device redirection for smart cards VRDE server feature. To reenable this feature, assign an empty value.
- --vrde-property=H3DRedirect/Enabled=1
-
Enables the 3D redirection VRDE server feature. To disable this feature, assign an empty value.
- --vrde-property=Security/Method= value
-
Specifies the following information that is required for a connection:
-
Negotiate
indicates that both Enhanced (TLS) and Standard RDP Security connections are permitted. The security method is negotiated with the client. This is the default value. -
RDP
indicates that only Standard RDP Security is accepted. -
TLS
indicates that only Enhanced RDP Security is accepted. The client must support TLS.
See RDP Encryption.
-
- --vrde-property=ServerCertificate= value
-
Specifies the absolute path to the server certificate. See RDP Encryption.
- --vrde-property=ServerPrivateKey= value
-
Specifies the absolute path to the server private key. See RDP Encryption.
- --vrde-property=CACertificate= value
-
Specifies the absolute path to the CA self-signed certificate. See RDP Encryption.
- --vrde-property Audio/RateCorrectionMode= value
-
Specifies the audio connection mode or the path to the audio log file. Valid values are as follows:
-
VRDP_AUDIO_MODE_VOID
is no mode. Use this value to unset any set audio mode. -
VRDP_AUDIO_MODE_RC
is the rate correction mode. -
VRDP_AUDIO_MODE_LPF
is the low pass filter mode. -
VRDP_AUDIO_MODE_CS
is the client sync sync mode to prevent an underflow or overflow of the client queue.
-
- --vrde-property=LogPath= value
-
Specifies the absolute path to the audio log file.
- --vrde-extpack=default | name
-
Specifies the library to use to access the VM remotely. The
default
value uses the RDP code that is part of the Oracle VM VirtualBox Extension Pack.To use the VRDE module in VNC, specify
VNC
. See Other Extension Packs. - --vrde-port=default | port
-
port is the port or port range to which the VRDE server binds. The
default
or0
value uses port3389
, which is the standard RDP port.You can specify a comma-separated list of ports or port ranges of ports. Use a dash between two port numbers to specify a port range. The VRDE server binds to only one of the available ports from the list. Only one machine can use a given port at a time. For example, the --vrde-port=5000,5010-5012 option specifies that server can bind to one of following ports:
5000
,5010
,5011
, or5012
. - --vrde-address= IP-address
-
Specifies the IP address of the host network interface to which the VRDE server binds. If you specify an IP address, the server accepts connections only on the specified host network interface.
Use this option to specify whether the VRDP server should accept IPv4, IPv6, or both type of connections:
-
Only IPv4: Use the --vrde-address="0.0.0.0" option.
-
Only IPv6: Use the --vrde-address="::" option.
-
Both IPv6 and IPv4: Use the --vrde-address="" option. This is the default value.
-
- --vrde-auth-type=null | external | guest
-
Specify whether to use authorization and how to perform authorization. See RDP Authentication. Valid values are as follows:
-
null
provides no authentication. -
external
provides external authentication through an authentication library. -
guest
performs authentication by using guest user accounts. This unsupported method requires that you install the Guest Additions on the VM.
-
- --vrde-auth-library=default | name
-
Specifies the library to use for RDP authentication. The default library for external authentication is
VBoxAuth
. See RDP Authentication. - --vrde-multi-con=on | off
-
Enables or disables the multiple connections VRDE server feature, if supported. See Multiple Connections to the VRDP Server.
- --vrde-reuse-con=on | off
-
Specifies how the VRDE server behaves when multiple connections are disabled. When the value is
on
, the server permits a new client to connect and drops the existing connection. When the value isoff
, a new connection is not accepted if a client is already connected to the server. This is the default value. - --vrde-video-channel=on | off
-
Enables video redirection if supported by the VRDE server. See VRDP Video Redirection.
- --vrde-video-channel-quality= percent
-
Specifies the image quality for video redirection as a value from 10 to 100 percent. The percentage represents the JPEG compression level where a lower number diminishes quality and provides higher compression. See VRDP Video Redirection.
Teleporting Settings
The following options enable you to configure a machine as a teleporting target. See Teleporting and the teleporting related entries in Potentially Insecure Operations.
- --teleporter=on | off
-
Enables or disables the teleporter. When enabled, a machine starts up and waits to receive a teleporting request from the network instead of booting normally.
Teleporting requests are received on the port and address specified using the following parameters.
- --teleporter-port= port
-
Specifies the port on which the VM listens to receive a teleporting request from another VM. port is any free TCP/IP port number, such as
6000
. You must also specify the --teleporter option. - --teleporter-address= IP-address
-
Specifies the IP address on which the VM listens to receive a teleporting request from another VM. IP-address is any IP address or host name and specifies the TCP/IP socket on which to bind. The default IP address is
0.0.0.0
, which represents any IP address. You must also specify the --teleporter option. - --teleporter-password= password
-
Specifies the password to use for authentication. When specified, the teleporting request only succeeds if the password on the source machine is the same password as the one you specify.
- --teleporter-password-file= filename
-
Specifies a file that contains the password to use for authentication. When specified, the teleporting request only succeeds if the password on the source machine is the same password as the one you specify in the password file. A value of
stdin
reads the password from standard input. - --cpuid-portability-level= level
-
Restricts the virtual CPU capabilities that Oracle VM VirtualBox presents to the guest OS by using portability rules. Higher integer values designate more restrictive behavior. The default level of
0
indicates that all virtualized features supported by the host are made available to the guest. The value3
supresses most features. Values of1
and2
represent restrictions in between. The behavior may change depending on the product version. - --cpuid-set= leaf [: subleaf ] eax ebx ecx edx
-
Advanced users can use this setting before a teleporting operation (in fact before starting the VM) to restrict the virtual CPU capabilities that Oracle VM VirtualBox presents to the guest operating system. This must be run on both the source and the target machines involved in teleporting and will then modify what the guest sees when it executes the CPUID machine instruction. This might help with misbehaving applications that wrongly assume that certain CPU capabilities are present. The meaning of the parameters is hardware dependent. Refer to the AMD or Intel processor documentation.
The values of leaf, subleaf (optional), eax, ebx, ecx and edx are integers given in hexadecimal format, i.e. using a radix (base) of 16 without requiring any prefix.
- --cpuid-remove= leaf [: subleaf ]
-
Removes an adjustment established with --cpuid-set.
- --cpuid-remove-all
-
Removes all adjustments established with --cpuid-set.
Debugging Settings
Only use the following options to perform low-level VM debugging. These options are for advanced users only.
- --tracing-enabled=on | off
-
Enables or disables the trace buffer. Note that when specified, the trace buffer consumes some memory and adds overhead.
- --tracing-config= config-string
-
Enables a tracing configuration that defines which group of trace points are enabled.
- --tracing-allow-vm-access=on | off
-
Enables or disables VM access to the trace buffer. The default value is
off
, which disables access.
USB Card Reader Settings
The following options specify the access to a USB Card Reader by the guest environment. A USB card reader can access data on memory cards, such as CompactFlash (CF), Secure Digital (SD), and MultiMediaCard (MMC).
- --usb-card-reader=on | off
-
Enables or disables the USB card reader interface.
Autostarting VMs During Host System Boot
The following options enable you to configure the VM autostart feature, which automatically starts 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.
- --autostart-enabled=on | off
-
Enables or disables VM autostart at host system boot-up for the specified users.
- --autostart-delay= seconds
-
Specifies the number of seconds after host system boot-up to autostart the VM.
Guest Debugging
These options are for configuring the VMM for guest debugging.
- --guest-debug-provider=none | native | gdb | kd
-
Selects the given debug stub provider.
- --guest-debug-io-provider=none | tcp | udp | ipc
-
Selects the given I/O transport backend for the selected provider.
- --guest-debug-address= IP-Address | path
-
Sets the path the debugger is accessible under, depends on the selected I/O transport.
- --guest-debug-port= port
-
Sets the port the debugger is accessible under, depends on the selected I/O transport.
PCI Passthrough Settings
The following options enable you to configure the PCI passthrough feature, which currently is not available in Oracle VM VirtualBox. It is planned to bring this functionality back in the future.
- --pci-attach= host-PCI-address [@ guest-PCI-bus-address ]
-
Attaches the specified PCI network controller on the host to the guest VM. You can optionally specify the PCI bus on the guest VM on which to attach the controller.
- --pci-detach= host-PCI-address
-
Detaches the specified PCI network controller from the attached PCI bus on the guest VM.
Testing (ValidationKit / Bootsector)
These options are for configuring the testing functionality of the VMM device and almost exclusively used by the bootsector testcases in the ValidationKit.
- --testing-enabled=on | off
-
Enabled the testing functionality of the VMMDev. See VMMDevTesting.h for details.
- --testing-mmio=on | off
-
Enabled the MMIO region of the VMMDev testing feature.
- --testing-cfg-dword idx = value
-
This sets one of the 10 dword configuration values. The idx must be in the range 0 thru 9. The value is limited to 32 bits (dword).
VBoxManage movevm
Move a virtual machine to a new location on the host system
Description
The VBoxManage movevm
command moves a virtual
machine (VM) to a new location on the host system.
When moved, all of the files that are associated with the VM, such as settings files and disk image files, are moved to the new location. The Oracle VM VirtualBox configuration is updated automatically.
- uuid | vmname
-
Specifies the Universally Unique Identifier (UUID) or name of the VM to move.
- --type=basic
-
Specifies the type of the move operation. So far
basic
is the only recognized value and also the default if not specified. - --folder= folder-name
-
Specifies a full path name or relative path name of the new location on the host file system. Not specifying the option or specifying the current location is allowed, and moves disk images and other parts of the VM to this location if they are currently in other locations.
VBoxManage natnetwork
Create, modify, and manage a NAT network
Synopsis
Description
The VBoxManage natnetwork
command enables you
to create, modify and manage a NAT network.
NAT networks use the Network Address Translation (NAT) service. The service groups systems into a network and prevents external systems from directly accessing the systems in the network. The service also enables the systems in the network to communicate with each other and with external systems by means of TCP and UDP over IPv4 and IPv6.
A NAT service is attached to an internal network. For a VM to use the NAT service, you must attach the VM to the internal network. Specify the name of the internal network when you create the NAT service. Note that the internal network is created if it does not already exist.
Add a NAT Network Service
The VBoxManage natnetwork add
command creates
a new internal network interface, and adds a NAT network
service. You must use this command before you can attach the VM
to the NAT network.
- --disable
-
Disables the NAT network service.
- --enable
-
Enables the NAT network service.
- --netname= name
-
Specifies the name of the new internal network interface on the host OS.
- --network
-
Specifies the static or DHCP network address and mask of the NAT service interface. By default, this value specifies the static network address.
- --dhcp
-
Enables or disables the DHCP server that you specify by using the --netname option.
- --ipv6
-
Enables or disables IPv6. By default, IPv6 is disabled and IPv4 is enabled.
- --loopback-4= rule
-
Enables an IPv4 loopback interface by using the specified rule.
- --loopback-6= rule
-
Enables an IPv6 loopback interface by using the specified rule.
- --port-forward-4= rule
-
Enables IPv4 port forwarding by using the rule specified by rule.
- --port-forward-6= rule
-
Enables IPv6 port forwarding by using the rule specified by rule.
Remove a NAT Network Service
The VBoxManage natnetwork remove
command
removes the specified NAT network service.
- --netname= name
-
Specifies the name of the NAT network service to remove.
Start a NAT Network Service
The VBoxManage natnetwork start
command
starts a NAT network service and any associated DHCP server.
- --netname= name
-
Specifies the name of the NAT network service to start.
Stop a NAT Network Service
The VBoxManage natnetwork stop
command stops
a NAT network service and any associated DHCP server.
- --netname= name
-
Specifies the name of the NAT network service to stop.
List All NAT Network Services
The VBoxManage natnetwork list
command lists
all NAT network services. You can use a pattern to show a subset
of the NAT network services.
- filter-pattern
-
Specifies an optional filtering pattern.
Modify the Settings of a NAT Network Service
The VBoxManage natnetwork modify
command
modifies the settings of an existing internal network interface.
- --disable
-
Disables the NAT network service.
- --enable
-
Enables the NAT network service.
- --netname= name
-
Specifies the name of the new internal network interface on the host OS.
- --network
-
Specifies the static or DHCP network address and mask of the NAT service interface. By default, this value specifies the static network address.
- --dhcp
-
Enables or disables the DHCP server that you specify by using the --netname option.
- --ipv6
-
Enables or disables IPv6. By default, IPv6 is disabled and IPv4 is enabled.
- --loopback-4= rule
-
Enables an IPv4 loopback interface by using the specified rule.
- --loopback-6= rule
-
Enables an IPv6 loopback interface by using the specified rule.
- --port-forward-4= rule
-
Enables IPv4 port forwarding by using the rule specified by rule.
- --port-forward-6= rule
-
Enables IPv6 port forwarding by using the rule specified by rule.
Examples
The following command shows how to create a NAT network for the
natnet1
internal network that uses the
192.168.15.0/24
network address and mask of the
NAT service interface. In this static configuration, the gateway
is assigned the 192.168.15.1
IP address by
default. Note that this IP address is the next address after the
network address that you specify with the
--network option.
$ VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable
The following command shows how to add a DHCP server to the
natnet1
NAT network after creation:
$ VBoxManage natnetwork modify --netname natnet1 --dhcp on
VBoxManage registervm
Register a virtual machine
Description
The VBoxManage registervm
command enables you
to create a virtual machine (VM) by importing an XML machine
configuration file into Oracle VM VirtualBox. The VM cannot have the
same UUID as a VM that is already registered in Oracle VM VirtualBox.
Ensure that the XML machine configuration file is in the machines
folder prior to registration.
Note:
When you use the VBoxManage createvm
command
to create a VM, you can specify the --register
option to register the VM.
- filename
-
Specifies the XML machine configuration file. This file has the
.vbox
file extension. - --password
-
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.
VBoxManage setextradata
Set a keyword value that is associated with a virtual machine or configuration
Description
The VBoxManage setextradata
command enables you
to set a keyword value that is associated with a virtual machine
(VM) or with an Oracle VM VirtualBox configuration.
-
global
-
Sets information about the configuration rather than a VM.
- uuid | vmname
-
Specifies the Universally Unique Identifier (UUID) or name of the VM.
- keyword
-
Specifies the keyword for which to set its value.
- value
-
Specifies the keyword value. Specifying no value removes the keyword.
VBoxManage setproperty
Change global settings
Description
The VBoxManage setproperty
command enables you
to change global settings that affect the entire Oracle VM VirtualBox
installation. Some of these settings correspond to the settings in
the Preferences dialog in the
VirtualBox Manager.
The following properties are available:
-
autostartdbpath
-
Specifies the path to the autostart database. Valid values are
null
, which disables the autostart database, or the name of the folder that contains the database. See Starting Virtual Machines During System Boot. -
defaultfrontend
-
Specifies the global default VM frontend. Valid values are
default
, which specifies the default frontend, or the name of the frontend to use. -
hwvirtexclusive
-
Specifies whether Oracle VM VirtualBox makes exclusive use of the Intel VT-x or AMD-V hardware virtualization extensions of the host system's processor. See Hardware Virtualization.
Valid values are as follows:
-
on
enables Oracle VM VirtualBox to make exclusive use of these extensions. This is the default value. -
off
shares these extensions with other hypervisors that run simultaneously. Note that disabling this setting has negative performance implications.
-
-
language
-
Specifies the user language used to translate API messages. Valid values are
C
, which means no translation or language code in form eitherll
orll_CC
, wherell
is language 2 letters code in lower case andCC
is country 2 letter code in upper case. -
logginglevel
-
Specifies the VBoxSVC release logging details. See http://www.virtualbox.org/wiki/VBoxLogging.
-
loghistorycount
-
Specifies the number of rotated VM logs to retain.
-
machinefolder
-
Specifies the default folder in which virtual machine (VM) definitions are stored. Valid values are
default
, which specifies the default storage folder, or the name of the folder to use. See Where Oracle VM VirtualBox Stores its Files. -
proxymode
-
Configures the mode for an HTTP proxy server. Valid values are as follows:
-
manual
-
Configure the URL of a HTTP proxy server manually, using the
proxyurl
property value. -
noproxy
-
Do not use an HTTP proxy server. A direct connection to the Internet is used.
-
system
-
Detect the proxy settings automatically for the host network. This is the default value.
-
-
proxyurl
-
Specifies the URL for an HTTP proxy server when you specify a manual proxy by setting the
proxymode
property tomanual
. -
vrdeauthlibrary
-
Specifies which library to use when external authentication has been configured for a particular VM. Valid values are
default
, which specifies the default library, or the name of the library to use. See RDP Authentication. -
vrdeextpack
-
Specifies the library that implements the VirtualBox Remote Desktop Extension (RDE). Valid values are
null
, which disables the RDE, or the name of the library to use. -
websrvauthlibrary
-
Specifies which library the web service uses to authenticate users. Valid values are
default
, which specifies the default library,null
, which disables authentication, or the name of the library to use. For information about the Oracle VM VirtualBox web service, see Oracle VM VirtualBox Programming Interfaces.
VBoxManage sharedfolder
Add and remove shared folders
Description
Shared folders enable you to share data between the host system and guests. To use shared folders, you must first install the Oracle VM VirtualBox Guest Additions software on the guest OS.
The shared folder is associated with a share name and the full path name of the folder or directory on the host system. The share name is a unique name within the namespace of the host OS.
Add a Shared Folder
The VBoxManage sharedfolder add
command
creates a shared folder. The folder you specify is on the host
computer. When configured, the contents of the folder on the
host system can be shared with the guest OS.
- uuid | vmname
-
Specifies the name or UUID of the guest VM that shares a folder with the host system.
- --name=name
-
Specifies the name of the share, which is a unique name within the namespace of the host OS.
- --hostpath=hostpath
-
Specifies the absolute path of the folder or directory on the host OS to share with the guest OS.
- --readonly
-
Specifies that the share has only read-only access to files at the host path.
By default, shared folders have read-write access to the files at the host path. However on Linux distributions, shared folders are mounted with 770 file permissions with the
root
user and thevboxsf
group. By using this option, the file permissions become 700. - --transient
-
Specifies that the share is transient, which means that it can be added and removed at runtime and does not persist after the VM stops.
- --automount
-
Specifies that the share is automatically mounted.
- --auto-mount-point=path
-
Specifies the mount point of the share. This guest OS specific.
For Windows and OS/2 guest this must be an unused drive letter. If left blank (or if the drive letter is already in use), the last unused drive letter is used instead (i.e. searching from
Z:
thruA:
).For Linux, Solaris and other unix guest, it must be an absolute path like
/mnt/mysharedfolder
. If left empty the default location is/media/sf_sharename
.
Remove a Shared Folder
The VBoxManage sharedfolder remove
command
removes a shared folder.
- uuid | vmname
-
Specifies the name or UUID of the guest VM that shares a folder with the host system.
- --name=name
-
Specifies the name of the share to remove.
- --transient
-
Specifies that the share is transient, which means that it can be added and removed at runtime and does not persist after the VM stops.
Examples
The following command creates a shared folder called
o7share
for the ol7
VM.
The share is mounted automatically when the VM is started.
$ VBoxManage sharedfolder add ol7 --name ol7share --hostpath "/home/user/ol7share" --automount
The following command removes the shared folder called
o7share
for the ol7
VM.
$ VBoxManage sharedfolder remove ol7 --name ol7share
VBoxManage showmediuminfo
Show information about a medium
Description
The VBoxManage showmediuminfo
command shows the
following information about a medium:
-
Size
-
Size on disk
-
Type
-
In use by virtual machines (VMs)
The medium must be specified either by its UUID, if the medium is
registered, or by its filename. Registered images can be listed
using VBoxManage list hdds
, VBoxManage
list dvds
, or VBoxManage list
floppies
, as appropriate.
For backward compatibility, you can also use the
showvdiinfo
command to obtain information about
the medium.
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.
If the medium is registered, you can specify the UUID. You can also list registered images by using the
VBoxManage list hdds
,VBoxManage list dvds
, orVBoxManage list floppies
command.
VBoxManage showvminfo
Show configuration information or log file contents for a virtual machine
Synopsis
Description
The VBoxManage showvminfo
command outputs
configuration information or log file contents for a specified
virtual machine (VM).
Viewing Virtual Machine Information
The VBoxManage showvminfo
command outputs
information about the specified VM in a detailed format or in a
machine-readable format.
The VBoxManage showvminfo
command shows the
same information for the specified VM in the same format as the
VBoxManage list vms --long
command.
- --details
-
Includes detailed information about the VM.
- --machinereadable
-
Specifies that the VM information be in a machine-readable format.
- --password-id id
-
Specifies password id of the VM if it is encrypted.
- --password file |-
-
Specifies password of the VM if it is encrypted. Either specify the absolute pathname of a password file on the host operating system, or
-
to prompt you for the password.
Viewing Virtual Machine Log Contents
The VBoxManage showvminfo --log
command
outputs the contents of one of the specified VM's log files.
- --log= index
-
Specifies a numerical index that identifies the log file.
The index value starts at
0
, which indicates theVBox.log
file. An index value of1
indicates theVBoxHardening.log
file. Index values starting at2
indicate other log files, such as theVBox.log.1
file. - --password-id id
-
Specifies password id of the VM if it is encrypted.
- --password file |-
-
Specifies password of the VM if it is encrypted. Either specify the absolute pathname of a password file on the host operating system, or
-
to prompt you for the password.
Examples
The following example shows typical output for this command:
$ VBoxManage showvminfo "Windows 10"
VirtualBox Command Line Management Interface Version version-number
Copyright (C) 2005-2023 Oracle and/or its affiliates
Name: Windows 10
Groups: /
Guest OS: Windows 10 (64-bit)
UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7
Config file: /home/username/VirtualBox VMs/Windows 10/Windows 10.vbox
Snapshot folder: /home/username/VirtualBox VMs/Windows 10/Snapshots
Log folder: /home/username/VirtualBox VMs/Windows 10/Logs
Hardware UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7
Memory size: 2048MB
Page Fusion: off
VRAM size: 12MB
CPU exec cap: 100%
...
The following example shows the information output in a machine-readable format, which shows the entries as a property=value string:
$ VBoxManage showvminfo "Windows 10" --machinereadable ... groups="/" ostype="Windows 10 (64-bit)" UUID="1bf3464d-57c6-4d49-92a9-a5cc3816b7e7" ...
The following example shows the contents of the
VBox.log
log file:
$ VBoxManage showvminfo "Windows 10" --log 0 00:00:02.895106 VirtualBox VM 6.0.0_RC1 r127378 linux.amd64 (Dec 10 2018 17:16:06) release log 00:00:02.895109 Log opened 2018-12-14T14:31:44.088259000Z 00:00:02.895111 Build Type: release 00:00:02.895115 OS Product: Linux 00:00:02.895117 OS Release: 4.1.12-61.1.22.el7uek.x86_64 00:00:02.895119 OS Version: #2 SMP Fri Dec 2 09:28:44 PST 2016 ...
VBoxManage signova
Digitally sign an OVA
Synopsis
Description
The VBoxManage signova
command adds a digital
signature to an OVA file.
- ova
-
The OVA file to sign.
- --certificate= file
-
File containing the certificate that the OVA should be signed with. This can either be in PEM format (base64) or DER (binary), the command will detect which.
- --private-key= file
-
The file containing the private key. This can either be in PEM (base64) or DER (binary) format, the command will detect which.
- --private-key-password-file= password-file
-
File containing the private key password.
- --private-key-password= password
-
The private key password.
- --digest-type= type
-
Select the cryptographic digest algorithm to use in the signing. Possible values: SHA-256 (default), SHA-512 and SHA-1.
Some older versions of OVFTool and other VMware produces may require --digest-type=sha-1 to accept the OVA.
- --pkcs7, --no-pkcs7
-
Enables or disables the creation of an additional PKCS#7/CMS signature. This is enabled by default.
- --intermediate-cert= file
-
File containing an intermediary certificate that should be included in the optional PKCS#7/CMS signature. Like the others, the file can either be in PEM or DER format. This option can be repeated to add multiple intermediate certificates. This option implies the --pkcs7 option.
- --force
-
Overwrite existing signature if present. The default behaviour is to fail if the OVA is already signed.
- --dry-run
-
Do not actually modify the OVA, just test-run the signing operation.
- -v, --verbose, -q, --quiet
-
Controls the verbositity of the command execution. The --verbose option can be used multiple times to get more output.
VBoxManage snapshot
Manage virtual machine snapshots
Synopsis
Description
The VBoxManage snapshot
command manages
snapshots.
Oracle VM VirtualBox uses the snapshot to capture the state of a virtual machine (VM). You can later use the snapshot to revert to the state described by the snapshot.
A snapshot is a complete copy of a VM's settings. If you take the snapshot while the VM is running, the snapshot also includes the VM's state file.
After you take a snapshot, Oracle VM VirtualBox creates a differencing hard disk for each normal hard disk that is associated with the host machine. When you restore a snapshot, Oracle VM VirtualBox uses these differencing files to quickly reset the contents of the VM's virtual hard disks.
For each VBoxManage snapshot
command, you must
specify the name or the universal unique identifier (UUID) of the
VM for which you want to take a snapshot.
Take a Snapshot of a Virtual Machine
The VBoxManage snapshot take
command takes a
snapshot of the current state of the VM. You must supply a name
for the snapshot and can optionally supply a description. The
new snapshot is inserted into the snapshots tree as a child of
the current snapshot and then becomes the new current snapshot.
- --description= description
-
Specifies a description of the snapshot.
- --live
-
Specifies that the VM is not stopped while you create the snapshot. This operation is know as live snapshotting.
- --uniquename Number,Timestamp,Space,Force
-
TBD.
- snapshot-name
-
Specifies the name of the snapshot to create.
Delete a Snapshot
The VBoxManage snapshot delete
command
removes the specified snapshot.
The delete operation may take some time to finish. This is because the differencing images that are associated with the snapshot may need to be merged with their child differencing images.
- snapshot-name
-
Specifies the UUID or name of the snapshot.
Restore a Snapshot
The VBoxManage snapshot restore
command
restores the specified snapshot. This operation resets the VM's
settings and current state to that of the snapshot. The state of
the VM on which you restore a snapshot is lost. When restored,
the specified snapshot becomes the new current snapshot and
subsequent snapshots are children of that snapshot.
- snapshot-name
-
Specifies the UUID or name of the snapshot.
Restore the Current Snapshot
The VBoxManage snapshot restorecurrent
command restores the current snapshot. The current snapshot is
the one from which the current state is derived. This command is
equivalent to using the VBoxManage snapshot
restore
command and specifying the name or UUID of the
current snapshot.
Change the Name or Description of an Existing Snapshot
The VBoxManage snapshot edit
command enables
you to change the name or the description of a specified
snapshot.
- snapshot-name
-
Specifies the UUID or name of the snapshot to edit.
This option is mutually exclusive with the --current option.
- --current
-
Specifies that you update the current version of the snapshot.
This option is mutually exclusive with a specific snapshot name or its UUID.
- --description= description
-
Specifies a new description for the snapshot.
- --name= new-name
-
Specifies a new name for the snapshot.
List the Snapshots
The VBoxManage snapshot list
command lists
all the snapshots for a VM.
- --details
-
Specifies that the output shows detailed information about the snapshot.
This option is mutually exclusive with the --machinereadable option.
- --machinereadable
-
Specifies that the output is shown in a machine-readable format.
This option is mutually exclusive with the --details option.
Examples
The following command creates a snapshot of the ol7u4 VM. The snapshot is called ol7u4-snap-001. The command uses the --description option to provide a description of the snapshot contents.
$ VBoxManage snapshot ol7u4 take ol7u4-snap-001 \ --description="Oracle Linux 7.4"
The following command lists the snapshots for the ol7u4 VM.
$ VBoxManage snapshot ol7u4 list
The following command changes the description for the ol7u4-snap-001 snapshot of the ol7u4 VM.
$ VBoxManage snapshot ol7u4 edit ol7u4-snap-001 \ --description="Oracle Linux 7.4 with UEK4 kernel"
The following command shows VM settings for the ol7u1-snap-001 snapshot of the ol7u4 VM.
$ VBoxManage snapshot ol7u4 showvminfo ol7u4-snap-001 Name: ol7u4 Groups: / Guest OS: Oracle (64-bit) UUID: 43349d78-2ab3-4cb8-978f-0e755cd98090 Config file: C:\Users\user1\VirtualBox VMs\ol7u4\ol7u4.vbox ... Snapshots: Name: ol7u4-snap-001 (UUID: 1cffc37d-5c37-4b86-b9c5-a0f157a55f43) Description: Oracle Linux 7.4 with UEK4 kernel
VBoxManage startvm
Start a virtual machine
Synopsis
Description
The VBoxManage startvm
command starts an
Oracle VM VirtualBox virtual machine (VM) that is in the Powered Off or
Saved state.
- uuid | vmname
-
Specifies the name or Universally Unique Identifier (UUID) of the VM.
- --putenv= name = value
-
Assigns a value to an environment variable as a name-value pair. For example, VBOX_DISABLE_HOST_DISK_CACHE=1.
The short form of this option is -E.
- --type=gui | headless | sdl | separate
-
Specifies the frontend used to start the VM.
You can use the
VBoxManage setproperty
command to set a global default value for the frontend. Alternatively, you can use theVBoxManage modifyvm
command to specify a default frontend value for a specific VM. If neither a global or per-VM default value is set and you do not specify the --type option, then the VM opens in a window on the host desktop.The --type option accepts the following values:
-
gui
-
Starts a VM in a graphical user interface (GUI) window. This is the default.
-
headless
-
Starts a VM for remote display only.
-
sdl
-
Starts a VM using the VBoxSDL frontend.
-
separate
-
Starts a VM with a detachable user interface (UI), which means that the VM runs headless with the UI in a separate process.
This is an experimental feature that lacks certain functionality, such as 3D acceleration.
-
- --password
-
Use the --password to supply the encryption password. 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. - --password-id
-
Use the --password-id option to specify the id the password is supplied for.
Note:
If a VM fails to start with a particular frontend and the error information is inconclusive, consider starting the VM directly by running the frontend. This workaround might provide additional error information.
VBoxManage storageattach
Attach, remove, and modify storage media used by a virtual machine
Synopsis
Description
The VBoxManage storageattach
command enables
you to manage a storage medium that you connected to a storage
controller by using the VBoxManage storagectl
command.
- uuid | vmname
-
Specifies the Universally Unique Identifier (UUID) or the name of the virtual machine (VM).
- --storagectl= name
-
Specifies the name of the storage controller. Use the
VBoxManage showvminfo
command to list the storage controllers that are attached to the VM. - --port= number
-
Specifies the port number of the storage controller to modify. You must specify this option unless the storage controller has only a single port.
- --device= number
-
Specifies the port's device number to modify. You must specify this option unless the storage controller has only one device per port.
- --type=dvddrive | fdd | hdd
-
Specifies the drive type to which the medium is associated. Only omit this option if the medium type can be determined by using the --medium option or by information provided by an earlier medium attachment command.
- --medium=none | emptydrive | additions | uuid | filename | host: drive | iscsi
-
Specifies one of the following values:
-
none
-
Removes any existing device from the specified slot.
-
emptydrive
-
For a virtual DVD or floppy drive only.
Makes the device slot behave like a removeable drive into which no media has been inserted.
-
additions
-
For a virtual DVD drive only.
Attaches the VirtualBox Guest Additions image to the specified device slot.
- uuid
-
Specifies the UUID of a storage medium to attach to the specified device slot. The storage medium must already be known to Oracle VM VirtualBox, such as a storage medium that is attached to another VM. Use the
VBoxManage list
command to list media. - filename
-
Specifies the full path of an existing disk image to attach to the specified device slot. The disk image can be in ISO, RAW, VDI, VMDK, or other format.
- host: drive
-
For a virtual DVD or floppy drive only.
Connects the specified device slot to the specified DVD or floppy drive on the host computer.
-
iscsi
-
For virtual hard disks only.
Specifies an iSCSI target for which you must specify additional information. See iSCSI Servers.
For removeable media such as floppies and DVDs, you can make configuration changes while a VM is running. Changes to devices or hard disk device slots require that the VM be powered off.
-
- --mtype=normal | writethrough | immutable | shareable | readonly | multiattach
-
Specifies how this medium behaves with respect to snapshots and write operations. See Special Image Write Modes.
- --comment= text
-
Specifies an optional description to store with the medium.
- --setuuid= uuid
-
Modifies the UUID of a medium before attaching it to a VM.
This is an expert option. Inappropriate values might make the medium unusable or lead to broken VM configurations if another VM already refers to the same medium.
Using the --setuuid="" option assigns a new random UUID to an image, which can resolve duplicate UUID errors if you used a file copy utility to duplicate an image.
- --setparentuuid= uuid
-
Modifies the parent UUID of a medium before attaching it to a VM.
This is an expert option. Inappropriate values might make the medium unusable or lead to broken VM configurations if another VM already refers to the same medium.
- --passthrough=on | off
-
For a virtual DVD drive only.
Enables writing to a DVD. This feature is experimental, see CD/DVD Support.
- --tempeject=on | off
-
For a virtual DVD drive only.
Specifies whether to permit a temporary guest-triggered medium eject operation. When set to
on
, you can eject a medium. The ability for a guest-triggered eject operation does not persist if the VM is powered off and restarted. So, when you set this option toon
and the VM is restarted, the originally configured medium is still in the drive. - --nonrotational=on | off
-
Enables you to specify that the virtual hard disk is non-rotational. Some guest OSes, such as Windows 7 or later, treat such disks as solid state drives (SSDs) and do not perform disk fragmentation on them.
- --discard=on | off
-
Specifies whether to enable the auto-discard feature for a virtual hard disk. When set to
on
, a VDI image is shrunk in response to atrim
command from the guest OS.The virtual hard disk must meet the following requirements:
-
The disk format must be VDI.
-
The size of the cleared area of the disk must be at least 1 MB.
-
Ensure that the space being trimmed is at least a 1 MB contiguous block at a 1 MB boundary.
Consider running defragmentation commands as background cron jobs to save space. On Windows, run the
defrag.exe /D
command. On Linux, run thebtrfs filesystem defrag
command.Note:
When you configure the guest OS to issue the
trim
command, the guest OS typically sees the disk as an SSD.Ext4 supports the -o discard mount option. Mac OS X might require additional settings. Windows 7, 8, and 10 automatically detect and support SSDs. The Linux
exFAT
driver from Samsung supports thetrim
command.The Microsoft implementation of exFAT might not support this feature.
You can use other methods to issue trim commands. The Linux
fstrim
command is part of theutil-linux
package. Earlier solutions required you to zero out unused areas by using thezerofree
or a similar command, and then to compact the disk. You can only perform these steps when the VM is offline. -
- --bandwidthgroup= name
-
Specifies the bandwidth group to use for the device. See Limiting Bandwidth for Disk Images.
- --forceunmount
-
For a virtual DVD or floppy drive only.
Forcibly unmounts the DVD, CD, or floppy or mounts a new DVD, CD, or floppy even if the previous removable storage is locked by the guest for reading. See CD/DVD Support.
The following options are applicable when you specify the --medium=iscsi option:
- --server= hostname | IP-address
-
Specifies the host name or IP address of the iSCSI target.
- --target= target
-
Specifies the target name string, which is determined by the iSCSI target and is used to identify the storage resource.
- --tport= port
-
Specifies the TCP/IP port number of the iSCSI service on the target.
- --lun= LUN
-
Specifies the logical unit number (LUN) of the target resource. For a single disk drive, the value is zero.
- --encodedlun= LUN
-
Specifies the hexadecimal-encoded of the target resource. For a single disk drive, the value is zero.
- --username= username
-
Specifies the user name to use for target authentication.
Note:
Unless you provide a settings password, the user name is stored as clear text in the XML machine configuration file.
- --password= password
-
Specifies the password used for target authentication.
Note:
Unless you provide a settings password, this password is stored as clear text in the XML machine configuration file. When you specify a settings password for the first time, the target authentication password is stored in encrypted form.
- --passwordfile= password-filename
-
Specifies a file that contains the target authentication password as clear text.
Note:
Use permission and ownership settings to ensure that the contents of this file cannot be read by unauthorized users.
- --initiator= initiator
-
Specifies the iSCSI initiator.
The Microsoft iSCSI Initiator is a system, such as a server, that attaches to an IP network and initiates requests and receives responses from an iSCSI target. The SAN components in the iSCSI initiator are largely analogous to Fibre Channel SAN components, and they include the following:
-
iSCSI driver. Transports blocks of iSCSI commands over the IP network. This iSCSI driver is installed on the iSCSI host and is included with the Microsoft iSCSI Initiator.
-
Gigabit Ethernet adapter. Connects to an iSCSI target. Use an Ethernet adapter that can transmit 1000 megabits per second (Mbps). Like standard 10/100 adapters, most gigabit adapters use a preexisting Category 5 or Category 6E cable. Each port on the adapter is identified by a unique IP address.
-
iSCSI target. Is any device that receives iSCSI commands. The device can be an end node such as a storage device, or it can be an intermediate device such as a network bridge between IP and Fibre Channel devices. Each port on the storage array controller or network bridge is identified by one or more IP addresses.
-
- --intnet
-
Specifies whether to connect to the iSCSI target that uses internal networking. This configuration requires further configuration. See Access iSCSI Targets Using Internal Networking.
Examples
The following command attaches the o7.vdi
disk image to the specified SATA storage controller on the
ol7
VM.
$ storageattach ol7 --storagectl "SATA Controller" --port 0 --device 0 \ --type hdd --medium /VirtualBox/ol7/ol7.vdi
The following command attaches the
o7-r6-dvd.iso
DVD image to the specified IDE
storage controller on the ol7
VM.
$ VBoxManage storageattach ol7 --storagectl "IDE Controller" --port 0 --device 0 \ --type dvddrive --medium ol7-r6-dvd.iso
VBoxManage storagectl
Manage a storage controller
Synopsis
Description
The VBoxManage storagectl
command enables you
to attach, modify, and remove a storage controller. After you
configure the storage controller, you can use the
VBoxManage storageattach
command to attach
virtual media to the controller.
- uuid | vmname
-
Specifies the Universally Unique Identifier (UUID) or name of the virtual machine (VM).
- --name= controller-name
-
Specifies the name of the storage controller.
- --add= system-bus-type
-
Specifies the type of the system bus to which to connect the storage controller. Valid values are
floppy
,ide
,pcie
,sas
,sata
,scsi
, andusb
. - --controller= chipset-type
-
Specifies the chipset type to emulate for the specified storage controller. Valid values are
BusLogic
,I82078
,ICH6
,IntelAHCI
,LSILogic
,LSILogicSAS
,NVMe
,PIIX3
,PIIX4
, andUSB
.The default value varies, according to the type of storage controller.
- --portcount= count
-
Specifies the number of ports that the storage controller supports. Valid values depend on the type of storage controller.
- --hostiocache=on|off
-
Specifies whether to use the host I/O cache for all disk images attached to this storage controller. Valid values are
on
andoff
. See Host Input/Output Caching. - --bootable=on|off
-
Specifies whether this controller is bootable. Valid values are
on
andoff
. - --rename= new-controller-name
-
Specifies a new name for the storage controller.
- --remove
-
Removes a storage controller from the VM configuration.
Examples
The following command creates a SATA storage controller called
sata01
and adds it to the
ol7
VM. The storage controller emulates the
IntelAHCI chipset.
$ VBoxManage storagectl ol7 --name "sata01" --add sata --controller IntelAHCI
The following command creates an IDE storage controller called
ide01
and adds it to the ol7
VM.
$ VBoxManage storagectl ol7 --name "ide01" --add ide
VBoxManage unattended
Unattended guest OS installation
Synopsis
Description
unattended detect
Detects the guest operating system (OS) on the specified installation ISO and displays the result. This can be used as input when creating a VM for the ISO to be installed in.
- --iso= install-iso
-
The installation ISO to run the detection on.
- --machine-readable
-
Produce output that is simpler to parse from a script.
unattended install
Reconfigures the specified VM for installation and optionally starts it up.
- uuid | vmname
-
Either the UUID or the name (case sensitive) of a VM.
- --iso= install-iso
-
The installation ISO to run the detection on.
- --user= login
-
The login name. (default: vboxuser)
- --password= password
-
The login password. This is used for the user given by --user as well as the root/administrator user. (default: changeme)
- --password-file= file
-
Alternative to --password for providing the password. Special filename stdin can be used to read the password from standard input.
- --full-user-name= name
-
The full user name. (default: --user)
- --key= product-key
-
The guest OS product key. Not all guest OSes requires this.
- --install-additions, --no-install-additions
-
Whether to install the VirtualBox guest additions. (default: --no-install-addations)
- --additions-iso= add-iso
-
Path to the VirtualBox guest additions ISO. (default: installed/downloaded GAs)
- --install-txs, --no-install-txs
-
Whether to install the test execution service (TXS) from the VirtualBox ValidationKit. This is useful when preparing VMs for testing or similar. (default: --no-install-txs)
- --validation-kit-iso= testing-iso
-
Path to the VirtualBox ValidationKit ISO. This is required if --install-txs is specified.
- --locale= ll_CC
-
The base locale specification for the guest, like en_US, de_CH, or nn_NO. (default: host or en_US)
- --country= CC
-
The two letter country code if it differs from the specified by --location.
- --time-zone= tz
-
The time zone to set up the guest OS with. (default: host time zone or UTC)
- --hostname= fqdn
-
The fully qualified domain name of the guest machine. (default: vmname.myguest.virtualbox.org)
- --package-selection-adjustment= keyword
-
Adjustments to the guest OS packages/components selection. This can be specfied more than once. Currently the only recognized keyword is minimal which triggers a minimal installation for some of the guest OSes.
- --dry-run
-
Do not create any files or make any changes to the VM configuration.
- --start-vm= session-type
-
Start the VM using the front end given by session-type. This is the same as the --type option for the startvm command, but we have add none for indicating that the VM should not be started. (default: none)
Advanced options:
- --auxiliary-base-path= path
-
The path prefix to the media related files generated for the installation. (default: vm-config-dir/Unattended-vm-uuid-)
- --image-index= number
-
Windows installation image index. (default: 1)
- --script-template= file
-
The unattended installation script template. (default: IMachine::OSTypeId dependent)
- --post-install-template= file
-
The post installation script template. (default: IMachine::OSTypeId dependent)
- --post-install-command= command
-
A single command to run after the installation is completed. The exact format and exactly when this is run is guest OS installer dependent.
- --extra-install-kernel-parameters= params
-
List of extra linux kernel parameters to use during the installation. (default: IMachine::OSTypeId dependent)
- --language= lang
-
Specifies the UI language for a Windows installation. The lang is generally on the form {ll}-{CC}. See detectedOSLanguages results from
VBoxManage unattended detect
. (default: detectedOSLanguages[0])
VBoxManage unregistervm
Unregister a virtual machine
Description
The VBoxManage unregistervm
command unregisters
a virtual machine (VM).
- uuid | vmname
-
Specifies the name or Universally Unique Identifier (UUID) of the VM.
- --delete
-
Deletes the following files related to the VM automatically:
-
All hard disk image files, including differencing files.
-
All saved state files that the machine created, including one for each snapshot.
-
XML VM machine definition file and its backups.
-
VM log files.
-
The empty directory associated with the unregistered VM.
-
- --delete-all
-
Deletes the files described in the --delete option, as well as all DVDs and Floppy disks located in the VM folder and attached only to this VM.
VBoxManage updatecheck
Checks for a newer version of VirtualBox
Synopsis
Description
The updatecheck
subcommand is used to check if a newer
version of VirtualBox is available. The two subcommand options of updatecheck
are used for modifying or viewing the settings associated with checking for a newer version
of VirtualBox.
updatecheck perform
Checks if a newer version of VirtualBox is available.
- --machine-readable
-
Machine readable output.
updatecheck list
Displays the current settings used for specifying when to check for a newer version of VirtualBox.
- --machine-readable
-
Machine readable output.
updatecheck modify
Modifies the settings used for specifying when to check for a newer version of VirtualBox.
- --enable
-
Enable the update check service.
- --disable
-
Disable the update check service.
- --channel=stable | withbetas | all
-
The preferred release type used for determining whether a newer version of VirtualBox is available. The default is 'stable'.
- stable
-
Checks for newer stable releases (maintenance and minor releases within the same major release) of VirtualBox.
- all
-
Checks for newer stable releases (maintenance and minor releases within the same major release) and major releases of VirtualBox.
- withbetas
-
Checks for newer stable releases (maintenance and minor releases within the same major release), major releases, and beta releases of VirtualBox.
- --frequency=days
-
Specifies how often in days to check for a newer version of VirtualBox.
- --proxy-mode=system | manual | none
-
Specifies the proxy mode to use.
- --proxy-url=<address>
-
Specifies the proxy address to use. Set to empty string to clear proxy address.
VBoxManage usbdevsource
Add and remove USB device sources
Synopsis
Description
The VBoxManage usbdevsource
command adds a USB
device source and makes it available to the guests on the host
system. You can also use this command to remove the USB device
source.
Add a USB Device Source
The VBoxManage usbdevsource add
command adds
a USB device source, which is available to all guests on the
host system.
- source-name
-
Specifies a unique name for the USB device source.
- --address=address
-
Specifies the address of the USB backend.
- --backend=backend
-
Specifies the USB proxy service backend to use.
For now only USBIP is supported to specify a remote server using the USB/IP protocol.
VBoxManage usbfilter
Manage USB filters
Synopsis
Description
The VBoxManage usbfilter
command enables you to
manage USB filters for a specific virtual machine (VM), or global
USB filters that affect the entire Oracle VM VirtualBox configuration.
Global filters are applied before VM-specific filters. This means that you can use a global filter to prevent devices from being captured by any VM.
Global filters are applied in a particular order. Only the first filter that fits a device is applied. For example, the first global filter makes a specific Kingston memory stick device available while the second filter ignores all Kingston devices. The result of applying these filters is that the specific Kingston memory stick is made available to any machine that has the appropriate filter, but no other Kingston devices are made available.
Common Operand and Options
- index,0-N
-
Specifies a single integer that indicates the position of the filter in the list. Zero (
0
) represents the first position in the list. If a filter already exists at the specified position, the existing filter and any existing filters that follow are moved down the list. Otherwise, the new filter is appended to the list. - --action=ignore | hold
-
Specifies whether to permit VMs access to devices that fit the filter description (
hold
) or to deny them access (ignore
). This option applies only to global filters. - --active=yes | no
-
Specifies whether the USB filter is active or temporarily disabled. Valid values are
yes
, which activates the filter, andno
, which disables the filter. The default value isyes
. - --manufacturer= string
-
Specifies a manufacturer ID filter as a string. The default value is an empty string (
""
). - --maskedinterfaces= XXXXXXXX
-
Specifies a masked interface filter that is used to hide one or more USB interfaces from the guest. The value is a bit mask where the set bits correspond to the USB interfaces to hide, or mask off. This feature is supported on Linux host systems only.
- --name= filter-name
-
Specifies the name of the filter.
- --port= hex
-
Specifies a hub port number filter as a string. The default value is an empty string (
""
). - --product= string
-
Specifies a product ID filter as a string. The default value is an empty string (
""
). - --productid= XXXX
-
Specifies a product ID filter. The string representation for an exact match has the form XXXX, where X is a hexadecimal digit including leading zeroes. The default value is an empty string (
""
). - --remote=yes | no
-
Specifies a remote filter that indicates whether the device is physically connected to a remote VRDE client or to a local host system. This option applies to VM filters only. The default value is an empty string (
""
). - --revision= IIFF
-
Specifies a revision ID filter. The string representation for an exact match has the form IIFF. I is a decimal digit of the integer part of the revision. F is a decimal digit of its fractional part that includes leading and trailing zeros. The default value is an empty string (
""
).To specify a range of revision IDs, ensure that you use the hexadecimal form so that the revision is stored as a 16-bit packed BCD value. For example, the
int:0x0100-0x0199
expression matches any revision from 1.0 to 1.99, inclusive. - --serialnumber= string
-
Specifies a serial number filter as a string. The default value is an empty string (
""
). - --target= uuid | vmname | global
-
Specifies the VM that the filter is attached to. You can specify the Universally Unique Identifier (UUID) or the name of the VM. To apply the filter description to all VMs, specify
global
. - --vendorid= XXXX
-
Specifies a vendor ID filter, which is a string representation of a four-digit hexadecimal number. X is the hexadecimal digit including leading zeroes. The default value is an empty string (
""
).
Add a USB Filter or a Global Filter
Use the VBoxManage usbfilter add
command to
create a new USB filter.
In addition, specify parameters by which to filter. You can use
the VBoxManage list usbhost
command to view
the parameters for devices that are attached to your system.
Modify a USB Filter or a Global Filter
Use the VBoxManage usbfilter modify
command
to modify a USB filter. You can use the VBoxManage list
usbfilters
command to list global filter indexes and
the VBoxManage showvminfo
command to list
indexes for a specific machine.
Examples
The following command lists the available USB devices on the host system.
$ VBoxManage list usbhost
The following command adds a USB filter called
filter01
to the ol7
VM.
The filter specifies a Kingston DataTraveler memory stick and is
placed first in the list of USB filters for the VM.
$ VBoxManage usbfilter add 0 --target ol7 --name filter01 --vendorid 0x0930 --productid 0x6545
The following command removes the USB filter that is second in the
list for the ol7
VM.
$ VBoxManage usbfilter remove 1 --target ol7
vboximg-mount
FUSE mount a virtual disk image for Mac OS and Linux hosts
Synopsis
Description
The vboximg-mount
command enables you to make
Oracle VM VirtualBox disk images available to a Mac OS or Linux host
operating system (OS) for privileged or non-priviliged access. You
can mount any version of the disk from its available history of
snapshots. Use this command to mount, view, and optionally modify
the contents of an Oracle VM VirtualBox virtual disk image, and you can
also use this command to view information about registered virtual
machines (VMs).
This command uses the Filesystem in Userspace (FUSE) technology to provide raw access to an Oracle VM VirtualBox virtual disk image.
When you use the --image option to specify a base image identifier, only the base image is mounted. Any related snapshots are disregarded. Alternatively, if you use the --image option to specify a snapshot, the state of the FUSE-mounted virtual disk is synthesized from the implied chain of snapshots, including the base image.
The vboximg-mount
command includes experimental
read-only access to file systems inside a VM disk image. This
feature enables you to extract some files from the VM disk image
without starting the VM and without requiring third-party file
system drivers on the host system. Oracle VM VirtualBox supports the
FAT, NTFS, ext2
, ext3
,
and ext4
file systems.
The virtual disk is exposed as a device node within a FUSE-based file system that overlays the specified mount point.
The FUSE file system includes a directory that contains a number
of files. The file system can also contain a directory that
includes a symbolic link that has the same base name (see the
basename
(1) man page) as the virtual disk base
image and points to the location of the virtual disk base image.
The directory can be of the following types:
-
vhdd
provides access to the raw disk image data as a flat image -
volID provides access to an individual volume on the specified disk image
-
fsID provides access to a supported file system without requiring a host file system driver
General Command Options
Use the following options to obtain information about the
vboximg-mount
command and its options.
- --help, --h, or--?
-
Shows usage information.
Mounting an Oracle VM VirtualBox Disk Image
Use the vboximg-mount
command to mount an
Oracle VM VirtualBox virtual disk image on a Mac OS or Linux host
system. When mounted, you can view the contents of the disk
image or modify the contents of the disk image.
You can use the vboximg-mount
command to
restrict FUSE-based access to a subsection of the virtual disk.
- --image= disk-image
-
Specifies the Universally Unique Identifier (UUID), name, or path of the Oracle VM VirtualBox disk image.
The short form of the --image option is -i.
- --guest-filesystem
-
Enables experimental read-only support for guest file systems. When you specify this option, all known file systems are made available to access.
The short form of the --guest-filesystem option is -g.
- -o= FUSE-option [, FUSE-option ...]
-
Specifies FUSE mount options.
The
vboximg-mount
command enables you to use the FUSE mount options that are described in themount.fuse
(8) man page. - --root
-
Overrides the security measure that restricts file access to the file system owner by also granting file access to the
root
user.Same as the -o allow_root option. See the -o option description.
This option is incompatible with the -o allow_other option.
- --rw
-
Mounts the specified image as read-write, which is required if you want to modify its contents. By default, images are mounted as read-only.
- mount-point
-
Specifies the path name of a directory on which to mount the Oracle VM VirtualBox disk image.
Viewing Oracle VM VirtualBox Disk Image Information
Use the vboximg-mount
command to view
information about registered VMs or an Oracle VM VirtualBox virtual
disk image.
- --image= disk-image
-
Specifies the UUID, name, or path of the Oracle VM VirtualBox disk image.
The short form of the --image option is -i.
- --guest-filesystem
-
Enables experimental read-only support for guest file systems. When you specify this option, all known file systems are made available to access.
The short form of the --guest-filesystem option is -g.
- --list
-
Shows information about the disks that are associated with the registered VMs. If you specify a disk image, this option shows information about the partitions of the specified image.
When you specify the --verbose option, the output includes detailed information about the VMs and media, including snapshot images and file paths.
The short form of the --list option is -l.
- --verbose
-
Shows or logs detailed information.
The short form of the --verbose option is -v.
- --vm= vm-UUID
-
Outputs information about the VM that is associated with the specified UUID.
- --wide
-
Outputs information in a wide format. This output includes the lock state information of running VMs. For VMs that are not running, the state is
created
.The wide output uses a tree-like structure in the VM column to show the relationship between a VM base image and its snapshots.
Examples
The following example shows how to mount a virtual disk image on the host operating system (OS).
$ mkdir fuse_mount_point $ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 fuse_mount_point $ ls fuse_mount_point ubu.vdi[32256:2053029880] vhdd $ sudo mount fuse_mount_point/vhdd /mnt
The mkdir
command creates a mount point called
fuse_mount_point
on the host OS. The
vboximg-mount
command is then used to mount the
specified disk image on the fuse_mount_point
mount point. The mount includes all snapshots for the disk image.
The ls
command shows the contents of
fuse_mount_point
. The
mount
command is then used to mount the
FUSE-mounted device node, vhdd
, on the
/mnt
mount point. The vhdd
device node represents the virtual disk image.
The following example shows how to make the known file systems of
the b490e578-08be-4f7d-98e9-4c0ef0952377
disk
image accessible when the image is mounted on the
fuse_mount_point
mount point:
$ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 \ --guest-filesystem fuse_mount_point
The following command outputs detailed information about all registered VMs and their snapshots:
$ vboximg-mount --list --verbose
The following command shows an excerpt of the list output in wide format.
$ vboximg-mount --list --wide VM Image Size Type State UUID (hierarchy) ------------------------------------------ ------------------------------------ Proxy 0833f5bc-6304-42e1-b799-cdc81c576c60 | +- Proxy.vdi 4.8G VDI rlock d5f84afb-0794-4952-ab71-6bbcbee07737 | +- <snapshot> 12.3G VDI rlock dffc67aa-3023-477f-8033-b27e3daf4f54 | +- <snapshot> 8.8G VDI rlock 3b2755bd-5f2a-4171-98fe-647d510b6274 | +- <snapshot> 14.6G VDI rlock e2ccdb5f-49e8-4123-8623-c61f363cc5cf | +- <snapshot> 7.4G VDI wlock 3c1e6794-9091-4be3-9e80-11aba40c2649 ------------------------------------------ ------------------------------------ Oracle Linux 7 5365ab5f-470d-44c0-9863-dad532ee5905 | +- Oracle Linux 7.vdi 7.0G VDI created 96d2e92e-0d4e-46ab-a0f1-008fdbf997e7 | +- <snapshot> 15.9G VDI created f9cc866a-9166-42e9-a503-bbfe9b7312e8 | +- kernel.vdi 11.1G VDI created 79a370bd-0c4f-480a-30bb-10cdea68423f
The output shows that the Proxy VM is running the fourth snapshot
of the Proxy.vdi
virtual disk image. The
running state is indicated by the wlock
value
in the State column.
The Oracle Linux 7 VM is not running. It has two images:
Oracle Linux 7.vdi
and
kernel.vdi
. The Oracle Linux
7.vdi
image has a snapshot.
The following command shows information about the VM with the specified UUID:
$ vboximg-mount --list --vm=b1d5563b-2a5b-4013-89f1-26c81d6bbfa0 ----------------------------------------------------------------- VM: ubu UUID: b1d5563b-2a5b-4013-89f1-26c81d6bbfa0 Image: ubu.vdi UUID: b490e578-08be-4f7d-98e9-4c0ef0952377 Snapshot: 35afe1e0-0a51-44f3-a228-caf172f3306f Size: 12.1G Snapshot: 874279c1-4425-4282-ada8-a9c07c00bbf9 Size: 13.6G Image: kernel.vdi UUID: 79a370bd-6eb7-4dbf-8bc6-d29118f127e0