Chapter 8. VBoxManage

Table of Contents

8.1. Introduction
8.2. Commands Overview
8.3. General Options
8.4. VBoxManage
8.5. VBoxManage list
8.6. VBoxManage showvminfo
8.7. VBoxManage registervm
8.8. VBoxManage unregistervm
8.9. VBoxManage createvm
8.10. VBoxManage modifyvm
8.11. VBoxManage clonevm
8.12. VBoxManage movevm
8.13. VBoxManage encryptvm
8.14. VBoxManage cloud
8.15. VBoxManage cloudprofile
8.16. VBoxManage import
8.17. VBoxManage export
8.18. VBoxManage signova
8.19. VBoxManage startvm
8.20. VBoxManage controlvm
8.21. VBoxManage unattended
8.22. VBoxManage discardstate
8.23. VBoxManage adoptstate
8.24. VBoxManage snapshot
8.25. VBoxManage closemedium
8.26. VBoxManage storageattach
8.27. VBoxManage storagectl
8.28. VBoxManage bandwidthctl
8.29. VBoxManage showmediuminfo
8.30. VBoxManage createmedium
8.31. VBoxManage modifymedium
8.32. VBoxManage clonemedium
8.33. VBoxManage mediumproperty
8.34. VBoxManage encryptmedium
8.35. VBoxManage checkmediumpwd
8.36. VBoxManage convertfromraw
8.37. VBoxManage mediumio
8.38. VBoxManage setextradata
8.39. VBoxManage getextradata
8.40. VBoxManage setproperty
8.41. VBoxManage usbfilter
8.42. VBoxManage sharedfolder
8.43. VBoxManage guestproperty
8.44. VBoxManage guestcontrol
8.45. VBoxManage debugvm
8.46. VBoxManage metrics
8.47. VBoxManage natnetwork
8.48. VBoxManage hostonlyif
8.49. VBoxManage hostonlynet
8.50. VBoxManage dhcpserver
8.51. VBoxManage usbdevsource
8.52. VBoxManage extpack
8.53. VBoxManage updatecheck
8.54. VBoxManage modifynvram
8.55. vboximg-mount

8.1. Introduction

As briefly mentioned in Section 1.18, “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 Chapter 8, 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
Copyright (C) 2005-2022 Oracle and/or its affiliates

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 Section 8.9, “VBoxManage createvm”.
To show the configuration of a particular VM, use VBoxManage showvminfo. See Section 8.6, “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 Section 8.10, “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 Section 8.27, “VBoxManage storagectl” and Section 8.26, “VBoxManage storageattach”.
To control VM operation, use one of the following:
- To start a VM that is currently powered off, use VBoxManage startvm. See Section 8.19, “VBoxManage startvm”.
- To pause or save a VM that is currently running or change some of its settings, use VBoxManage controlvm. See Section 8.20, “VBoxManage controlvm”.

8.2. 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.

VBoxManage [ -V | --version ] [--dump-build-type] [ -q | --nologo ] [--settingspw=password] [--settingspwfile=pw-file] [@response-file] [[help]subcommand]

VBoxManage showvminfo < uuid | vmname > [--details] [--machinereadable] [--password-id] [--password]

VBoxManage showvminfo < uuid | vmname > <--log=index> [--password-id id] [--password file|-]

VBoxManage registervm <filename> --password file

VBoxManage unregistervm < uuid | vmname > [--delete]

VBoxManage createvm <--name=name> [--basefolder=basefolder] [--default] [--group=group-ID,...] [--ostype=ostype] [--register] [--uuid=uuid] [--cipher cipher] [--password-id password-id] [--password file]

VBoxManage modifyvm < uuid | vmname > [--nat-netN= network | default ] [--nat-pfN= [rule-name],tcp | udp,[host-IP],hostport,[guest-IP],guestport ] [--nat-pfN=delete=rule-name] [--nat-tftp-prefixN=prefix] [--nat-tftp-fileN=filename] [--nat-tftp-serverN=IP-address] [--nat-bind-ipN=IP-address] [--nat-dns-pass-domainN= on | off ] [--nat-dns-proxyN= on | off ] [--nat-dns-host-resolverN= on | off ] [--nat-localhostreachableN= on | off ] [--nat-settingsN=[mtu],[socksnd],[sockrcv],[tcpsnd],[tcprcv]] [--nat-alias-modeN= default | [log],[proxyonly],[sameports] ]

VBoxManage modifyvm < uuid | vmname > [--recording= on | off ] [--recording-screens= all | none | screen-ID[,screen-ID...] ] [--recording-file=filename] [--recording-max-size=MB] [--recording-max-time=msec] [--recording-opts= key=value[,key=value...] ] [--recording-video-fps=fps] [--recording-video-rate=rate] [--recording-video-res=widthheight]

VBoxManage modifyvm < uuid | vmname > [--vrde= on | off ] [--vrde-property=property-name= [property-value]] [--vrde-extpack= default | name ] [--vrde-port=port] [--vrde-address=hostip] [--vrde-auth-type= null | external | guest ] [--vrde-auth-library= default | name ] [--vrde-multi-con= on | off ] [--vrde-reuse-con= on | off ] [--vrde-video-channel= on | off ] [--vrde-video-channel-quality=percent]

VBoxManage modifyvm < uuid | vmname > [--teleporter= on | off ] [--teleporter-port=port] [--teleporter-address= address | empty ] [--teleporter-password=password] [--teleporter-password-file= filename | stdin ] [--cpuid-portability-level=level] [--cpuid-set=leaf [:subleaf]eax ebx ecx edx] [--cpuid-remove=leaf [:subleaf]] [--cpuid-remove-all]

VBoxManage modifyvm < uuid | vmname > [--tracing-enabled= on | off ] [--tracing-config=string] [--tracing-allow-vm-access= on | off ]

VBoxManage modifyvm < uuid | vmname > [--usb-card-reader= on | off ]

VBoxManage modifyvm < uuid | vmname > [--autostart-enabled= on | off ] [--autostart-delay=seconds]

VBoxManage modifyvm < uuid | vmname > [--pci-attach=host-PCI-address [@guest-PCI-bus-address]] [--pci-detach=host-PCI-address]

VBoxManage modifyvm < uuid | vmname > [--testing-enabled= on | off ] [--testing-mmio= on | off ] [--testing-cfg-dwordidx=value]

VBoxManage clonevm <vmname|uuid> [--basefolder=basefolder] [--groups=group,...] [ --mode=machine | --mode=machinechildren | --mode=all ] [--name=name] [--options=option,...] [--register] [--snapshot=snapshot-name] [--uuid=uuid]

VBoxManage movevm < uuid | vmname > [--type=basic] [--folder=folder-name]

VBoxManage encryptvm < uuid | vmname > setencryption --old-password file --cipher cipher-identifier --new-password file --new-password-id password-identifier --force

VBoxManage encryptvm < uuid | vmname > checkpassword <file>

VBoxManage encryptvm < uuid | vmname > addpassword --password file --password-id password-identifier

VBoxManage encryptvm < uuid | vmname > removepassword <password-identifier>

VBoxManage cloud <--provider=name> <--profile=name>
list instances [--state=string] [--compartment-id=string]

VBoxManage cloud <--provider=name> <--profile=name>
list images <--compartment-id=string> [--state=string]

VBoxManage cloud <--provider=name> <--profile=name>
instance create <--domain-name=name> <<--image-id=id> | <--boot-volume-id=id>> <--display-name=name> <--shape=type> <--subnet=id> [--boot-disk-size=size in GB] [--publicip=true/false] [--privateip=IP address] [--public-ssh-key=key string...] [--launch-mode=NATIVE/EMULATED/PARAVIRTUALIZED] [--cloud-init-script-path=path to a script]

VBoxManage cloud <--provider=name> <--profile=name>
instance info <--id=unique id>

VBoxManage cloud <--provider=name> <--profile=name>
instance terminate <--id=unique id>

VBoxManage cloud <--provider=name> <--profile=name>
instance start <--id=unique id>

VBoxManage cloud <--provider=name> <--profile=name>
instance pause <--id=unique id>

VBoxManage cloud <--provider=name> <--profile=name>
image create <--display-name=name> [--bucket-name=name] [--object-name=name] [--instance-id=unique id]

VBoxManage cloud <--provider=name> <--profile=name>
image info <--id=unique id>

VBoxManage cloud <--provider=name> <--profile=name>
image delete <--id=unique id>

VBoxManage cloud <--provider=name> <--profile=name>
image import <--id=unique id> [--bucket-name=name] [--object-name=name]

VBoxManage cloud <--provider=name> <--profile=name>
image export <--id=unique id> <--display-name=name> [--bucket-name=name] [--object-name=name]

VBoxManage cloud <--provider=name> <--profile=name>
network setup [--gateway-os-name=string] [--gateway-os-version=string] [--gateway-shape=string] [--tunnel-network-name=string] [--tunnel-network-range=string] [--proxy=string] [--compartment-id=string]

VBoxManage cloud <--provider=name> <--profile=name>
network create <--name=string> <--network-id=string> [ --enable | --disable ]

VBoxManage cloud network update <--name=string> [--network-id=string] [ --enable | --disable ]

VBoxManage cloud network delete <--name=string>

VBoxManage cloud network info <--name=string>

VBoxManage cloudprofile <--provider=name> <--profile=name> add [--clouduser=unique id] [--fingerprint=MD5 string] [--keyfile=path] [--passphrase=string] [--tenancy=unique id] [--compartment=unique id] [--region=string]

VBoxManage cloudprofile <--provider=name> <--profile=name> update [--clouduser=unique id] [--fingerprint=MD5 string] [--keyfile=path] [--passphrase=string] [--tenancy=unique id] [--compartment=unique id] [--region=string]

VBoxManage cloudprofile <--provider=name> <--profile=name> delete

VBoxManage cloudprofile <--provider=name> <--profile=name> show

VBoxManage import < ovfname | ovaname > [--dry-run] [--options= keepallmacs | keepnatmacs | importtovdi ] [--vsys=n] [--ostype=ostype] [--vmname=name] [--settingsfile=file] [--basefolder=folder] [--group=group] [--memory=MB] [--cpus=n] [--description=text] [--eula= show | accept ] [--unit=n] [--ignore] [--scsitype= BusLogic | LsiLogic ] [--disk=path] [--controller=index] [--port=n]

VBoxManage import OCI:// --cloud [--ostype=ostype] [--vmname=name] [--basefolder=folder] [--memory=MB] [--cpus=n] [--description=text] <--cloudprofile=profile> <--cloudinstanceid=id> [--cloudbucket=bucket]

VBoxManage export <machines> <--output=name> [ --legacy09 | --ovf09 | --ovf10 | --ovf20 ] [--manifest] [--options= manifest | iso | nomacs | nomacsbutnat ... ] [--vsys=virtual-system-number] [--description=description-info] [--eula=license-text] [--eulafile=filename] [--product=product-name] [--producturl=product-URL] [--vendor=vendor-name] [--vendorurl=vendor-URL] [--version=version-info] [--vmname=vmname]

VBoxManage export <machine> <--output=cloud-service-provider> [--opc10] [--vmname=vmname] [--cloud=virtual-system-number] [--cloudprofile=cloud-profile-name] [--cloudshape=cloud-shape-name] [--clouddomain=cloud-domain] [--clouddisksize=disk-size-in-GB] [--cloudbucket=bucket-name] [--cloudocivcn=OCI-VCN-ID] [--cloudocisubnet=OCI-subnet-ID] [--cloudkeepobject= true | false ] [--cloudlaunchinstance= true | false ] [--cloudlaunchmode= EMULATED | PARAVIRTUALIZED ] [--cloudpublicip= true | false ]

VBoxManage signova <ova> <--certificate=file> <--private-key=file> [ --private-key-password-file=password-file | --private-key-password=password ] [--digest-type=type] [ --pkcs7 | --no-pkcs7 ] [--intermediate-cert=file] [--force] [--verbose] [--quiet] [--dry-run]

VBoxManage startvm < uuid | vmname ...> [--putenv=name[=value]] [--type= [ gui | headless | sdl | separate ]] --password file --password-id password identifier

VBoxManage controlvm < uuid | vmname > pause

VBoxManage controlvm < uuid | vmname > resume

VBoxManage controlvm < uuid | vmname > reset

VBoxManage controlvm < uuid | vmname > poweroff

VBoxManage controlvm < uuid | vmname > savestate

VBoxManage controlvm < uuid | vmname > acpipowerbutton

VBoxManage controlvm < uuid | vmname > acpisleepbutton

VBoxManage controlvm < uuid | vmname > reboot

VBoxManage controlvm < uuid | vmname > shutdown [--force]

VBoxManage controlvm < uuid | vmname > keyboardputscancode <hex> [hex...]

VBoxManage controlvm < uuid | vmname > keyboardputstring <string> [string...]

VBoxManage controlvm < uuid | vmname > keyboardputfile <filename>

VBoxManage controlvm < uuid | vmname > setlinkstateN < on | off >

VBoxManage controlvm < uuid | vmname > nictraceN < on | off >

VBoxManage controlvm < uuid | vmname > nictracefileN <filename>

VBoxManage controlvm < uuid | vmname > nicpropertyN <prop-name=prop-value>

VBoxManage controlvm < uuid | vmname > nicpromiscN < deny | allow-vms | allow-all >

VBoxManage controlvm < uuid | vmname > natpfN < [rulename] ,tcp | udp, [host-IP], hostport, [guest-IP], guestport >

VBoxManage controlvm < uuid | vmname > natpfN delete <rulename>

VBoxManage controlvm < uuid | vmname > guestmemoryballoon <balloon-size>

VBoxManage controlvm < uuid | vmname > usbattach < uuid | address > [--capturefile=filename]

VBoxManage controlvm < uuid | vmname > usbdetach < uuid | address >

VBoxManage controlvm < uuid | vmname > audioin < on | off >

VBoxManage controlvm < uuid | vmname > audioout < on | off >

VBoxManage controlvm < uuid | vmname > clipboard mode < disabled | hosttoguest | guesttohost | bidirectional >

VBoxManage controlvm < uuid | vmname > clipboard filetransfers < on | off >

VBoxManage controlvm < uuid | vmname > draganddrop < disabled | hosttoguest | guesttohost | bidirectional >

VBoxManage controlvm < uuid | vmname > vrde < on | off >

VBoxManage controlvm < uuid | vmname > vrdeport <port>

VBoxManage controlvm < uuid | vmname > vrdeproperty <prop-name=prop-value>

VBoxManage controlvm < uuid | vmname > vrdevideochannelquality <percentage>

VBoxManage controlvm < uuid | vmname > setvideomodehint <xres> <yres> <bpp> [[display] [ enabled:yes | no | [x-origin y-origin]]]

VBoxManage controlvm < uuid | vmname > setscreenlayout <display> < on | primary x-origin y-origin x-resolution y-resolution bpp | off >

VBoxManage controlvm < uuid | vmname > screenshotpng <filename> [display]

VBoxManage controlvm < uuid | vmname > recording < on | off >

VBoxManage controlvm < uuid | vmname > recording screens < all | none | screen-ID[,screen-ID...] >

VBoxManage controlvm < uuid | vmname > recording filename <filename>

VBoxManage controlvm < uuid | vmname > recording videores <widthxheight>

VBoxManage controlvm < uuid | vmname > recording videorate <rate>

VBoxManage controlvm < uuid | vmname > recording videofps <fps>

VBoxManage controlvm < uuid | vmname > recording maxtime <sec>

VBoxManage controlvm < uuid | vmname > recording maxfilesize <MB>

VBoxManage controlvm < uuid | vmname > setcredentials <username> --passwordfile= < filename | password > <domain-name> --allowlocallogon= < yes | no >

VBoxManage controlvm < uuid | vmname > teleport <--host=host-name> <--port=port-name> [--maxdowntime=msec] [ --passwordfile=filename | --password=password ]

VBoxManage controlvm < uuid | vmname > plugcpu <ID>

VBoxManage controlvm < uuid | vmname > unplugcpu <ID>

VBoxManage controlvm < uuid | vmname > cpuexecutioncap <num>

VBoxManage controlvm < uuid | vmname > webcam attach [pathname [settings]]

VBoxManage controlvm < uuid | vmname > webcam detach [pathname]

VBoxManage controlvm < uuid | vmname > webcam list

VBoxManage controlvm < uuid | vmname > addencpassword <ID> < password-file | - > [--removeonsuspend= yes | no ]

VBoxManage controlvm < uuid | vmname > removeencpassword <ID>

VBoxManage controlvm < uuid | vmname > removeallencpasswords

VBoxManage controlvm < uuid | vmname > autostart-enabledN on | off

VBoxManage controlvm < uuid | vmname > autostart-delayseconds

VBoxManage unattended detect <--iso=install-iso> [--machine-readable]

VBoxManage unattended install <uuid|vmname> <--iso=install-iso> [--user=login] [--password=password] [--password-file=file] [--full-user-name=name] [--key=product-key] [--install-additions] [--no-install-additions] [--additions-iso=add-iso] [--install-txs] [--no-install-txs] [--validation-kit-iso=testing-iso] [--locale=ll_CC] [--country=CC] [--time-zone=tz] [--hostname=fqdn] [--package-selection-adjustment=keyword] [--dry-run] [--auxiliary-base-path=path] [--image-index=number] [--script-template=file] [--post-install-template=file] [--post-install-command=command] [--extra-install-kernel-parameters=params] [--language=lang] [--start-vm=session-type]

VBoxManage discardstate < uuid | vmname >

VBoxManage adoptstate < uuid | vmname > <state-filename>

VBoxManage snapshot <uuid|vmname>

VBoxManage snapshot <uuid|vmname> take <snapshot-name> [--description=description] [--live] [--uniquename Number,Timestamp,Space,Force]

VBoxManage snapshot <uuid|vmname> delete <snapshot-name>

VBoxManage snapshot <uuid|vmname> restore <snapshot-name>

VBoxManage snapshot <uuid|vmname> restorecurrent

VBoxManage snapshot <uuid|vmname> edit < snapshot-name | --current > [--description=description] [--name=new-name]

VBoxManage snapshot <uuid|vmname> list [[--details] | [--machinereadable]]

VBoxManage snapshot <uuid|vmname> showvminfo <snapshot-name>

VBoxManage closemedium [ disk | dvd | floppy ] < uuid | filename > [--delete]

VBoxManage bandwidthctl < uuid | vmname > add <bandwidth-group-name> <--limit=bandwidth-limit[k|m|g|K|M|G]> <--type=disk|network>

VBoxManage bandwidthctl < uuid | vmname > list [--machinereadable]

VBoxManage bandwidthctl < uuid | vmname > remove <bandwidth-group-name>

VBoxManage bandwidthctl < uuid | vmname > set <bandwidth-group-name> <--limit=bandwidth-limit[k|m|g|K|M|G]>

VBoxManage showmediuminfo [ disk | dvd | floppy ] < uuid | filename >

VBoxManage createmedium [ disk | dvd | floppy ] <--filename=filename> [ --size=megabytes | --sizebyte=bytes ] [--diffparent= UUID | filename ] [--format= VDI | VMDK | VHD ] [--variant Standard,Fixed,Split2G,Stream,ESX,Formatted,RawDisk] --property name=value... --property-file name=/path/to/file/with/value...

VBoxManage mediumproperty [ disk | dvd | floppy ] set < uuid | filename > <property-name> <property-value>

VBoxManage mediumproperty [ disk | dvd | floppy ] get < uuid | filename > <property-name>

VBoxManage mediumproperty [ disk | dvd | floppy ] delete < uuid | filename > <property-name>

VBoxManage encryptmedium < uuid | filename > [--cipher=cipher-ID] [--newpassword=password] [--newpasswordid=password-ID] [--oldpassword=password]

VBoxManage checkmediumpwd < uuid | filename > <password-file>

VBoxManage convertfromraw <inputfile> <outputfile> [--format= VDI | VMDK | VHD ] [--uuid=uuid] [--variant=Standard,Fixed,Split2G,Stream,ESX]

VBoxManage convertfromraw stdin <outputfile> [--format= VDI | VMDK | VHD ] [--uuid=uuid] [--variant=Standard,Fixed,Split2G,Stream,ESX]

VBoxManage setextradata < global | uuid | vmname > <keyword> [value]

VBoxManage getextradata < global | uuid | vmname > <keyword> | [enumerate]

VBoxManage setproperty <property-name> <property-value>

VBoxManage usbfilter add <index,0-N> <--target= < uuid | vmname | global >> <--name=string> <--action=ignore | hold> [--active=yes | no] [--vendorid=XXXX] [--productid=XXXX] [--revision=IIFF] [--manufacturer=string] [--product=string] [--remote=yes | no] [--serialnumber=string] [--maskedinterfaces=XXXXXXXX]

VBoxManage usbfilter remove <index,0-N> <--target= < uuid | vmname | global >>

VBoxManage sharedfolder add < uuid | vmname > <--name=name> <--hostpath=hostpath> [--readonly] [--transient] [--automount] [--auto-mount-point=path]

VBoxManage sharedfolder remove < uuid | vmname > <--name=name> [--transient]

VBoxManage guestproperty get < uuid | vmname > <property-name> [--verbose]

VBoxManage guestproperty enumerate < uuid | vmname > [--no-timestamp] [--no-flags] [--relative] [--old-format] [patterns...]

VBoxManage guestproperty set < uuid | vmname > <property-name> [property-value [--flags=flags]]

VBoxManage guestproperty unset < uuid | vmname > <property-name>

VBoxManage guestproperty wait < uuid | vmname > <patterns> [--timeout=msec] [--fail-on-timeout]

VBoxManage guestcontrol < uuid | vmname > run [--domain=domainname] [--dos2unix] [--exe=filename] [--ignore-orphaned-processes] [ --no-wait-stderr | --wait-stderr ] [ --no-wait-stdout | --wait-stdout ] [ --passwordfile=password-file | --password=password ] [--profile] [--putenv=var-name=[value]] [--quiet] [--timeout=msec] [--unix2dos] [--unquoted-args] [--username=username] [--verbose] <-- program/arg0 [argument...]>

VBoxManage guestcontrol < uuid | vmname > start [--domain=domainname] [--exe=filename] [--ignore-orphaned-processes] [ --passwordfile=password-file | --password=password ] [--profile] [--putenv=var-name=[value]] [--quiet] [--timeout=msec] [--unquoted-args] [--username=username] [--verbose] <-- program/arg0 [argument...]>

VBoxManage guestcontrol < uuid | vmname > copyfrom [--domain=domainname] [--follow] [ --passwordfile=password-file | --password=password ] [--quiet] [--recursive] [--username=username] [--verbose] <guest-source0> guest-source1 [...] <host-destination>

VBoxManage guestcontrol < uuid | vmname > copyfrom [--domain=domainname] [--follow] [ --passwordfile=password-file | --password=password ] [--quiet] [--recursive] [--target-directory=host-destination-dir] [--username=username] [--verbose] <guest-source0> guest-source1 [...]

VBoxManage guestcontrol < uuid | vmname > copyto [--domain=domainname] [--follow] [ --passwordfile=password-file | --password=password ] [--quiet] [--recursive] [--username=username] [--verbose] <host-source0> host-source1 [...] <guest-destination>

VBoxManage guestcontrol < uuid | vmname > copyto [--domain=domainname] [--follow] [ --passwordfile=password-file | --password=password ] [--quiet] [--recursive] [--target-directory=guest-destination-dir] [--username=username] [--verbose] <host-source0> host-source1 [...]

VBoxManage guestcontrol < uuid | vmname > mkdir [--domain=domainname] [--mode=mode] [--parents] [ --passwordfile=password-file | --password=password ] [--quiet] [--username=username] [--verbose] <guest-directory...>

VBoxManage guestcontrol < uuid | vmname > rmdir [--domain=domainname] [ --passwordfile=password-file | --password=password ] [--quiet] [--recursive] [--username=username] [--verbose] <guest-directory...>

VBoxManage guestcontrol < uuid | vmname > rm [--domain=domainname] [--force] [ --passwordfile=password-file | --password=password ] [--quiet] [--username=username] [--verbose] <guest-directory...>

VBoxManage guestcontrol < uuid | vmname > mv [--domain=domainname] [ --passwordfile=password-file | --password=password ] [--quiet] [--username=username] [--verbose] <source...> <destination-directory>

VBoxManage guestcontrol < uuid | vmname > mktemp [--domain=domainname] [--mode=mode] [ --passwordfile=password-file | --password=password ] [--quiet] [--secure] [--tmpdir=directory-name] [--username=username] [--verbose] <template-name>

VBoxManage guestcontrol < uuid | vmname > stat [--domain=domainname] [ --passwordfile=password-file | --password=password ] [--quiet] [--username=username] [--verbose] <filename>

VBoxManage guestcontrol < uuid | vmname > list < all | files | processes | sessions > [--quiet] [--verbose]

VBoxManage guestcontrol < uuid | vmname > closeprocess [ --session-id=ID | --session-name=name-or-pattern ] [--quiet] [--verbose] <PID...>

VBoxManage guestcontrol < uuid | vmname > closesession [ --all | --session-id=ID | --session-name=name-or-pattern ] [--quiet] [--verbose]

VBoxManage guestcontrol < uuid | vmname > updatega [--quiet] [--verbose] [--source=guest-additions.ISO] [--wait-start] [-- [argument...]]

VBoxManage guestcontrol < uuid | vmname > watch [--quiet] [--verbose]

VBoxManage debugvm <uuid|vmname> dumpvmcore [--filename=name]

VBoxManage debugvm <uuid|vmname> info <item> [args...]

VBoxManage debugvm <uuid|vmname> injectnmi

VBoxManage debugvm <uuid|vmname> log [[--release] | [--debug]] [group-settings...]

VBoxManage debugvm <uuid|vmname> logdest [[--release] | [--debug]] [destinations...]

VBoxManage debugvm <uuid|vmname> logflags [[--release] | [--debug]] [flags...]

VBoxManage debugvm <uuid|vmname> osdetect

VBoxManage debugvm <uuid|vmname> osinfo

VBoxManage debugvm <uuid|vmname> osdmesg [--lines=lines]

VBoxManage debugvm <uuid|vmname> getregisters [--cpu=id] [reg-set.reg-name...]

VBoxManage debugvm <uuid|vmname> setregisters [--cpu=id] [reg-set.reg-name=value...]

VBoxManage debugvm <uuid|vmname> show [[--human-readable] | [--sh-export] | [--sh-eval] | [--cmd-set]] [settings-item...]

VBoxManage debugvm <uuid|vmname> stack [--cpu=id]

VBoxManage debugvm <uuid|vmname> statistics [--reset] [--descriptions] [--pattern=pattern]

VBoxManage debugvm <uuid|vmname> guestsample [--filename=filename] [--sample-interval-us=interval] [--sample-time-us=time]

VBoxManage metrics collect [--detach] [--list] [--period=seconds] [--samples=count] [ * | host | vmname [metric-list] ]

VBoxManage metrics disable [--list] [ * | host | vmname [metric-list] ]

VBoxManage metrics enable [--list] [ * | host | vmname [metric-list] ]

VBoxManage metrics list [ * | host | vmname [metric-list] ]

VBoxManage metrics query [ * | host | vmname [metric-list] ]

VBoxManage metrics setup [--list] [--period seconds] [--samples count] [ * | host | vmname [metric-list] ]

VBoxManage natnetwork add [ --disable | --enable ] <--netname=name> <--network=network> [--dhcp=on|off] [--ipv6=on|off] [--loopback-4=rule] [--loopback-6=rule] [--port-forward-4=rule] [--port-forward-6=rule]

VBoxManage natnetwork list [filter-pattern]

VBoxManage natnetwork modify [--dhcp=on|off] [ --disable | --enable ] <--netname=name> <--network=network> [--ipv6=on|off] [--loopback-4=rule] [--loopback-6=rule] [--port-forward-4=rule] [--port-forward-6=rule]

VBoxManage natnetwork remove <--netname=name>

VBoxManage natnetwork start <--netname=name>

VBoxManage natnetwork stop <--netname=name>

VBoxManage hostonlyif ipconfig <ifname> [ --dhcp | --ip=IPv4-address [--netmask=IPv4-netmask] | --ipv6=IPv6-address [--netmasklengthv6=length] ]

VBoxManage hostonlyif create

VBoxManage hostonlyif remove <ifname>

VBoxManage hostonlynet add <--name=netname> [--id=netid] <--netmask=mask> <--lower-ip=address> <--upper-ip=address> [ --enable | --disable ]

VBoxManage hostonlynet modify < --name=netname | --id=netid > [--lower-ip=address] [--upper-ip=address] [--netmask=mask] [ --enable | --disable ]

VBoxManage hostonlynet remove < --name=netname | --id=netid >

VBoxManage dhcpserver remove < --network=netname | --interface=ifname >

VBoxManage dhcpserver start < --network=netname | --interface=ifname >

VBoxManage dhcpserver restart < --network=netname | --interface=ifname >

VBoxManage dhcpserver stop < --network=netname | --interface=ifname >

VBoxManage dhcpserver findlease < --network=netname | --interface=ifname > <--mac-address=mac>

VBoxManage usbdevsource add <source-name> <--backend=backend> <--address=address>

VBoxManage usbdevsource remove <source-name>

VBoxManage extpack install [--replace] [--accept-license=sha256] <tarball>

VBoxManage extpack uninstall [--force] <name>

VBoxManage extpack cleanup

VBoxManage updatecheck perform [--machine-readable]

VBoxManage updatecheck list [--machine-readable]

VBoxManage updatecheck modify [ --disable | --enable ] [--channel=stable | withbetas | all] [--frequency=days]

VBoxManage modifynvram <uuid|vmname> inituefivarstore

VBoxManage modifynvram <uuid|vmname> enrollmssignatures

VBoxManage modifynvram <uuid|vmname> enrollorclpk

VBoxManage modifynvram <uuid|vmname> enrollpk [--platform-key=filename] [--owner-uuid=uuid]

VBoxManage modifynvram <uuid|vmname> listvars

VBoxManage modifynvram <uuid|vmname> queryvar [--name=name] [--filename=filename]

VBoxManage modifynvram <uuid|vmname> deletevar [--name=name] [--owner-uuid=uuid]

VBoxManage modifynvram <uuid|vmname> changevar [--name=name] [--filename=filename]

Each time VBoxManage is invoked, only one command can be executed. However, a command might support several subcommands which then can be invoked in one single call. The following sections provide detailed reference information on the different commands.

8.3. 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: Specifiy 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 Section 8.26, “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.

8.4. VBoxManage

Oracle VM VirtualBox command-line interface.

Synopsis

VBoxManage [ -V | --version ] [--dump-build-type] [ -q | --nologo ] [--settingspw=password] [--settingspwfile=pw-file] [@response-file] [[help]subcommand]

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 as controlvm, createvm, list, modifyvm, showvminfo, startvm, storageattach, and storagectl.

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

8.5. 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

VBoxManage list bridgedifs

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 Chapter 6, Virtual Networking.

List the Cloud Network Interfaces

VBoxManage list cloudnets

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

VBoxManage list cloudprofiles

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

VBoxManage list cloudproviders

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

VBoxManage list 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

VBoxManage list dhcpservers

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 Chapter 6, Virtual Networking.

List the DVD Virtual Disk Images

VBoxManage list dvds

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 Section 5.3, “The Virtual Media Manager”.

List the Installed Oracle VM VirtualBox Extension Packs

VBoxManage list extpacks

The VBoxManage list extpacks command shows all Oracle VM VirtualBox extension packs that are currently installed. See Section 1.5, “Installing Oracle VM VirtualBox and Extension Packs” and Section 8.52, “VBoxManage extpack”.

List the Floppy Disk Virtual Disk Images

VBoxManage list floppies

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 Section 5.3, “The Virtual Media Manager”.

List the Virtual Machine Groups

VBoxManage list groups

The VBoxManage list groups command shows all VM groups. See Section 1.10, “Using VM Groups”.

List the Virtual Disk Backends

VBoxManage list hddbackends

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

VBoxManage list hdds

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 Section 5.3, “The Virtual Media Manager”.

List the CPUID Information for the Host System CPUs

VBoxManage list hostcpuids

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

VBoxManage list hostdrives

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

VBoxManage list hostdvds

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

VBoxManage list hostfloppies

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

VBoxManage list hostinfo

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

VBoxManage list hostonlyifs

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 Chapter 6, Virtual Networking.

List Host-Only Networks

VBoxManage list hostonlynets

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 Chapter 6, Virtual Networking.

List Internal Networks

VBoxManage list intnets

The VBoxManage list intnets command shows information about the internal networks. See Chapter 6, Virtual Networking.

List the NAT Network Interfaces on the Host System

VBoxManage list natnets

The VBoxManage list natnets command lists the NAT network interfaces that are currently available on the host system. See Chapter 6, Virtual Networking.

List the Guest Operating Systems

VBoxManage list ostypes

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

VBoxManage list runningvms

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

VBoxManage list screenshotformats

The VBoxManage list screenshotformats command shows the list of available screen shot formats.

List System Properties

VBoxManage list systemproperties

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

VBoxManage list usbfilters

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

VBoxManage list usbhost

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

VBoxManage list vms

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

VBoxManage list webcams

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.

Examples

The following command lists the VM groups configured for Oracle VM VirtualBox.

$ VBoxManage list groups
"/Linux-VMs"
"/Windows-VMs"

The following command lists the VMs that are currently running.

$ VBoxManage list runningvms
"ol7" {ol7-UUID}
"win8" {win8-UUID}

8.6. VBoxManage showvminfo

Show configuration information or log file contents for a virtual machine.

Synopsis

VBoxManage showvminfo < uuid | vmname > [--details] [--machinereadable] [--password-id] [--password]

VBoxManage showvminfo < uuid | vmname > <--log=index> [--password-id id] [--password file|-]

Description

The VBoxManage showvminfo command outputs configuration information or log file contents for a specified virtual machine (VM).

Viewing Virtual Machine Information

VBoxManage showvminfo < uuid | vmname > [--details] [--machinereadable] [--password-id] [--password]

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

VBoxManage showvminfo < uuid | vmname > <--log=index> [--password-id id] [--password file|-]

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 the VBox.log file. An index value of 1 indicates the VBoxHardening.log file. Index values starting at 2 indicate other log files, such as the VBox.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-2022 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
...

8.7. VBoxManage registervm

Synopsis

VBoxManage registervm <filename> --password file

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.

Examples

The following command registers a VM called vm2. The XML machine configuration file for the VM is located in the default machines folder.

$ VBoxManage registervm "/home/user/VirtualBox VMs/vm2/vm2.vbox"

8.8. VBoxManage unregistervm

Unregister a virtual machine.

Synopsis

VBoxManage unregistervm < uuid | vmname > [--delete]

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.

Examples

The following command unregisters a VM called vm2.

$ VBoxManage unregistervm vm2

The following command unregisters a VM called vm3. All files associated with the VM are deleted.

$ VBoxManage unregistervm vm3 --delete
%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

8.9. VBoxManage createvm

Create a new virtual machine.

Synopsis

Description

The VBoxManage createvm command creates a new XML virtual machine (VM) definition file.

You must specify the name of the VM by using --name name. This name is used by default as the name of the settings file that has the .vbox extension and the machine folder, which is a subfolder of the $HOME/VirtualBox VMs directory.

The actual file name may not correspond directly to the VM name if it violates the host OS file name requirements (such as using the path separator or other reserved characters, they will be substituted with a placeholder). If you later rename the VM, the file and folder names will be updated to match the new name automatically.

Command Options

In addition to specifying the name or UUID of the VM, which is required, you can specify any of the following options:

--basefolder=basefolder

Specifies the name of the folder in which to save the machine configuration file for the new VM.

Note that the names of the file and the folder do not change if you rename the VM.

--default

Applies a default hardware configuration for the specified guest OS. By default, the VM is created with minimal hardware.

--group=group-ID,...

Assigns the VM to the specified groups. If you specify more than one group, separate each group name with a comma.

Note that each group is identified by a group ID that starts with a slash character (/) so that groups can be nested. By default, a VM is always assigned membership to the / group.

--ostype=ostype

Specifies the guest OS to run in the VM. Run the VBoxManage list 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 the VBoxManage 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 or AES-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.

Examples

The following command creates a VM called vm2 where you plan to run a 64-bit version of Oracle Linux.

$ VBoxManage createvm --name "vm2" --ostype "Oracle_64"

The following command creates and registers a VM called vm3.

$ VBoxManage createvm --name "vm3" --register

8.10. VBoxManage modifyvm

Change settings for a virtual machine that is stopped.

Synopsis

VBoxManage modifyvm < uuid | vmname > [--tracing-enabled= on | off ] [--tracing-config=string] [--tracing-allow-vm-access= on | off ]

VBoxManage modifyvm < uuid | vmname > [--usb-card-reader= on | off ]

VBoxManage modifyvm < uuid | vmname > [--autostart-enabled= on | off ] [--autostart-delay=seconds]

VBoxManage modifyvm < uuid | vmname > [--pci-attach=host-PCI-address [@guest-PCI-bus-address]] [--pci-detach=host-PCI-address]

VBoxManage modifyvm < uuid | vmname > [--testing-enabled= on | off ] [--testing-mmio= on | off ] [--testing-cfg-dwordidx=value]

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 Chapter 3, 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 Section 8.20, “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 Section 8.9, “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 Section 1.8, “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 Section 4.10.2, “Page Fusion”.

--vram=size

Specifies the amount of RAM to allocate to the virtual graphics card. See Section 3.6, “Display Settings”.

--acpi=on | off

Determines whether the VM has ACPI support. See Section 3.5.1, “Motherboard Tab”.

--ioapic=on | off

Determines whether the VM has I/O APIC support. See Section 3.5.1, “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 Section 3.5.2, “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 Section 9.4, “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 to 100. 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 Section 3.5.2, “Processor Tab”.

--long-mode=on | off

Enables or disables long mode. See Section 3.5.2, “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 Section 13.4.1, “CVE-2018-3646”.

--l1d-flush-on-vm-entry=on | off

Enables or disables level 1 data cache flushing on every VM entry. See Section 13.4.1, “CVE-2018-3646”.

--mds-clear-on-sched=on | off

Enables CPU buffer clearing when a thread is scheduled to execute guest code. See Section 13.4.2, “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 Section 13.4.2, “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, or 80386.

--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 Section 10.3, “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 Section 3.5.1, “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.

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 Section 10.5, “Paravirtualization Providers”.
hyperv is recommended for Windows guest VMs. See Section 10.5, “Paravirtualization Providers”.

--paravirt-debug=property=value

Specifies debugging properties that are specific to the paravirtualization provider configured for the specified VM. See Section 9.30, “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 Section 10.3, “Hardware Virtualization” and Section 13.4.1, “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 Section 10.3, “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 Section 9.34, “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. Section 9.34, “Nested Virtualization”.

--accelerated3d=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 Section 4.5.1, “Hardware 3D Acceleration (OpenGL and Direct3D 8/9)”.

--accelerated2dvideo=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 Section 4.5.2, “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 Section 3.5.1, “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, and disabled. When the value is disabled, neither the apic nor the x2apic 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 to apic, if supported. Otherwise, the APIC level downgrades to disabled. Similarly, if you specify the apic value and APIC is unsupported by the virtual CPU, the APIC level downgrades to disabled.

--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 Section 12.1.2, “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 is off to keep the content of the DMI/SMBIOS table unchanged, which can be important for Windows license activation.

--bootN=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, and net for a network device. A value of none 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 Section 3.5.1, “Motherboard Tab”.

--graphicscontroller=none | vboxvga | vmsvga | vboxsvga

Specifies the graphics controller type to use. See Section 3.6.1, “Screen Tab”.

--snapshot-folder=default | pathname

Specifies the name of the VM's snapshot storage folder. If you specify default, the folder name is Snapshots/ in the machine folder.

--firmware=bios | efi | efi32 | efi64

Specifies the firmware used to boot the VM. Valid values are: bios, efi, efi32, or efi64. 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 Section 4.10.1, “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 Section 8.19, “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.

Configures the network type used by each virtual network card in the VM.

The following valid values correspond to the modes described in Section 6.2, “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-typeN=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 Section 6.1, “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-connectedN=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-traceN=on | off

Enables or disables network tracing for the specified virtual network card.

--nic-trace-fileN=filename

Specifies the absolute path of the file in which to write trace log information. Use this option if network tracing is enabled.

--nic-propertyN=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 Section 6.8, “UDP Tunnel Networking”.

--nic-speedN=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-prioN=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 to 4. Priority 0, which is the default value, is the lowest priority. Priority 1 is the highest priority, and priorities 3 and 4 are lower.

This option has an effect only when using the Intel PXE boot ROM.

--nic-promiscN=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-groupN=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.

See Section 6.12, “Limiting Bandwidth for Network Input/Output”.

--bridge-adapterN=none | device-name

Specifies the host interface to use for the specified virtual network interface. See Section 6.5, “Bridged Networking”. Use this option only if you used the --nic option to enable bridged networking for the specified virtual network card.

--host-only-adapterN=none | device-name

Specifies which host-only networking interface to use for the specified virtual network interface. See Section 6.7, “Host-Only Networking”. Use this option only if you used the --nic option to enable host-only networking for the specified virtual network card.

--intnetN=network-name

Specifies the name of the internal network. See Section 6.6, “Internal Networking”. Use this option only if you used the --nic option to enable internal networking for the specified virtual network card.

--nat-networkN=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, not nat.

--nic-generic-drvN=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-addressN=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-netN=default | network

Specifies the IP address range to use for this network. See Section 9.8, “Fine Tuning the Oracle VM VirtualBox NAT Engine”. Use this option only if the networking type is nat, not natnetwork.

--nat-pfN=[name],tcp | udp,[host-IP],hostport,[guest-IP],guestport

Specifies the NAT port-forwarding rule to use. See Section 6.3.1, “Configuring Port Forwarding with NAT”.

--nat-pfN=delete name

Specifies the NAT port-forwarding rule to delete. See Section 6.3.1, “Configuring Port Forwarding with NAT”.

--nat-tftp-prefixN=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 Section 6.3.2, “PXE Booting with NAT” and Section 9.8.2, “Configuring the Boot Server (Next Server) of a NAT Network Interface”.

--nat-tftp-fileN=boot-file

Specifies the name of the TFT boot file. See Section 9.8.2, “Configuring the Boot Server (Next Server) of a NAT Network Interface”.

--nat-tftp-serverN=tftp-server

Specifies the address of the TFTP server from which to boot. See Section 9.8.2, “Configuring the Boot Server (Next Server) of a NAT Network Interface”.

--nat-bind-ipN=IP-address

Specifies an alternate IP address to which the NAT engine binds. See Section 9.8.3, “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-domainN=on | off

Specifies whether the built-in DHCP server passes the domain name for network name resolution.

--nat-dns-proxyN=on | off

Specifies whether the NAT engine is the proxy for all guest DNS requests to the host system's DNS servers. See Section 9.8.5, “Enabling DNS Proxy in NAT Mode”.

--nat-dns-host-resolverN=on | off

Specifies whether the NAT engine uses the host system's resolver mechanisms to handle DNS requests. See Section 9.8.5, “Enabling DNS Proxy in NAT Mode”.

--nat-localhostreachableN=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-settingsN=[mtu],[socksnd],[sockrcv],[tcpsnd],[tcprcv]

Specifies values for tuning NAT performance. See Section 9.8.3, “Tuning TCP/IP Buffers for NAT”.

--nat-alias-modeN=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 Section 9.8.7, “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 and usbmtscreenpluspad.

--keyboard=ps2 | usb

Specifies the mode of the keyboard to use in the VM. Valid values are: ps2 and usb.

--uartN=off | I/O-baseIRQ

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 Section 3.10, “Serial Ports”.

--uart-modeN=mode

Specifies how Oracle VM VirtualBox connects the specified virtual serial port to the host system that runs the VM. See Section 3.10, “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.
serverpipe-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.
clientpipe-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.
tcpserverport 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.
tcpclienthostname:port connects the virtual serial device to the TCP socket.
Note that the TCP socket must already exist.
filefilename 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-typeN=UART-type

Configures the UART type for the specified virtual serial port (N). Valid values are 16450, 16550A, and 16750. The default value is 16550A.

--lpt-modeN=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.

--lptN=I/O-baseIRQ

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=type

Specifies whether the VM has audio support, and if so, which type. Valid audio type values are: none, default, null, dsound, was, oss, alsa, pulse, and coreaudio.

Note that the audio types are dependent on the host operating system. Use the VBoxManage modifyvm command usage output to determine the supported audio types for your host system.

--audio-controller=controller-type

Specifies the audio controller to be used with the VM. Valid audio controller type values are: ac97, hda, and sb16.

--audio-codec=codec-type

Specifies the audio codec to be used with the VM. Valid audio codec type values are: stac9700, ad1980, stac9221, and sb16.

--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, and bidirectional. See Section 3.4, “General Settings”.

The clipboard 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, and bidirectional. See Section 4.4, “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 Section 3.6, “Display Settings”.

--usb-ohci=on | off

Enables or disables the VM's virtual USB 1.1 controller. See Section 3.11.1, “USB Settings”.

--usb-ehci=on | off

Enables or disables the VM's virtual USB 2.0 controller. See Section 3.11.1, “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 Section 3.11.1, “USB Settings”.

--usb-rename=old-namenew-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=widthxheight

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 or 0 value uses port 3389, 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 means on and 0 means off. See Section 7.1.9, “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 Section 7.1.9, “VRDP Video Redirection”.

--vrde-property=DownscaleProtection=value

Enables or disables the video downscale protection feature. Valid values are 1 to enable the feature and 0 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 Section 7.1.10, “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 Section 7.1.10, “VRDP Customization”.

--vrde-property=DisableUpstreamAudio=1

Disables the upstream audio VRDE server feature. To reenable the feature, assign an empty value. See Section 7.1.10, “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 Section 7.1.6, “RDP Encryption”.

--vrde-property=ServerCertificate=value

Specifies the absolute path to the server certificate. See Section 7.1.6, “RDP Encryption”.

--vrde-property=ServerPrivateKey=value

Specifies the absolute path to the server private key. See Section 7.1.6, “RDP Encryption”.

--vrde-property=CACertificate=value

Specifies the absolute path to the CA self-signed certificate. See Section 7.1.6, “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 Section 9.20, “Other Extension Packs”.

--vrde-port=default | port

port is the port or port range to which the VRDE server binds. The default or 0 value uses port 3389, 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, or 5012.

--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 Section 7.1.5, “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 Section 7.1.5, “RDP Authentication”.

--vrde-multi-con=on | off

Enables or disables the multiple connections VRDE server feature, if supported. See Section 7.1.7, “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 is off, 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 Section 7.1.9, “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 Section 7.1.9, “VRDP Video Redirection”.

Teleporting Settings

The following options enable you to configure a machine as a teleporting target. See Section 7.2, “Teleporting”.

--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 value 3 supresses most features. Values of 1 and 2 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

VBoxManage modifyvm < uuid | vmname > [--tracing-enabled= on | off ] [--tracing-config=string] [--tracing-allow-vm-access= on | off ]

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

VBoxManage modifyvm < uuid | vmname > [--usb-card-reader= on | off ]

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 Section 9.21, “Starting Virtual Machines During System Boot”.

VBoxManage modifyvm < uuid | vmname > [--autostart-enabled= on | off ] [--autostart-delay=seconds]

--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.

VBoxManage modifyvm < uuid | vmname > [--pci-attach=host-PCI-address [@guest-PCI-bus-address]] [--pci-detach=host-PCI-address]

--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.

VBoxManage modifyvm < uuid | vmname > [--testing-enabled= on | off ] [--testing-mmio= on | off ] [--testing-cfg-dwordidx=value]

--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-dwordidx=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).

Examples

The following command changes the description for the ol7 VM.

$ VBoxManage modifyvm ol7 --description "Oracle Linux 7 with UEK4"

The following command enables VirtualBox Remote Display Protocol (VRDP) support for the ol7 VM.

$ VBoxManage modifyvm ol7 --vrde on

8.11. 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 Section 8.7, “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"

8.12. VBoxManage movevm

Move a virtual machine to a new location on the host system.

Synopsis

VBoxManage movevm < uuid | vmname > [--type=basic] [--folder=folder-name]

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.

Examples

The following command moves the ol7 VM to a new location on the host system.

$ VBoxManage movevm ol7 --folder "/home/testuser/vms" --type basic
0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
Machine has been successfully moved into /home/testuser/vms

8.13. VBoxManage encryptvm

Change encryption and passwords of the VM.

Synopsis

VBoxManage encryptvm < uuid | vmname > setencryption --old-password file --cipher cipher-identifier --new-password file --new-password-id password-identifier --force

VBoxManage encryptvm < uuid | vmname > checkpassword <file>

VBoxManage encryptvm < uuid | vmname > addpassword --password file --password-id password-identifier

VBoxManage encryptvm < uuid | vmname > removepassword <password-identifier>

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

VBoxManage encryptvm < uuid | vmname > setencryption --old-password file --cipher cipher-identifier --new-password file --new-password-id password-identifier --force

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

VBoxManage encryptvm < uuid | vmname > checkpassword <file>

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

VBoxManage encryptvm < uuid | vmname > addpassword --password file --password-id password-identifier

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

VBoxManage encryptvm < uuid | vmname > removepassword <password-identifier>

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.

Examples

The following command encrypts the ol7 VM using AES-256 giving password via command prompt:

$ VBoxManage encryptvm ol7 setencryption --cipher=AES-256 --new-password - --new-password-id vmid

8.14. VBoxManage cloud

Manage the cloud entities.