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 Section 4.2.1.4, “Manual File Extraction”, and copy the VBoxGINA.dll file to the Windows SYSTEM32 directory. In the registry, create the following key with a value of VBoxGINA.dll:

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

To manually install the Oracle VM VirtualBox credential provider module, extract the Guest Additions as shown in Section 4.2.1.4, “Manual File Extraction” and copy the VBoxCredProv.dll 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:

$ 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 credentials 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:

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.

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 display manager. See Section 9.1.2.1, “Oracle VM VirtualBox Greeter for Ubuntu/LightDM”.

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.

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:

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.

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:

To customize pam_vbox further there are the following guest properties:

# ./VBoxLinuxAdditions.run -- --with-autologon

[SeatDefaults]
greeter-session=vbox-greeter

Microsoft offers a system preparation tool called Sysprep, to prepare a Windows system for deployment or redistribution. Some Windows releases include Sysprep on the installation medium, but the tool is also available for download from the Microsoft web site. In a standard For most Windows versions, Sysprep is included in a default installation. Sysprep mainly consists of an executable called sysprep.exe which is invoked by the user to put the Windows installation into preparation mode.

The Guest Additions offer a way to launch a system preparation on the guest operating system in an automated way, controlled from the host system. See Section 4.9, “Guest Control of Applications” for details of how to use this feature with the special identifier sysprep as the program to execute, along with the user name sysprep and password sysprep for the credentials. Sysprep is then started with the required system rights.

The Oracle VM VirtualBox Guest Additions contain several different drivers. If you do not want to configure them all, use the following command to install the Guest Additions:

$ sh ./VBoxLinuxAdditions.run no_setup

After running this script, run the rcvboxadd setup command as root to compile the kernel modules.

On some 64-bit guests, you must replace lib with lib64. On older guests that do not run the udev service, you must add the vboxadd service to the default runlevel to ensure that the modules are loaded.

To set up the time synchronization service, add the vboxadd-service service to the default runlevel. To set up the X11 and OpenGL part of the Guest Additions, run the rcvboxadd-x11 setup command. Note that you do not need to enable additional services.

Use the rcvboxadd setup to recompile the guest kernel modules.

After compilation, reboot your guest to ensure that the new modules are loaded.

This section assumes that you are familiar with configuring the X.Org server using xorg.conf and optionally the newer mechanisms using hal or udev and xorg.conf.d. If not you can learn about them by studying the documentation which comes with X.Org.

The Oracle VM VirtualBox Guest Additions includes drivers for X.Org. By default these drivers are in the following directory:

/opt/VBoxGuestAdditions-version/other/

The correct versions for the X server are symbolically linked into the X.Org driver directories.

For graphics integration to work correctly, the X server must load the vboxvideo driver. Many recent X server versions look for it automatically if they see that they are running in Oracle VM VirtualBox. For an optimal user experience, the guest kernel drivers must be loaded and the Guest Additions tool VBoxClient must be running as a client in the X session.

For mouse integration to work correctly, the guest kernel drivers must be loaded. In addition, for legacy X servers the correct vboxmouse driver must be loaded and associated with /dev/mouse or /dev/psaux. For most guests, a driver for a PS/2 mouse must be loaded and the correct vboxmouse driver must be associated with /dev/vboxguest.

The Oracle VM VirtualBox guest graphics driver can use any graphics configuration for which the virtual resolution fits into the virtual video memory allocated to the virtual machine, minus a small amount used by the guest driver, as described in Section 3.6, “Display Settings”. The driver will offer a range of standard modes at least up to the default guest resolution for all active guest monitors. The default mode can be changed by setting the output property VBOX_MODE to "<width>x<height>" for any guest monitor. When VBoxClient and the kernel drivers are active this is done automatically when the host requests a mode change. The driver for older versions can only receive new modes by querying the host for requests at regular intervals.

With legacy X Servers before version 1.3, you can also add your own modes to the X server configuration file. Add them to the "Modes" list in the "Display" subsection of the "Screen" section. For example, the following section has a custom 2048x800 resolution mode added:

Section "Screen"
        Identifier    "Default Screen"
        Device        "VirtualBox graphics card"
        Monitor       "Generic Monitor"
        DefaultDepth  24
        SubSection "Display"
                Depth         24
                Modes         "2048x800" "800x600" "640x480"
        EndSubSection
EndSection

Oracle VM VirtualBox includes a feature called webcam passthrough, which enables a guest to use a host webcam. This complements the general USB passthrough support which was the typical way of using host webcams in legacy releases. The webcam passthrough support can handle non-USB video sources in theory, but this is completely untested.

The host webcam can be attached to the VM using the Devices menu in the VM menu bar. The Webcams menu contains a list of available video input devices on the host. Clicking on a webcam name attaches or detaches the corresponding host device.

The VBoxManage command line tool can be used to enable webcam passthrough. Please see the host-specific sections below for additional details. The following commands are available:

When the webcam device is detached from the host, the emulated webcam device is automatically detached from the guest.

When the webcam device is detached from the host, the emulated webcam device remains attached to the guest and must be manually detached using the VBoxManage controlvm VM-name webcam detach command.

When the webcam is detached from the host the emulated webcam device is automatically detached from the guest only if the webcam is streaming video. If the emulated webcam is inactive it should be manually detached using the VBoxManage controlvm VM-name webcam detach command.

Aliases .0 and .1 are mapped to /dev/video0, alias .2 is mapped to /dev/video1 and so forth.

Apart from the standard VESA resolutions, the Oracle VM VirtualBox VESA BIOS enables you to add up to 16 custom video modes which will be reported to the guest operating system. When using Windows guests with the Oracle VM VirtualBox Guest Additions, a custom graphics driver will be used instead of the fallback VESA solution so this information does not apply.

Additional video modes can be configured for each VM using the extra data facility. The extra data key is called CustomVideoModex with x being a number from 1 to 16. Please note that modes will be read from 1 until either the following number is not defined or 16 is reached. The following example adds a video mode that corresponds to the native display resolution of many notebook computers:

$ VBoxManage setextradata VM-name "CustomVideoMode1" "1400x1050x16"

The VESA mode IDs for custom video modes start at 0x160. In order to use the above defined custom video mode, the following command line has to be supplied to Linux:

vga = 0x200 | 0x160
vga = 864

For guest operating systems with Oracle VM VirtualBox Guest Additions, a custom video mode can be set using the video mode hint feature.

When guest systems with the Guest Additions installed are started using the graphical frontend, the normal Oracle VM VirtualBox application, they will not be allowed to use screen resolutions greater than the host's screen size unless the user manually resizes them by dragging the window, switching to full screen or seamless mode or sending a video mode hint using VBoxManage. This behavior is what most users will want, but if you have different needs, you can change it by issuing one of the following commands from the command line:

As an alternative to using virtual disk images as described in Chapter 5, Virtual Storage, Oracle VM VirtualBox can also present either entire physical hard disks or selected partitions as virtual disks to virtual machines.

With Oracle VM VirtualBox, this type of access is called raw hard disk access. It enables a guest operating system to access its virtual hard disk without going through the host OS file system. The actual performance difference for image files compared to raw disk varies greatly depending on the overhead of the host file system, whether dynamically growing images are used, and on host OS caching strategies. The caching indirectly also affects other aspects such as failure behavior. For example, whether the virtual disk contains all data written before a host OS crash. Consult your host OS documentation for details on this.

Raw hard disk access, both for entire disks and individual partitions, is implemented as part of the VMDK image format support. As a result, you will need to create a special VMDK image file which defines where the data will be stored. After creating such a special VMDK image, you can use it like a regular virtual disk image. For example, you can use the Virtual Media Manager, see Section 5.3, “The Virtual Media Manager”, or VBoxManage to assign the image to a virtual machine.

$ VBoxManage createmedium disk --filename path-to-file.vmdk --format=VMDK
 --variant RawDisk --property RawDrive=/dev/sda

$ VBoxManage storageattach WindowsXP --storagectl "IDE Controller" \
 --port 0 --device 0 --type hdd --medium path-to-file.vmdk

$ VBoxManage createmedium disk --filename path-to-file.vmdk --format=VMDK
--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5

$ VBoxManage list hostdrives

$ VBoxManage createmedium disk --filename path-to-file.vmdk --format=VMDK
--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5
--property Relative=1

$ VBoxManage createmedium disk --filename path-to-file.vmdk --format=VMDK
--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5
--property-file BootSector=winxp.mbr

Oracle VM VirtualBox reports vendor product data for its virtual hard disks which consist of hard disk serial number, firmware revision and model number. These can be changed using the following commands:

$ VBoxManage setextradata VM-name \
"VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial"
$ VBoxManage setextradata VM-name \
"VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware"
$ VBoxManage setextradata VM-name \
"VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model"

The serial number is a 20 byte alphanumeric string, the firmware revision an 8 byte alphanumeric string and the model number a 40 byte alphanumeric string. Instead of Port0, referring to the first port, specify the desired SATA hard disk port.

The above commands apply to virtual machines with an AHCI (SATA) controller. The commands for virtual machines with an IDE controller are:

$ VBoxManage setextradata VM-name \
"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial"
$ VBoxManage setextradata VM-name \
"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware"
$ VBoxManage setextradata VM-name \
"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model"

For hard disks, you can mark the drive as having a non-rotational medium by using the following command:

$ VBoxManage setextradata VM-name \
"VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1"

Additional three parameters are needed for CD/DVD drives to report the vendor product data:

$ VBoxManage setextradata VM-name \
"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor"
VBoxManage setextradata VM-name \
"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product"
VBoxManage setextradata VM-name \
"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIRevision" "revision"

The vendor id is an 8 byte alphanumeric string, the product id an 16 byte alphanumeric string and the revision a 4 byte alphanumeric string. Instead of Port0, referring to the first port, specify the desired SATA hard disk port.

As an experimental feature, Oracle VM VirtualBox enables access to an iSCSI target running in a virtual machine which is configured to use Internal Networking mode. See Section 5.10, “iSCSI Servers”, Section 6.6, “Internal Networking”, and Section 8.26, “VBoxManage storageattach”.

The IP stack accessing Internal Networking must be configured in the virtual machine which accesses the iSCSI target. A free static IP and a MAC address not used by other virtual machines must be chosen. In the example below, adapt the name of the virtual machine, the MAC address, the IP configuration, and the Internal Networking name (MyIntNet) according to your needs. The following eight commands must first be issued:

$ VBoxManage setextradata VM-name \
VBoxInternal/Devices/IntNetIP/0/Trusted 1
$ VBoxManage setextradata VM-name \
VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f
$ VBoxManage setextradata VM-name \
VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1
$ VBoxManage setextradata VM-name \
VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0
$ VBoxManage setextradata VM-name \
VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet
$ VBoxManage setextradata VM-name \
VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet
$ VBoxManage setextradata VM-name \
VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/TrunkType 2
$ VBoxManage setextradata VM-name \
VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1

Finally the iSCSI disk must be attached with the --intnet option to tell the iSCSI initiator to use internal networking, as follows:

$ VBoxManage storageattach ... --medium iscsi --server 10.0.9.30 \
--target iqn.2008-12.com.sun:sampletarget --intnet

Compared to a regular iSCSI setup, the IP address of the target must be specified as a numeric IP address, as there is no DNS resolver for internal networking.

The virtual machine with the iSCSI target should be started before the VM using it is powered on. If a virtual machine using an iSCSI disk is started without having the iSCSI target powered up, it can take up to 200 seconds to detect this situation. The VM will fail to power up.

In NAT mode, the guest network interface is assigned to the IPv4 range 10.0.x.0/24 by default where x corresponds to the instance of the NAT interface +2. So x is 2 when there is only one NAT instance active. In that case the guest is assigned to the address 10.0.2.15, the gateway is set to 10.0.2.2 and the name server can be found at 10.0.2.3.

If the NAT network needs to be changed, use the following command:

$ VBoxManage modifyvm VM-name \
--natnet1 "192.168/16"

This command would reserve the network addresses from 192.168.0.0 to 192.168.254.254 for the first NAT network instance of VM-name The guest IP would be assigned to 192.168.0.15 and the default gateway could be found at 192.168.0.2.

For network booting in NAT mode, by default Oracle VM VirtualBox uses a built-in TFTP server at the IP address 10.0.2.4. This default behavior should work fine for typical remote-booting scenarios. However, it is possible to change the boot server IP and the location of the boot image with the following commands:

$ VBoxManage modifyvm VM-name \
--nattftpserver1 10.0.2.2
$ VBoxManage modifyvm VM-name \
--nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe

The Oracle VM VirtualBox NAT stack performance is often determined by its interaction with the host's TCP/IP stack and the size of several buffers, SO_RCVBUF and SO_SNDBUF. For certain setups users might want to adjust the buffer size for a better performance. This can by achieved using the following commands, where values are in kilobytes and can range from 8 to 1024:

$ VBoxManage modifyvm VM-name \
--natsettings1 16000,128,128,0,0

This example illustrates tuning the NAT settings. The first parameter is the MTU, then the size of the socket's send buffer and the size of the socket's receive buffer, the initial size of the TCP send window, and lastly the initial size of the TCP receive window. Note that specifying zero means fallback to the default value.

Each of these buffers has a default size of 64KB and default MTU is 1500.

By default, Oracle VM VirtualBox's NAT engine will route TCP/IP packets through the default interface assigned by the host's TCP/IP stack. The technical reason for this is that the NAT engine uses sockets for communication. If you want to change this behavior, you can tell the NAT engine to bind to a particular IP address instead. For example, use the following command:

$ VBoxManage modifyvm VM-name \
--natbindip1 "10.45.0.2"

After this, all outgoing traffic will be sent through the interface with the IP address 10.45.0.2. Ensure that this interface is up and running before changing the NAT bind address.

The NAT engine by default offers the same DNS servers to the guest that are configured on the host. In some scenarios, it can be desirable to hide the DNS server IPs from the guest, for example when this information can change on the host due to expiring DHCP leases. In this case, you can tell the NAT engine to act as DNS proxy using the following command:

$ VBoxManage modifyvm VM-name --natdnsproxy1 on

For resolving network names, the DHCP server of the NAT engine offers a list of registered DNS servers of the host. If for some reason you need to hide this DNS server list and use the host's resolver settings, thereby forcing the Oracle VM VirtualBox NAT engine to intercept DNS requests and forward them to host's resolver, use the following command:

$ VBoxManage modifyvm VM-name --natdnshostresolver1 on

Note that this setting is similar to the DNS proxy mode, however whereas the proxy mode just forwards DNS requests to the appropriate servers, the resolver mode will interpret the DNS requests and use the host's DNS API to query the information and return it to the guest.

VBoxManage setextradata VM-name \
"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
unique-rule-name-of-interception-rule/HostIP" IPv4

VBoxManage setextradata VM-name \
"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
unique-rule-name/HostName" hostname

VBoxManage setextradata VM-name \
"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
unique-rule-name/HostIP" IPv4

VBoxManage setextradata VM-name \
"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
unique-rule-name/HostNamePattern" hostpattern

$ VBoxManage setextradata VM-name \
"VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/all_blocked_site/HostIP" 127.0.0.1
$ VBoxManage setextradata VM-name \
"VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/all_blocked_site/HostNamePattern" "*.blocked-site.*|*.fb.org"

By default, the NAT core uses aliasing and uses random ports when generating an alias for a connection. This works well for the most protocols like SSH, FTP and so on. Though some protocols might need a more transparent behavior or may depend on the real port number the packet was sent from. You can change the NAT mode by using the following commands:

$ VBoxManage modifyvm VM-name \
--nataliasmode1 proxyonly

$ VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports

The first example disables aliasing and switches NAT into transparent mode, the second example enforces preserving of port values. These modes can be combined if necessary.

By default, Oracle VM VirtualBox keeps all sources of time visible to the guest synchronized to a single time source, the monotonic host time. This reflects the assumptions of many guest operating systems, which expect all time sources to reflect "wall clock" time. In special circumstances it may be useful however to make the time stamp counter (TSC) in the guest reflect the time actually spent executing the guest.

This special TSC handling mode can be enabled on a per-VM basis, and for best results must be used only in combination with hardware virtualization. To enable this mode use the following command:

$ VBoxManage setextradata VM-name "VBoxInternal/TM/TSCTiedToExecution" 1

To revert to the default TSC handling mode use:

$ VBoxManage setextradata VM-name "VBoxInternal/TM/TSCTiedToExecution"

Note that if you use the special TSC handling mode with a guest operating system which is very strict about the consistency of time sources you may get a warning or error message about the timing inconsistency. It may also cause clocks to become unreliable with some guest operating systems depending on how they use the TSC.

For certain purposes it can be useful to accelerate or to slow down the virtual guest clock. This can be achieved as follows:

$ VBoxManage setextradata VM-name "VBoxInternal/TM/WarpDrivePercentage" 200

The above example will double the speed of the guest clock while

$ VBoxManage setextradata VM-name "VBoxInternal/TM/WarpDrivePercentage" 50

will halve the speed of the guest clock. Note that changing the rate of the virtual clock can confuse the guest and can even lead to abnormal guest behavior. For instance, a higher clock rate means shorter timeouts for virtual devices with the result that a slightly increased response time of a virtual device due to an increased host load can cause guest failures. Note further that any time synchronization mechanism will frequently try to resynchronize the guest clock with the reference clock, which is the host clock if the Oracle VM VirtualBox Guest Additions are active. Therefore any time synchronization should be disabled if the rate of the guest clock is changed as described above. See Section 9.11.3, “Tuning the Guest Additions Time Synchronization Parameters”.

The Oracle VM VirtualBox Guest Additions ensure that the guest's system time is synchronized with the host time. There are several parameters which can be tuned. The parameters can be set for a specific VM using the following command:

$ VBoxManage guestproperty set VM-name "/VirtualBox/GuestAdd/VBoxService/property" value

property is one of the following:

All these parameters can be specified as command line parameters to VBoxService as well.

Once installed and started, the Oracle VM VirtualBox Guest Additions will try to synchronize the guest time with the host time. This can be prevented by forbidding the guest service from reading the host clock:

$ VBoxManage setextradata VM-name "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1

There are several advanced customization settings for locking down VirtualBox Manager. Locking down means removing some features that the user should not see.

VBoxManage setextradata global GUI/Customizations property[,property ...]

property is one of the following properties:

To disable any of these VirtualBox Manager customizations use the following command:

$ VBoxManage setextradata global GUI/Customizations

The following per-machine VM extradata settings can be used to change the behavior of the VM selector window in respect of certain VMs:

$ VBoxManage setextradata VM-name property true

property can be any of the following:

Note that these settings do not prevent the user from reconfiguring the VM by using the VBoxManage modifyvm command.

You can disable certain entries in the global settings page of the VM selector:

$ VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages property[,property...]

property is one of the following:

This is a global setting. You can specify any combination of properties. To restore the default behavior, use the following command:

$ VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages

You can disable certain menu actions in the VM window:

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus OPTION[,OPTION...]

where OPTION is one of the following keywords:

This is a per-VM or global setting. Any combination of the above is allowed. To restore the default behavior, use the following command:

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus

You can also disable certain menu actions of certain menus. Use the following command to disable certain actions of the Application menu. This is only available on macOS hosts.

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]

where OPTION is one of the following keywords:

This is a per-VM or global setting. Any combination of the above is allowed. To restore the default behavior, use the following command:

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus

Use the following command to disable certain actions of the Machine menu:

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMachineMenuActions OPTION[,OPTION...]

where OPTION is one of the following keywords:

This is a per-VM or global setting. Any combination of the above is allowed. To restore the default behavior, use

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMachineMenuActions

Use the following command to disable certain actions of the View menu:

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeViewMenuActions OPTION[,OPTION...]

where OPTION is one of the following keywords:

This is a per-VM or global setting. Any combination of the above is allowed. To restore the default behavior, use

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeViewMenuActions

Use the following command to disable certain actions of the Input menu:

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeInputMenuActions OPTION[,OPTION...]

where OPTION is one of the following keywords:

This is a per-VM or global setting. Any combination of the above is allowed. To restore the default behavior, use

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeInputMenuActions

Use the following command to disable certain actions of the Devices menu:

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDevicesMenuActions OPTION[,OPTION...]

where OPTION is one of the following keywords to disable actions in the Devices menu:

This is a per-VM or global or global setting. Any combination of the above is allowed. To restore the default behavior, use

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDevicesMenuActions

Use the following command to disable certain actions of the Debug menu:

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDebuggerMenuActions OPTION[,OPTION...]

where OPTION is one of the following keywords to disable actions in the Debug menu, which is normally completely disabled:

This is a per-VM or global setting. Any combination of the above is allowed. To restore the default behavior, use

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDebuggerMenuActions

Use the following command to disable certain actions of the View menu:

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeHelpMenuActions OPTION[,OPTION...]

where OPTION is one of the following keywords to disable actions in the Help menu, which is normally completely disabled:

This is a per-VM or global setting. Any combination of the above is allowed. To restore the default behavior, use

VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeHelpMenuActions

You can disable certain status bar items:

VBoxManage setextradata "VM name"|global GUI/RestrictedStatusBarIndicators OPTION[,OPTION...]

where OPTION is one of the following keywords:

This is a per-VM or global setting. Any combination of the above is allowed. If all options are specified, no icons are displayed in the status bar of the VM window. To restore the default behavior, use

VBoxManage setextradata "VM name"|global GUI/RestrictedStatusBarIndicators

You can disable certain VM visual modes:

$ VBoxManage setextradata VM-name GUI/RestrictedVisualStates property[,property...]

property is one of the following:

This is a per-VM setting. You can specify any combination of properties. To restore the default behavior, use the following command:

$ VBoxManage setextradata VM-name GUI/RestrictedVisualStates

To disable all Host key combinations, open the preferences and change the Host key to None. This might be useful when using Oracle VM VirtualBox in a kiosk mode.

To redefine or disable certain Host key actions, use the following command:

$ VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...."

The following table shows the possible Host key actions, together with their default Host key shortcut. Setting an action to None will disable that Host key action.

To disable full screen mode and seamless mode, use the following command:

$ VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"

You can disallow certain actions when terminating a VM. To disallow specific actions, use the following command:

$ VBoxManage setextradata VM-name GUI/RestrictedCloseActions property[,property...]

property is one of the following:

This is a per-VM setting. You can specify any combination of properties. If all properties are specified, the VM cannot be shut down.

You can define a specific action for terminating a VM. In contrast to the setting decribed in the previous section, this setting allows only one action when the user terminates the VM. No exit menu is shown. Use the following command:

$ VBoxManage setextradata VM-name GUI/DefaultCloseAction action

action is one of the following:

This is a per-VM setting. You can specify any combination of properties. If all properties are specified, the VM cannot be shut down.

A VM runs into a Guru Meditation if there is a problem which cannot be fixed by other means than terminating the process. The default is to show a message window which instructs the user to open a bug report.

This behavior can be configured as follows:

$ VBoxManage setextradata VM-name GUI/GuruMeditationHandler mode

mode is one of the following:

This is a per-VM setting.

By default, the mouse is captured if the user clicks on the guest window and the guest expects relative mouse coordinates at this time. This happens if the pointing device is configured as PS/2 mouse and the guest has not yet started the Oracle VM VirtualBox Guest Additions. For instance, the guest is booting or the Guest Additions are not installed, or if the pointing device is configured as a USB tablet but the guest has no USB driver loaded yet. Once the Guest Additions become active or the USB guest driver is started, the mouse capture is automatically released.

The default behavior is sometimes not desired. Therefore it can be configured as follows:

VBoxManage setextradata VM-name GUI/MouseCapturePolicy mode

mode is one of the following:

This is a per-VM setting.

Oracle VM VirtualBox uses special window manager facilities to switch a multi-screen machine to full-screen on a multi-monitor host system. However, not all window managers provide these facilities correctly. Oracle VM VirtualBox can be configured to use a legacy method of switching to full-screen mode instead, by using the command:

VBoxManage setextradata global GUI/Fullscreen/LegacyMode true

You can go back to the default method by using the following command:

VBoxManage setextradata global GUI/Fullscreen/LegacyMode

This is a global setting.

It is possible to remove networking modes from Oracle VM VirtualBox GUI. To do this, use the following command:

VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes property[,property...]

property is one of the following:

This is a global setting. You can specify any combination of properties. To restore the default behavior, use the following command:

VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes

On Linux, the web service can be automatically started during host boot by adding appropriate parameters to the file /etc/default/virtualbox. There is one mandatory parameter, VBOXWEB_USER, which must be set to the user which will later start the VMs. The parameters in the following table all start with the VBOXWEB_ prefix string. For example: VBOXWEB_HOST and VBOXWEB_PORT.

Setting the parameter SSL_KEYFILE enables the SSL/TLS support. Using encryption is strongly encouraged, as otherwise everything, including passwords, is transferred in clear text.

On Oracle Solaris hosts, the Oracle VM VirtualBox web service daemon is integrated into the SMF framework. You can change the parameters, but do not have to if the defaults below already match your needs:

svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root

The table in Section 9.18.1, “Linux: Starting the Web Service With init” showing the parameter names and defaults also applies for Oracle Solaris. The parameter names must be changed to lowercase and a prefix of config/ has to be added. For example: config/user or config/ssl_keyfile. If you make any change, do not forget to run the following command to put the changes into effect immediately:

svcadm refresh svc:/application/virtualbox/webservice:default

If you forget the above command then the previous settings are used when enabling the service. Check the current property settings as follows:

svcprop -p config svc:/application/virtualbox/webservice:default

When everything is configured correctly you can start the Oracle VM VirtualBox web service with the following command:

svcadm enable svc:/application/virtualbox/webservice:default

For more information about SMF, please refer to the Oracle Solaris documentation.

On macOS, launchd is used to start the Oracle VM VirtualBox webservice. An example configuration file can be found in $HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist. It can be enabled by changing the Disabled key from true to false. To manually start the service use the following command:

launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist

For additional information on how launchd services could be configured see:

https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html.

The memory ballooning control inflates and deflates the memory balloon of VMs based on the VMs free memory and the desired maximum balloon size.

To set up the memory ballooning control the maximum ballooning size a VM can reach needs to be set. This can be specified using the command line, as follows:

--balloon-max <Size in MB>

Using a per-VM basis extradata value, as follows:

VBoxManage setextradata <VM-Name> VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB>

Setting the ballooning increment in MB can be either done using command line, as follows:

--balloon-inc <Size in MB>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB <Size in MB>

The default ballooning increment is 256 MB if not specified.

The same options apply for a ballooning decrement. Using the command line, as follows:

--balloon-dec <Size in MB>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB <Size in MB>

The default ballooning decrement is 128 MB if not specified.

The lower limit in MB for a balloon can be defined using the command line, as follows:

--balloon-lower-limit <Size in MB>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB <Size in MB>

The default lower limit is 128 MB if not specified.

To detect whether a host is being isolated, that is, the host cannot reach the Oracle VM VirtualBox server instance anymore, the host needs to set an alternating value to a global extradata value within a time period. If this value is not set within that time period a timeout occurred and the so-called host isolation response will be performed to the VMs handled. Which VMs are handled can be controlled by defining VM groups and assigning VMs to those groups. By default no groups are set, meaning that all VMs on the server will be handled when no host response is received within 30 seconds.

Set the groups handled by the host isolation detection using the following command line:

--apimon-groups=<string[,stringN]>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups <string[,stringN]>

Set the host isolation timeout using the following command line:

--apimon-isln-timeout=<ms>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS <ms>

Set the actual host isolation response using the following command line:

--apimon-isln-response=<cmd>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse <cmd>

The following response commands are available:

For more advanced options and parameters like verbose logging check the built-in command line help accessible with --help.

On Linux, the watchdog service can be automatically started during host boot by adding appropriate parameters to the file /etc/default/virtualbox. There is one mandatory parameter, VBOXWATCHDOG_USER, which must be set to the user which will later start the VMs. For backward compatibility you can also specify VBOXBALLOONCTRL_USER.

The parameters in the following table all start with the VBOXWATCHDOG_ prefix string. For example: VBOXWATCHDOG_BALLOON_INTERVAL and VBOXWATCHDOG_LOGSIZE. Legacy parameters such as VBOXBALLOONCTRL_INTERVAL can still be used.

On Oracle Solaris hosts, the Oracle VM VirtualBox watchdog service daemon is integrated into the SMF framework. You can change the parameters, but do not have to if the defaults already match your needs:

svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \
  config/balloon_interval=10000
svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \
config/balloon_safetymargin=134217728

Table 9.3, “Oracle VM VirtualBox Watchdog Configuration Parameters” also applies for Oracle Solaris. The parameter names must be changed to lowercase and a prefix of config/ has to be added. For example: config/user or config/balloon_safetymargin. If you made any change, do not forget to run the following command to put the changes into effect immediately:

svcadm refresh svc:/application/virtualbox/balloonctrl:default

If you forget the above command then the previous settings will be used when enabling the service. Check the current property settings with the following command:

svcprop -p config svc:/application/virtualbox/balloonctrl:default

When everything is configured correctly you can start the Oracle VM VirtualBox watchdog service with the following command:

svcadm enable svc:/application/virtualbox/balloonctrl:default

For more information about SMF, please refer to the Oracle Solaris documentation.

On Linux, the autostart service is activated by setting two variables in /etc/default/virtualbox. The first one is VBOXAUTOSTART_DB which contains an absolute path to the autostart database directory. The directory should have write access for every user who should be able to start virtual machines automatically. Furthermore the directory should have the sticky bit set. The second variable is VBOXAUTOSTART_CONFIG which points the service to the autostart configuration file which is used during boot to determine whether to allow individual users to start a VM automatically and configure startup delays. The configuration file can be placed in /etc/vbox and contains several options. One is default_policy which controls whether the autostart service allows or denies to start a VM for users which are not in the exception list. The exception list starts with exception_list and contains a comma separated list with usernames. Furthermore a separate startup delay can be configured for every user to avoid overloading the host. A sample configuration is given below:

# Default policy is to deny starting a VM, the other option is "allow".
default_policy = deny

# Bob is allowed to start virtual machines but starting them
# will be delayed for 10 seconds
bob = {
    allow = true
    startup_delay = 10
}

# Alice is not allowed to start virtual machines, useful to exclude certain users
# if the default policy is set to allow.
alice = {
    allow = false
}

Any user who wants to enable autostart for individual machines must set the path to the autostart database directory with the following command:

VBoxManage setproperty autostartdbpath autostart-directory

On Oracle Solaris hosts, the Oracle VM VirtualBox autostart daemon is integrated into the SMF framework. To enable it you must point the service to an existing configuration file which has the same format as on Linux, see Section 9.21.1, “Linux: Starting the Autostart Service With init”. For example:

# svccfg -s svc:/application/virtualbox/autostart:default setprop \
  config/config=/etc/vbox/autostart.cfg

When everything is configured correctly you can start the Oracle VM VirtualBox autostart service with the following command:

# svcadm enable svc:/application/virtualbox/autostart:default

For more information about SMF, see the Oracle Solaris documentation.

On macOS, launchd is used to start the Oracle VM VirtualBox autostart service. An example configuration file can be found in /Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist. To enable the service copy the file to /Library/LaunchDaemons and change the Disabled key from true to false. Furthermore replace the second parameter to an existing configuration file which has the same format as on Linux, see Section 9.21.1, “Linux: Starting the Autostart Service With init”.

To manually start the service use the following command:

# launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist

For additional information on how launchd services can be configured see:

http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html.

On Windows, autostart functionality consist of two components. The first component is a configuration file where the administrator can both set a delayed start for the VMs and temporarily disable autostarting for a particular user. The configuration file should be located in a folder accessible by all required users but it should have permissions allowing only reading by everyone but administrators. The configuration file contains several options. The default_policy controls whether the autostart service allows or denies starting of a VM for users that are not in the exception list. The exception list starts with exception_list and contains a comma separated list with usernames. Furthermore, a separate startup delay can be configured for every user to avoid overloading the host. A sample configuration is given below:

    # Default policy is to deny starting a VM, the other option is "allow".
    default_policy = deny

    # Bob is allowed to start virtual machines but starting them
    # will be delayed for 10 seconds
    bob = {
        allow = true
        startup_delay = 10
    }

    # Alice is not allowed to start virtual machines, useful to exclude certain users
    # if the default policy is set to allow.
    alice = {
        allow = false
    }

The user name can be specified using the following forms: "user", "domain\user", ".\user" and "user@domain". An administrator must add the VBOXAUTOSTART_CONFIG environment variable into system variables containing the path to the configuration file described above. The environment variable tells the autostart services which configuration file is used.

The second component of autostart functionality is a Windows service. Every instance of this works on behalf of a particular user using their credentials.

To enable autostarting for a particular user, a member of the administrators group must run the following command:

VBoxAutostartSvc install --user=user [--password-file=password_file]

The password file should contain the password followed by a line break. The rest of the file is ignored. The user will be asked for a password if the password file is not specified.

To disable autostarting for particular user, a member of the administrators group must run the following command:

VBoxAutostartSvc delete --user=user

If a user has changed their password then a member of the administrators group must either reinstall the service or change the service credentials using Windows Service Manager. Due to Windows security policies, the autostart service cannot be installed for users with empty passwords.

Finally, the user should define which VMs should be started at boot. The user should run the following command for every VM they wish to start at boot:

VBoxManage modifyvm VM name or UUID --autostart-enabled on

The user can remove a particular VM from the VMs starting at boot by running the following command:

VBoxManage modifyvm VM name or UUID --autostart-enabled off

There are some limitations the user needs to be aware of when using this feature:

Encrypting a VM can be done either using VirtualBox Manager or the VBoxManage. To encrypt an unencrypted VM with VBoxManage, use:

VBoxManage encryptvm uuid|vmname setencryption --new-password filename|- \
--cipher cipher-ID --new-password-id ID

To supply the encryption password, point VBoxManage to the file where the password is stored or specify - to let VBoxManage prompt for the password on the command line.

The cipher parameter specifies the cipher to use for encryption and can be either AES-128 or AES-256. The appropriate mode of operation, such as GCM, CTR, or XTS will be selected by the VM depending on the encrypting component. The specified password identifier can be freely chosen by the user and is used for correct identification when supplying multiple passwords for the VM.

When Oracle VM VirtualBox has just started up the encrypted VM cannot be opened and it stays inaccessible. Also, the encrypted VM stays inaccessible if it was just registered without a password or the password is incorrect. The user needs to provide the password using VirtualBox Manager or with the following VBoxManage command:

VBoxManage encryptvm uuid|vmname addpassword --password filename|- --password-id ID

To supply the encryption password point VBoxManage to the file where the password is stored or specify - to let VBoxManage prompt for the password on the command line.

If ID is the same as the password identifier supplied when encrypting the VM it updates the accessibility state.

To remove the entered password from the VM memory, use VBoxManage as follows:

VBoxManage encryptvm uuid|vmname removepassword ID

If ID is the same as the password identifier supplied when encrypting the VM it updates the accessibility state.

In some circumstances it might be required to decrypt previously encrypted VMs. This can be done in VirtualBox Manager or using VBoxManage with the following command:

VBoxManage encryptvm uuid|vmname setencryption --old-password file|-

The only required parameter is the password the VM was encrypted with. The options are the same as for encrypting VMs.

There are some limitations the user needs to be aware of when using this feature:

Encrypting disk images can be done either using VirtualBox Manager or the VBoxManage. While VirtualBox Manager is easier to use, it works on a per VM basis and encrypts all disk images attached to the specific VM. With VBoxManage one can encrypt individual images, including all differencing images. To encrypt an unencrypted medium with VBoxManage, use:

VBoxManage encryptmedium uuid|filename \
--newpassword filename|- --cipher cipher-ID --newpasswordid "ID

To supply the encryption password point VBoxManage to the file where the password is stored or specify - to let VBoxManage ask you for the password on the command line.

The cipher parameter specifies the cipher to use for encryption and can be either AES-XTS128-PLAIN64 or AES-XTS256-PLAIN64. The specified password identifier can be freely chosen by the user and is used for correct identification when supplying multiple passwords during VM startup.

If the user uses the same password when encrypting multiple images and also the same password identifier, the user needs to supply the password only once during VM startup.

When a VM is started using VirtualBox Manager, a dialog will open where the user needs to enter all passwords for all encrypted images attached to the VM. If another frontend like VBoxHeadless is used, the VM will be paused as soon as the guest tries to access an encrypted disk. The user needs to provide the passwords through VBoxManage using the following command:

VBoxManage controlvm uuid|vmname addencpassword ID password [--removeonsuspend yes|no]

ID must be the same as the password identifier supplied when encrypting the images. password is the password used when encrypting the images. Optionally, you can specify --removeonsuspend yes|no to specify whether to remove the password from VM memory when the VM is suspended. Before the VM can be resumed, the user needs to supply the passwords again. This is useful when a VM is suspended by a host suspend event and the user does not want the password to remain in memory.

In some circumstances it might be required to decrypt previously encrypted images. This can be done in VirtualBox Manager for a complete VM or using VBoxManage with the following command:

VBoxManage encryptmedium uuid|filename --oldpassword file|-

The only required parameter is the password the image was encrypted with. The options are the same as for encrypting images.

All of the options listed below are optional, and thus the default value specified will be used when the corresponding key-value pair is not specified.

This section gives a brief overview on how to set up a Linux based system to act as a USB device server. The system on the server requires that the usbip-core.ko and usbip-host.ko kernel drivers are available, and that the USB/IP tools package is installed. The particular installation method for the necessary tools depends on which distribution is used. For example, for Debian based systems, use the following command to install the required tools:

$ apt-get install usbip-utils

To check whether the necessary tools are already installed use the following command:

$ usbip list -l
      

This should produce output similar to that shown in the example below:

 - busid 4-2 (0bda:0301)
   Realtek Semiconductor Corp. : multicard reader (0bda:0301)

 - busid 5-1 (046d:c52b)
   Logitech, Inc. : Unifying Receiver (046d:c52b)
      

If everything is installed, the USB/IP server needs to be started as root using the following command:

# usbipd -D

See the documentation for the installed distribution to determine how to start the service when the system boots.

By default, no device on the server is exported. This must be done manually for each device. To export a device use the following command:

# usbip bind -b "bus identifier"

To export the multicard reader in the previous example:

# usbip bind -b 4-2

The communication between the server and client is unencrypted and there is no authorization required to access exported devices. An attacker might sniff sensitive data or gain control over a device. To mitigate this risk, the device should be exposed over a local network to which only trusted clients have access. To access the device remotely over a public network, a VPN solution should be used to provide the required level of security protection.