9 VBoxManage

--mac-address=<address>
Set the configuration scope to the specified MAC address.
--group=<name>
Set the configuration scope to the specified group.

Options configuring the currently selected scope:

--set-opt=<dhcp-opt-no value>
Adds the specified DHCP option number (0-255) and value. The value format is option
specific (typically human readable) and will be validated by the API and the DHCP server.
--set-opt-hex=<dhcp-opt-no hexstring>
Adds the specified DHCP option number (0-255) and value. The option value is specified
as a raw series of hex bytes, optionally separated by colons. No validation is performed on
these by the API or the DHCP server, they will be pass as specified to the client.
--force-opt=<dhcp-opt-no>
Forces the specified DHCP option number (0-255) onto to be sent to the client whether it
requested it or not (provided the option is configured with a value at some level).
--suppress-opt=<dhcp-opt-no>
Prevents the specified DHCP option number (0-255) from being sent to the client when
present in this or a high configuration scope.
--min-lease-time=<seconds>
Sets the minimum lease time for the current scope in seconds. Zero means taking the value
from a higher option level or use default.
--default-lease-time=<seconds>
Sets the default lease time for the current scope in seconds. Zero means taking the value
from a higher option level or use default.
--max-lease-time=<seconds>
Sets the maximum lease time for the current scope in seconds. Zero means taking the value
from a higher option level or use default.
--fixed-address=<address>
Fixed address assignment for a --vm or --mac-address configuration scope. Any empty
address turns it back to dynamic address assignment.

Options configuring group membership conditions (excludes overrides includes):

--incl-mac=<address>
Include the specific MAC address in the group.
--excl-mac=<address>
Exclude the specific MAC address from the group.
--incl-mac-wild=<pattern>
Include the specific MAC address pattern in the group.
--excl-mac-wild=<pattern>
Exclude the specific MAC address pattern from the group.
--incl-vendor=<string>
Include the specific vendor class ID in the group.
--excl-vendor=<string>
Exclude the specific vendor class ID from the group.

315
 9 VBoxManage

--incl-vendor-wild=<pattern>
Include the specific vendor class ID pattern in the group.
--excl-vendor-wild=<pattern>
Exclude the specific vendor class ID pattern from the group.
--incl-user=<string>
Include the specific user class ID in the group.
--excl-user=<string>
Exclude the specific user class ID from the group.
--incl-user-wild=<pattern>
Include the specific user class ID pattern in the group.
--excl-user-wild=<pattern>
Exclude the specific user class ID pattern from the group.

dhcpserver modify
VBoxManage dhcpserver modify <--network=netname | --interface=ifname>
[--server-ip=address] [--lower-ip=address] [--upper-ip=address]
[--netmask=mask] [--enable | --disable]
[[--global] | [--del-opt=dhcp-opt-no. . . ] | [--set-opt=dhcp-opt-no value. . . ]
| [--set-opt-hex=dhcp-opt-no hexstring. . . ] | [--force-opt=dhcp-opt-no. . . ]
| [--unforce-opt=dhcp-opt-no. . . ] | [--supress-opt=dhcp-opt-no. . . ]
| [--unsupress-opt=dhcp-opt-no. . . ] | [--min-lease-time=seconds]
| [--default-lease-time=seconds] | [--max-lease-time=seconds]
| [--remove-config] . . . ]
[<--group=name> | [--set-opt=dhcp-opt-no value. . . ]
| [--set-opt-hex=dhcp-opt-no hexstring. . . ] | [--force-opt=dhcp-opt-no. . . ]
| [--unforce-opt=dhcp-opt-no. . . ] | [--supress-opt=dhcp-opt-no. . . ]
| [--unsupress-opt=dhcp-opt-no. . . ] | [--del-mac=address. . . ]
| [--incl-mac=address. . . ] | [--excl-mac=address. . . ]
| [--del-mac-wild=pattern. . . ] | [--incl-mac-wild=pattern. . . ]
| [--excl-mac-wild=pattern. . . ] | [--del-vendor=string. . . ]
| [--incl-vendor=string. . . ] | [--excl-vendor=string. . . ]
| [--del-vendor-wild=pattern. . . ] | [--incl-vendor-wild=pattern. . . ]
| [--excl-vendor-wild=pattern. . . ] | [--del-user=string. . . ]
| [--incl-user=string. . . ] | [--excl-user=string. . . ]
| [--del-user-wild=pattern. . . ] | [--incl-user-wild=pattern. . . ]
| [--excl-user-wild=pattern. . . ] | [--zap-conditions]
| [--min-lease-time=seconds] | [--default-lease-time=seconds]
| [--max-lease-time=seconds] | [--remove-config] . . . ]
[<--vm=name|uuid> | [--nic=1-N] | [--del-opt=dhcp-opt-no. . . ]
| [--set-opt=dhcp-opt-no value. . . ] | [--set-opt-hex=dhcp-opt-no
hexstring. . . ] | [--force-opt=dhcp-opt-no. . . ]
| [--unforce-opt=dhcp-opt-no. . . ] | [--supress-opt=dhcp-opt-no. . . ]
| [--unsupress-opt=dhcp-opt-no. . . ] | [--min-lease-time=seconds]
| [--default-lease-time=seconds] | [--max-lease-time=seconds]
| [--fixed-address=address] | [--remove-config] . . . ]
[<--mac-address=address> | [--del-opt=dhcp-opt-no. . . ]
| [--set-opt=dhcp-opt-no value. . . ] | [--set-opt-hex=dhcp-opt-no
hexstring. . . ] | [--force-opt=dhcp-opt-no. . . ]
| [--unforce-opt=dhcp-opt-no. . . ] | [--supress-opt=dhcp-opt-no. . . ]
| [--unsupress-opt=dhcp-opt-no. . . ] | [--min-lease-time=seconds]

316
 9 VBoxManage

| [--default-lease-time=seconds] | [--max-lease-time=seconds]
| [--fixed-address=address] | [--remove-config] . . . ]

This modifies an existing DHCP server configuration. It takes the same options as the add
command with the addition of the following on scope configuration:

--del-opt=<dhcp-opt-no>
Counterpart to --set-opt that will cause the specified DHCP option number (0-255) to be
deleted from the server settings. Like with --set-opt the scope of the deletion is governed
by the --global, --vm, --mac-address and --group options.
--unforce-opt=<dhcp-opt-no>
Removes the specified DHCP option number (0-255) from the forced option list (i.e. the
reverse of --force-opt). Like with --set-opt the scope of the deletion is governed by
the --global, --vm, --mac-address and --group options.
--unsuppress-opt=<dhcp-opt-no>
Removes the specified DHCP option number (0-255) from the supressed option list (i.e. the
reverse of --suppress-opt). Like with --set-opt the scope of the deletion is governed
by the --global, --vm, --mac-address and --group options.
--remove-config
Removes the configuration currently being scoped. The --global scope is not removable.
The configuration scope will change to --global after this option.

And the addition of these group membership condition options:

--del-mac=<address>
Delete the specific MAC address from the group conditions.
--del-mac-wild=<pattern>
Delete the specific MAC address pattern from the group conditions.

--del-vendor=<string>
Delete the specific vendor class ID from the group conditions.
--del-vendor-wild=<pattern>
Delete the specific vendor class ID pattern from the group conditions.

--del-user=<string>
Delete the specific user class ID from the group conditions.
--del-user-wild=<pattern>
Delete the specific user class ID pattern from the group conditions.

--zap-conditions
Deletes all the group conditions.

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

Removes the specified DHCP server.

317
 9 VBoxManage

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

Start the specified DHCP server.

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

Restarts the specified DHCP server. The DHCP server must be running.

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

Stops the specified DHCP server.

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

Performs a lease database lookup. This is mainly for getting the IP address of a running VM.

--mac-address=<mac>
The MAC address to lookup in the lease database.

Common DHCP Options:

1 - SubnetMask
IPv4 netmask. Set to the value of the –netmask option by default.
2 - TimeOffset
UTC offset in seconds (32-bit decimal value).
3 - Routers
Space separated list of IPv4 router addresses.
4 - TimeServers
Space separated list of IPv4 time server (RFC 868) addresses.
5 - NameServers
Space separated list of IPv4 name server (IEN 116) addresses.

6 - DomainNameServers
Space separated list of IPv4 DNS addresses.
7 - LogServers
Space separated list of IPv4 log server addresses.

8 - CookieServers
Space separated list of IPv4 cookie server (RFC 865) addresses.

318
 9 VBoxManage

9 - LPRServers
Space separated list of IPv4 line printer server (RFC 1179) addresses.

10 - ImpressServers
Space separated list of IPv4 imagen impress server addresses.
11 - ResourseLocationServers
Space separated list of IPv4 resource location (RFC 887) addresses.

12 - HostName
The client name. See RFC 1035 for character limits.
13 - BootFileSize
Number of 512 byte blocks making up the boot file (16-bit decimal value).

14 - MeritDumpFile
Client core file.
15 - DomainName
Domain name for the client.
16 - SwapServer
IPv4 address of the swap server that the client should use.
17 - RootPath
The path to the root disk the client should use.
18 - ExtensionPath
Path to a file containing additional DHCP options (RFC2123).
19 - IPForwarding
Whether IP forwarding should be enabled by the client (boolean).
20 - OptNonLocalSourceRouting
Whether non-local datagrams should be forwarded by the client (boolean)

21 - PolicyFilter
List of IPv4 addresses and masks paris controlling non-local source routing.
22 - MaxDgramReassemblySize
The maximum datagram size the client should reassemble (16-bit decimal value).

23 - DefaultIPTTL
The default time-to-leave on outgoing (IP) datagrams (8-bit decimal value).
24 - PathMTUAgingTimeout
RFC1191 path MTU discovery timeout value in seconds (32-bit decimal value).

25 - PathMTUPlateauTable
RFC1191 path MTU discovery size table, sorted in ascending order (list of 16-bit decimal
values).
26 - InterfaceMTU
The MTU size for the interface (16-bit decimal value).

27 - AllSubnetsAreLocal
Indicates whether the MTU size is the same for all subnets (boolean).
28 - BroadcastAddress
Broadcast address (RFC1122) for the client to use (IPv4 address).

319
 9 VBoxManage

29 - PerformMaskDiscovery
Whether to perform subnet mask discovery via ICMP (boolean).
30 - MaskSupplier
Whether to respond to subnet mask requests via ICMP (boolean).
31 - PerformRouterDiscovery
Whether to perform router discovery (RFC1256) (boolean).
32 - RouterSolicitationAddress
Where to send router solicitation requests (RFC1256) (IPv4 address).
33 - StaticRoute
List of network and router address pairs addresses.
34 - TrailerEncapsulation
Whether to negotiate the use of trailers for ARP (RTF893) (boolean).
35 - ARPCacheTimeout
The timeout in seconds for ARP cache entries (32-bit decimal value).
36 - EthernetEncapsulation
Whether to use IEEE 802.3 (RTF1042) rather than of v2 (RFC894) ethernet encapsulation
(boolean).
37 - TCPDefaultTTL
Default time-to-live for TCP sends (non-zero 8-bit decimal value).
38 - TCPKeepaliveInterval
The interface in seconds between TCP keepalive messages (32-bit decimal value).
39 - TCPKeepaliveGarbage
Whether to include a byte of garbage in TCP keepalive messages for backward compatibility
(boolean).
40 - NISDomain
The NIS (Sun Network Information Services) domain name (string).
41 - NISServers
Space separated list of IPv4 NIS server addresses.
42 - NTPServers
Space separated list of IPv4 NTP (RFC1035) server addresses.
43 - VendorSpecificInfo
Vendor specific information. Only accessible using –set-opt-hex.
44 - NetBIOSNameServers
Space separated list of IPv4 NetBIOS name server (NBNS) addresses (RFC1001,RFC1002).
45 - NetBIOSDatagramServers
Space separated list of IPv4 NetBIOS datagram distribution server (NBDD) addresses
(RFC1001,RFC1002).
46 - NetBIOSNodeType
NetBIOS node type (RFC1001,RFC1002): 1=B-node, 2=P-node, 4=M-node, and 8=H-
node (8-bit decimal value).
47 - NetBIOSScope
NetBIOS scope (RFC1001,RFC1002). Only accessible using –set-opt-hex.

320
 9 VBoxManage

48 - XWindowsFontServers
Space separated list of IPv4 X windows font server addresses.
49 - XWindowsDisplayManager
Space separated list of IPv4 X windows display manager addresses.
62 - NetWareIPDomainName
Netware IP domain name (RFC2242) (string).
63 - NetWareIPInformation
Netware IP information (RFC2242). Only accessible using –set-opt-hex.
64 - NISPlusDomain
The NIS+ domain name (string).
65 - NISPlusServers
Space separated list of IPv4 NIS+ server addresses.
66 - TFTPServerName
TFTP server name (string).
67 - BootfileName
Bootfile name (string).
68 - MobileIPHomeAgents
Space separated list of IPv4 mobile IP agent addresses.
69 - SMTPServers
Space separated list of IPv4 simple mail transport protocol (SMPT) server addresses.
70 - POP3Servers
Space separated list of IPv4 post office protocol 3 (POP3) server addresses.
71 - NNTPServers
Space separated list of IPv4 network news transport protocol (NTTP) server addresses.
72 - WWWServers
Space separated list of default IPv4 world wide web (WWW) server addresses.
73 - FingerServers
Space separated list of default IPv4 finger server addresses.
74 - IRCServers
Space separated list of default IPv4 internet relay chat (IRC) server addresses.
75 - StreetTalkServers
Space separated list of IPv4 StreetTalk server addresses.
76 - STDAServers
Space separated list of IPv4 StreetTalk directory assistance (STDA) server addresses.
78 - SLPDirectoryAgent
Addresses of one or more service location protocol (SLP) directory agent, and an indicator
of whether their use is mandatory. Only accessible using –set-opt-hex.
79 - SLPServiceScope
List of service scopes for the service location protocol (SLP) and whether using the list is
mandator. Only accessible using –set-opt-hex.
119 - DomainSearch
Domain search list, see RFC3397 and section 4.1.4 in RFC1035 for encoding. Only acces-
sible using –set-opt-hex.

321
 9 VBoxManage

9.51 VBoxManage usbdevsource

Add and remove USB device sources.

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

VBoxManage usbdevsource remove <source-name>

Description
The VBoxManage usbdevsource command adds a USB device source and makes it available to
the guests on the host system. You can also use this command to remove the USB device source.

Add a USB Device Source

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

The VBoxManage usbdevsource add command adds a USB device source, which is available
to all guests on the host system.

source-name
Specifies a unique name for the USB device source.
–address=address
Specifies the address of the USB backend.

–backend=backend
Specifies the USB proxy service backend to use.
For now only USBIP is supported to specify a remote server using the USB/IP protocol.

Remove a USB Device

VBoxManage usbdevsource remove <source-name>

The VBoxManage usbdevsource remove command removes a USB device.

source-name
Specifies the name of the USB device source to remove.

Examples
The following command adds a USB device server called hostusb01.
$ VBoxManage usbdevsource add hostusb01 --backend USBIP --address [Link]

9.52 VBoxManage extpack

Extension package management.

322
 9 VBoxManage

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

VBoxManage extpack uninstall [--force] <name>

VBoxManage extpack cleanup

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

Installs a new extension pack on the system. This command will fail if an older version of the
same extension pack is already installed. The --replace option can be used to uninstall any old
package before the new one is installed.

--replace
Uninstall existing extension pack version.
--accept-license=<sha256>
Accept the license text with the given SHA-256 hash value.
VBoxManage will display the SHA-256 value when performing a manual installation. The
hash can of course be calculated by looking inside the extension pack and using sha256sum
or similar on the license file.
tarball
The file containing the extension pack to be installed.

extpack uninstall
VBoxManage extpack uninstall [--force] <name>

Uninstalls an extension pack from the system. The subcommand will also succeed in the case
where the specified extension pack is not present on the system. You can use VBoxManage list
extpacks to show the names of the extension packs which are currently installed.

--force
Overrides most refusals to uninstall an extension pack

name
The name of the extension pack to be uninstalled.

extpack cleanup
VBoxManage extpack cleanup

Used to remove temporary files and directories that may have been left behind if a previous
install or uninstall command failed.

323
 9 VBoxManage

Examples
How to list extension packs:
$ VBoxManage list extpacks
Extension Packs: 1
Pack no. 0: Oracle VM VirtualBox Extension Pack
Version: 4.1.12
Revision: 77218
Edition:
Description: USB 2.0 Host Controller, VirtualBox RDP, PXE ROM with E1000 support.
VRDE Module: VBoxVRDP
Usable: true
Why unusable:

How to remove an extension pack:

$ VBoxManage extpack uninstall "Oracle VM VirtualBox Extension Pack"
0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
Successfully uninstalled "Oracle VM VirtualBox Extension Pack".

9.53 VBoxManage updatecheck

Checks for a newer version of VirtualBox.

Synopsis
VBoxManage updatecheck perform [--machine-readable]

VBoxManage updatecheck list [--machine-readable]

VBoxManage updatecheck modify [--disable | --enable] [--channel=stable |

withbetas | all] [--frequency=days]

Description
The updatecheck subcommand is used to check if a newer version of VirtualBox is available.
The two subcommand options of updatecheck are used for modifying or viewing the settings
associated with checking for a newer version of VirtualBox.

updatecheck perform
VBoxManage updatecheck perform [--machine-readable]

Checks if a newer version of VirtualBox is available.

--machine-readable
Machine readable output.

updatecheck list
VBoxManage updatecheck list [--machine-readable]

Displays the current settings used for specifying when to check for a newer version of
VirtualBox.
--machine-readable
Machine readable output.

324
 9 VBoxManage

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

Modifies the settings used for specifying when to check for a newer version of VirtualBox.

--enable
Enable the update check service.
--disable
Disable the update check service.
--channel=stable | withbetas | all
The preferred release type used for determining whether a newer version of VirtualBox is
available. The default is ’stable’.
stable
Checks for newer stable releases (maintenance and minor releases within the same
major release) of VirtualBox.
all
Checks for newer stable releases (maintenance and minor releases within the same
major release) and major releases of VirtualBox.
withbetas
Checks for newer stable releases (maintenance and minor releases within the same
major release), major releases, and beta releases of VirtualBox.
--frequency=days
Specifies how often in days to check for a newer version of VirtualBox.

--proxy-mode=system | manual | none

Specifies the proxy mode to use.
--proxy-url=<address>
Specifies the proxy address to use. Set to empty string to clear proxy address.

9.54 VBoxManage modifynvram

List and modify the NVRAM content of a virtual machine.

Synopsis
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> enrollmok [--mok=filename]

[--owner-uuid=uuid]

VBoxManage modifynvram <uuid|vmname> listvars

325
 9 VBoxManage

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]

Description
The “modifynvram” commands are for experts who want to inspect and modify the UEFI variable
store of a virtual machine. Any mistakes done here can bring the virtual machine in a non
working state.

Common options
The subcommands of modifynvram all operate on a running virtual machine:

uuid|vmname
Either the UUID or the name (case sensitive) of a VM.

modifynvram inituefivarstore
VBoxManage modifynvram <uuid|vmname> inituefivarstore

Iniitalizes the UEFI variable store to a default state. Any previous existing variable store is
deleted. Use with extreme caution!

modifynvram enrollmssignatures
VBoxManage modifynvram <uuid|vmname> enrollmssignatures

Enrolls the default Microsoft KEK and DB signatures required for UEFI secure boot.

modifynvram enrollorclpk
VBoxManage modifynvram <uuid|vmname> enrollorclpk

Enrolls the default platform key provided by Oracle required for UEFI secure boot.

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

Enrolls a custom platform key provided by the user required for UEFI secure boot. The follow-
ing commands use openssl to generate a new platform key:
$ openssl req -new -x509 -newkey rsa:2048 -keyout [Link] -out [Link]

$ openssl x509 -in [Link] -out [Link] -outform DER

326
 9 VBoxManage

--platform-key=<filename>
The platform key provided as a DER encoded X.509 signature.

--owner-uuid=<uuid>
The UUID identifying the owner of the platform key.

modifynvram listvars
VBoxManage modifynvram <uuid|vmname> listvars

Lists all UEFI variables in the virtual machines’s store along with their owner UUID.

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

Queries the content of a given UEFI variable identified by its name.

--name=<name>
UEFI variable name to query.

--filename=<filename>
Where to store the content of the variable upon success. This is optional, if omitted the
content will be dumped to the terminal as a hex dump.

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

Deletes the given variable identified by its name and owner UUID.

--name=<name>
UEFI variable name to delete.
--owner-uuid=<uuid>
The UUID identifying the owner of the variable to delete.

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

Changes the UEFI variable content to the one form the given file.

--name=<name>
UEFI variable name to change the data for.

--filename=<filename>
The file to read the data from.

327
 9 VBoxManage

9.55 vboximg-mount
FUSE mount a virtual disk image for Mac OS and Linux hosts.

Synopsis
vboximg-mount <-? | -h | --help>

vboximg-mount <--image=image-UUID> [--guest-filesystem]

[-o=FUSE-option[,FUSE-option]] [--root] [--rw] <mountpoint>

vboximg-mount <--list> [--image=image-UUID] [--guest-filesystem]

[--verbose] [--vm=vm-UUID] [--wide]

Description
The vboximg-mount command enables you to make Oracle VM VirtualBox disk images available
to a Mac OS or Linux host operating system (OS) for privileged or non-priviliged access. You
can mount any version of the disk from its available history of snapshots. Use this command to
mount, view, and optionally modify the contents of an Oracle VM VirtualBox virtual disk image,
and you can also use this command to view information about registered virtual machines (VMs).
This command uses the Filesystem in Userspace (FUSE) technology to provide raw access to
an Oracle VM VirtualBox virtual disk image.
When you use the --image option to specify a base image identifier, only the base image is
mounted. Any related snapshots are disregarded. Alternatively, if you use the --image option
to specify a snapshot, the state of the FUSE-mounted virtual disk is synthesized from the implied
chain of snapshots, including the base image.
The vboximg-mount command includes experimental read-only access to file systems inside a
VM disk image. This feature enables you to extract some files from the VM disk image without
starting the VM and without requiring third-party file system drivers on the host system. Oracle
VM VirtualBox supports the FAT, NTFS, ext2, ext3, and ext4 file systems.
The virtual disk is exposed as a device node within a FUSE-based file system that overlays the
specified mount point.
The FUSE file system includes a directory that contains a number of files. The file system
can also contain a directory that includes a symbolic link that has the same base name (see the
basename(1) man page) as the virtual disk base image and points to the location of the virtual
disk base image. The directory can be of the following types:

• vhdd provides access to the raw disk image data as a flat image
• volID provides access to an individual volume on the specified disk image

• fsID provides access to a supported file system without requiring a host file system driver

General Command Options

vboximg-mount <-? | -h | --help>

Use the following options to obtain information about the vboximg-mount command and its
options.

--help, --h, or--?

Shows usage information.

328
 9 VBoxManage

Mounting an Oracle VM VirtualBox Disk Image

vboximg-mount <--image=image-UUID> [--guest-filesystem]
[-o=FUSE-option[,FUSE-option]] [--root] [--rw] <mountpoint>

Use the vboximg-mount command to mount an Oracle VM VirtualBox virtual disk image on a
Mac OS or Linux host system. When mounted, you can view the contents of the disk image or
modify the contents of the disk image.
You can use the vboximg-mount command to restrict FUSE-based access to a subsection of the
virtual disk.

--image=<disk-image>
Specifies the Universally Unique Identifier (UUID), name, or path of the Oracle VM
VirtualBox disk image.
The short form of the --image option is -i.
--guest-filesystem
Enables experimental read-only support for guest file systems. When you specify this op-
tion, all known file systems are made available to access.
The short form of the --guest-filesystem option is -g.

-o=<FUSE-option>[,<FUSE-option>...]
Specifies FUSE mount options.
The vboximg-mount command enables you to use the FUSE mount options that are de-
scribed in the [Link](8) man page.

--root
Overrides the security measure that restricts file access to the file system owner by also
granting file access to the root user.
Same as the -o allow_root option. See the -o option description.
This option is incompatible with the -o allow_other option.

--rw
Mounts the specified image as read-write, which is required if you want to modify its
contents. By default, images are mounted as read-only.
mount-point
Specifies the path name of a directory on which to mount the Oracle VM VirtualBox disk
image.

Viewing Oracle VM VirtualBox Disk Image Information

vboximg-mount <--list> [--image=image-UUID] [--guest-filesystem]
[--verbose] [--vm=vm-UUID] [--wide]

Use the vboximg-mount command to view information about registered VMs or an Oracle VM
VirtualBox virtual disk image.

--image=<disk-image>
Specifies the UUID, name, or path of the Oracle VM VirtualBox disk image.
The short form of the --image option is -i.

329
 9 VBoxManage

--guest-filesystem
Enables experimental read-only support for guest file systems. When you specify this op-
tion, all known file systems are made available to access.
The short form of the --guest-filesystem option is -g.
--list
Shows information about the disks that are associated with the registered VMs. If you
specify a disk image, this option shows information about the partitions of the specified
image.
When you specify the --verbose option, the output includes detailed information about
the VMs and media, including snapshot images and file paths.
The short form of the --list option is -l.
--verbose
Shows or logs detailed information.
The short form of the --verbose option is -v.
--vm=<vm-UUID>
Outputs information about the VM that is associated with the specified UUID.
--wide
Outputs information in a wide format. This output includes the lock state information of
running VMs. For VMs that are not running, the state is created.
The wide output uses a tree-like structure in the VM column to show the relationship
between a VM base image and its snapshots.

Examples
The following example shows how to mount a virtual disk image on the host operating system
(OS).
$ mkdir fuse_mount_point
$ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 fuse_mount_point
$ ls fuse_mount_point
[Link][32256:2053029880] vhdd
$ sudo mount fuse_mount_point/vhdd /mnt

The mkdir command creates a mount point called fuse_mount_point on the host OS.
The vboximg-mount command is then used to mount the specified disk image on the
fuse_mount_point mount point. The mount includes all snapshots for the disk image.
The ls command shows the contents of fuse_mount_point. The mount command is then
used to mount the FUSE-mounted device node, vhdd, on the /mnt mount point. The vhdd device
node represents the virtual disk image.
The following example shows how to make the known file systems of the
b490e578-08be-4f7d-98e9-4c0ef0952377 disk image accessible when the image is mounted
on the fuse_mount_point mount point:
$ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 \
--guest-filesystem fuse_mount_point

The following command outputs detailed information about all registered VMs and their snap-
shots:
$ vboximg-mount --list --verbose

The following command shows an excerpt of the list output in wide format.

330
 9 VBoxManage

$ vboximg-mount --list --wide

VM Image Size Type State UUID (hierarchy)

------------------------------------------ ------------------------------------
Proxy 0833f5bc-6304-42e1-b799-cdc81c576c60
|
+- [Link] 4.8G VDI rlock d5f84afb-0794-4952-ab71-6bbcbee07737
| +- <snapshot> 12.3G VDI rlock dffc67aa-3023-477f-8033-b27e3daf4f54
| +- <snapshot> 8.8G VDI rlock 3b2755bd-5f2a-4171-98fe-647d510b6274
| +- <snapshot> 14.6G VDI rlock e2ccdb5f-49e8-4123-8623-c61f363cc5cf
| +- <snapshot> 7.4G VDI wlock 3c1e6794-9091-4be3-9e80-11aba40c2649

------------------------------------------ ------------------------------------
Oracle Linux 7 5365ab5f-470d-44c0-9863-dad532ee5905
|
+- Oracle Linux [Link] 7.0G VDI created 96d2e92e-0d4e-46ab-a0f1-008fdbf997e7
| +- <snapshot> 15.9G VDI created f9cc866a-9166-42e9-a503-bbfe9b7312e8
|
+- [Link] 11.1G VDI created 79a370bd-0c4f-480a-30bb-10cdea68423f

The output shows that the Proxy VM is running the fourth snapshot of the [Link] virtual
disk image. The running state is indicated by the wlock value in the State column.
The Oracle Linux 7 VM is not running. It has two images: Oracle Linux [Link] and
[Link]. The Oracle Linux [Link] image has a snapshot.
The following command shows information about the VM with the specified UUID:

$ vboximg-mount --list --vm=b1d5563b-2a5b-4013-89f1-26c81d6bbfa0

-----------------------------------------------------------------
VM: ubu
UUID: b1d5563b-2a5b-4013-89f1-26c81d6bbfa0

Image: [Link]
UUID: b490e578-08be-4f7d-98e9-4c0ef0952377

Snapshot: 35afe1e0-0a51-44f3-a228-caf172f3306f
Size: 12.1G

Snapshot: 874279c1-4425-4282-ada8-a9c07c00bbf9
Size: 13.6G

Image: [Link]
UUID: 79a370bd-6eb7-4dbf-8bc6-d29118f127e0

331
10 Advanced Topics
10.1 Automated Guest Logins
Oracle VM VirtualBox provides Guest Addition modules for Windows, Linux, and Oracle Solaris
to enable automated logins on the guest.
When a guest operating system is running in a virtual machine, it might be desirable to perform
coordinated and automated logins using credentials passed from the host. Credentials are user
name, password, and domain name, where each value might be empty.

10.1.1 Automated Windows Guest Logins

Windows provides a modular system login subsystem, called Winlogon, which can be customized
and extended by means of so-called GINA (Graphical Identification and Authentication) modules.
In Windows Vista and later releases, the GINA modules were replaced with a new mechanism
called credential providers. The Oracle VM VirtualBox Guest Additions for Windows come with
both, a GINA and a credential provider module, and therefore enable any Windows guest to
perform automated logins.
To activate the Oracle VM VirtualBox GINA or credential provider module, install the Guest
Additions using the command line switch /with_autologon. All the following manual steps
required for installing these modules will be then done by the installer.
To manually install the Oracle VM VirtualBox GINA module, extract the Guest Additions as
shown in chapter [Link], Manual File Extraction, page 93, and copy the [Link] file
to the Windows SYSTEM32 directory. In the registry, create the following key with a value of
[Link]:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL

Note: The Oracle VM VirtualBox GINA module is implemented as a wrapper around the
[Link] standard Windows GINA module. As a result, it might not work correctly
with third-party GINA modules.

To manually install the Oracle VM VirtualBox credential provider module, extract the
Guest Additions as shown in chapter [Link], Manual File Extraction, page 93 and copy the
[Link] file to the Windows SYSTEM32 directory. In the registry, create the following
keys:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
Authentication\Credential Providers\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}

HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}

HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32

All default values, the key named Default, must be set to VBoxCredProv.
Create the following string and assign it a value of Apartment.
HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel

To set credentials, use the following command on a running VM:

332
 10 Advanced Topics

$ VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"

While the VM is running, the credentials can be queried by the Oracle VM VirtualBox login
modules, GINA or credential provider, using the Oracle VM VirtualBox Guest Additions device
driver. When Windows is in logged out mode, the login modules will constantly poll for creden-
tials and if they are present, a login will be attempted. After retrieving the credentials, the login
modules will erase them so that the above command will have to be repeated for subsequent
logins.
For security reasons, credentials are not stored in any persistent manner and will be lost when
the VM is reset. Also, the credentials are write-only. There is no way to retrieve the credentials
from the host side. Credentials can be reset from the host side by setting empty values.
Depending on the Windows guest version, the following restrictions apply:

• For Windows XP guests. The login subsystem needs to be configured to use the classic
login dialog, as the Oracle VM VirtualBox GINA module does not support the Windows
XP-style welcome dialog.
• Windows Vista, Windows 7, Windows 8, and Windows 10 guests. The login subsystem
does not support the so-called Secure Attention Sequence, Ctrl+Alt+Del. As a result, the
guest’s group policy settings need to be changed to not use the Secure Attention Sequence.
Also, the user name given is only compared to the true user name, not the user friendly
name. This means that when you rename a user, you still have to supply the original user
name as Windows never renames user accounts internally.
• Automatic login handling of the built-in Windows Remote Desktop Service, formerly
known as Terminal Services, is disabled by default. To enable it, create the following
registry key with a DWORD value of 1.

HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon

The following command forces Oracle VM VirtualBox to keep the credentials after they were
read by the guest and on VM reset:
$ VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1

Note that this is a potential security risk, as a malicious application running on the guest could
request this information using the proper interface.

10.1.2 Automated Linux and UNIX Guest Logins

Oracle VM VirtualBox provides a custom PAM module (Pluggable Authentication Module) which
can be used to perform automated guest logins on platforms which support this framework.
Virtually all modern Linux and UNIX distributions rely on PAM.
For automated logins on Ubuntu, or Ubuntu-derived, distributions using LightDM as the dis-
play manager. See chapter [Link], Oracle VM VirtualBox Greeter for Ubuntu/LightDM, page
335.
The pam_vbox.so module itself does not do an actual verification of the credentials passed to
the guest OS. Instead it relies on other modules such as pam_unix.so or pam_unix2.so down
in the PAM stack to do the actual validation using the credentials retrieved by pam_vbox.so.
Therefore pam_vbox.so has to be on top of the authentication PAM service list.

Note: The pam_vbox.so module only supports the auth primitive. Other primitives
such as account, session, or password are not supported.

333
 10 Advanced Topics

The pam_vbox.so module is shipped as part of the Guest Additions but it is not installed
and/or activated on the guest OS by default. In order to install it, it has to be copied from
/opt/VBoxGuestAdditions-version/other/ to the security modules directory. This is usually
/lib/security/ on 32-bit Linux guests or /lib64/security/ on 64-bit Linux guests. Please
refer to your guest OS documentation for the correct PAM module directory.
For example, to use pam_vbox.so with a Ubuntu Linux guest OS and the GNOME Desktop
Manager (GDM) to log in users automatically with the credentials passed by the host, configure
the guest OS as follows:

1. Copy the pam_vbox.so module to the security modules directory. In this case,
/lib/security.

2. Edit the PAM configuration file for GDM, found at /etc/pam.d/gdm. Add the line auth
requisite pam_vbox.so at the top. Additionally, in most Linux distributions there is a
file called /etc/pam.d/common-auth. This file is included in many other services, like
the GDM file mentioned above. There you also have to add the line auth requisite
pam_vbox.so.

3. If authentication against the shadow database using pam_unix.so or pam_unix2.so

is desired, the argument try_first_pass for pam_unix.so or use_first_pass for
pam_unix2.so is needed in order to pass the credentials from the Oracle VM VirtualBox
module to the shadow database authentication module. For Ubuntu, this needs to be added
to /etc/pam.d/common-auth, to the end of the line referencing pam_unix.so. This argu-
ment tells the PAM module to use credentials already present in the stack, such as the ones
provided by the Oracle VM VirtualBox PAM module.

Warning: An incorrectly configured PAM stack can effectively prevent you from logging
into your guest system.

To make deployment easier, you can pass the argument debug right after the pam_vbox.so
statement. Debug log output will then be recorded using syslog.

Note: By default, pam_vbox does not wait for credentials to arrive from the host.
When a login prompt is shown, for example by GDM/KDM or the text console, and
pam_vbox does not yet have credentials it does not wait until they arrive. Instead the
next module in the PAM stack, depending on the PAM configuration, will have the
chance for authentication.

pam_vbox supports various guest property parameters that are located in

/VirtualBox/GuestAdd/PAM/. These parameters allow pam_vbox to wait for credentials
to be provided by the host and optionally can show a message while waiting for those. The
following guest properties can be set:

• CredsWait: Set to 1 if pam_vbox should start waiting until credentials arrive from the
host. Until then no other authentication methods such as manually logging in will be
available. If this property is empty or gets deleted no waiting for credentials will be per-
formed and pam_vbox will act like before. This property must be set read-only for the guest
(RDONLYGUEST).
• CredsWaitAbort: Aborts waiting for credentials when set to any value. Can be set from
host and the guest.

334
 10 Advanced Topics

• CredsWaitTimeout: Timeout, in seconds, to let pam_vbox wait for credentials to arrive.

When no credentials arrive within this timeout, authentication of pam_vbox will be set to
failed and the next PAM module in chain will be asked. If this property is not specified,
set to 0 or an invalid value, an infinite timeout will be used. This property must be set
read-only for the guest (RDONLYGUEST).
To customize pam_vbox further there are the following guest properties:
• CredsMsgWaiting: Custom message showed while pam_vbox is waiting for credentials
from the host. This property must be set read-only for the guest (RDONLYGUEST).
• CredsMsgWaitTimeout: Custom message showed when waiting for credentials by
pam_vbox has timed out. For example, they did not arrive within time. This property
must be set read-only for the guest (RDONLYGUEST).

Note: If a pam_vbox guest property does not have the correct flag set (RDONLYGUEST)
the property is ignored and, depending on the property, a default value will be used.
This can result in pam_vbox not waiting for credentials. Consult the appropriate syslog
file for more information and use the debug option.

[Link] Oracle VM VirtualBox Greeter for Ubuntu/LightDM

Oracle VM VirtualBox comes with a greeter module, named vbox-greeter, that can be used
with LightDM. LightDM is the default display manager for Ubuntu Linux and therefore can also
be used for automated guest logins.
vbox-greeter does not need the pam_vbox module described in chapter 10.1.2, Automated
Linux and UNIX Guest Logins, page 333in order to function. It comes with its own authentication
mechanism provided by LightDM. However, to provide maximum flexibility both modules can be
used together on the same guest.
As with the pam_vbox module, vbox-greeter is shipped as part of the Guest Additions but
it is not installed or activated on the guest OS by default. To install vbox-greeter automat-
ically upon Guest Additions installation, use the --with-autologon option when starting the
[Link] file:
# ./[Link] -- --with-autologon

For manual or postponed installation, copy the [Link] file from

/opt/VBoxGuestAdditions-<version>/other/ to the xgreeters directory, which is usually
/usr/share/xgreeters/. See your guest OS documentation for the name of the correct
LightDM greeter directory.
The vbox-greeter module is installed by the Oracle VM VirtualBox Guest Additions installer
and is located in /usr/sbin/. To enable vbox-greeter as the standard greeter module, edit the
file /etc/lightdm/[Link] as follows:
[SeatDefaults]
greeter-session=vbox-greeter

Note:

• The LightDM server must be fully restarted in order for vbox-greeter

to be used as the default greeter. As root on Ubuntu, run
service lightdm --full-restart or restart the guest.

• vbox-greeter is independent of the graphical session you choose, such as

Gnome, KDE, or Unity. However, vbox-greeter does require FLTK 1.3 or later
to implement its own user interface.

335