Chapter 9. Advanced topics

Table of Contents

VBoxSDL, the simplified VM displayer
Introduction
Secure labeling with VBoxSDL
Releasing modifiers with VBoxSDL on Linux
Automated guest logons
Automated Windows guest logons
Automated Linux/Unix guest logons
Advanced configuration for Windows guests
Automated Windows system preparation
Advanced configuration for Linux and Solaris guests
Manual setup of selected guest services on Linux
Guest graphics and mouse driver setup in depth
CPU hot-plugging
PCI passthrough
Advanced display configuration
Custom VESA resolutions
Configuring the maximum resolution of guests when using the graphical frontend
Advanced storage configuration
Using a raw host hard disk from a guest
Configuring the hard disk vendor product data (VPD)
Access iSCSI targets via Internal Networking
Launching more than 128 VMs on Linux hosts
Launching more than 120 VMs on Solaris hosts
Temporary solution while VirtualBox is running
Persistent solution, requires user to re-login
Legacy commands for using serial ports
Fine-tuning the VirtualBox NAT engine
Configuring the address of a NAT network interface
Configuring the boot server (next server) of a NAT network interface
Tuning TCP/IP buffers for NAT
Binding NAT sockets to a specific interface
Enabling DNS proxy in NAT mode
Using the host's resolver as a DNS proxy in NAT mode
Configuring aliasing of the NAT engine
Configuring the BIOS DMI information
DMI BIOS information (type 0)
DMI system information (type 1)
DMI board information (type 2)
DMI system enclosure or chassis (type 3)
DMI processor informatiion (type 4)
DMI OEM strings (type 11)
Configuring the custom ACPI table
Fine-tuning timers and time synchronization
Configuring the guest time stamp counter (TSC) to reflect guest execution
Accelerate or slow down the guest clock
Tuning the Guest Additions time synchronization parameters
Disabling the Guest Additions time synchronization
Installing the alternate bridged networking driver on Solaris 11 hosts
VirtualBox VNIC templates for VLANs on Solaris 11 hosts
Configuring multiple host-only network interfaces on Solaris hosts
Configuring the VirtualBox CoreDumper on Solaris hosts
Locking down the VirtualBox manager GUI
GUI customization
Host Key customization
Action when terminating the VM
Starting the VirtualBox web service automatically
Linux: starting the webservice via init
Solaris: starting the web service via SMF
Mac OS X: starting the webservice via launchd
VirtualBox Watchdog
Memory ballooning control
Host isolation detection
More information
Other extension packs
Starting virtual machines during system boot
Linux: starting the autostart service via init
Solaris: starting the autostart service via SMF
Mac OS X: starting the autostart service via launchd

VBoxSDL, the simplified VM displayer

Introduction

VBoxSDL is a simple graphical user interface (GUI) that lacks the nice point-and-click support which VirtualBox, our main GUI, provides. VBoxSDL is currently primarily used internally for debugging VirtualBox and therefore not officially supported. Still, you may find it useful for environments where the virtual machines are not necessarily controlled by the same person that uses the virtual machine.

Note

VBoxSDL is not available on the Mac OS X host platform.

As you can see in the following screenshot, VBoxSDL does indeed only provide a simple window that contains only the "pure" virtual machine, without menus or other controls to click upon and no additional indicators of virtual machine activity:

To start a virtual machine with VBoxSDL instead of the VirtualBox GUI, enter the following on a command line:

VBoxSDL --startvm <vm>

where <vm> is, as usual with VirtualBox command line parameters, the name or UUID of an existing virtual machine.

Secure labeling with VBoxSDL

When running guest operating systems in full screen mode, the guest operating system usually has control over the whole screen. This could present a security risk as the guest operating system might fool the user into thinking that it is either a different system (which might have a higher security level) or it might present messages on the screen that appear to stem from the host operating system.

In order to protect the user against the above mentioned security risks, the secure labeling feature has been developed. Secure labeling is currently available only for VBoxSDL. When enabled, a portion of the display area is reserved for a label in which a user defined message is displayed. The label height in set to 20 pixels in VBoxSDL. The label font color and background color can be optionally set as hexadecimal RGB color values. The following syntax is used to enable secure labeling:

VBoxSDL --startvm "VM name"
      --securelabel --seclabelfnt ~/fonts/arial.ttf
      --seclabelsiz 14 --seclabelfgcol 00FF00 --seclabelbgcol 00FFFF

In addition to enabling secure labeling, a TrueType font has to be supplied. To use another font size than 12 point use the parameter --seclabelsiz.

The label text can be set with

VBoxManage setextradata "VM name" "VBoxSDL/SecureLabel" "The Label"

Changing this label will take effect immediately.

Typically, full screen resolutions are limited to certain "standard" geometries such as 1024 x 768. Increasing this by twenty lines is not usually feasible, so in most cases, VBoxSDL will chose the next higher resolution, e.g. 1280 x 1024 and the guest's screen will not cover the whole display surface. If VBoxSDL is unable to choose a higher resolution, the secure label will be painted on top of the guest's screen surface. In order to address the problem of the bottom part of the guest screen being hidden, VBoxSDL can provide custom video modes to the guest that are reduced by the height of the label. For Windows guests and recent Solaris and Linux guests, the VirtualBox Guest Additions automatically provide the reduced video modes. Additionally, the VESA BIOS has been adjusted to duplicate its standard mode table with adjusted resolutions. The adjusted mode IDs can be calculated using the following formula:

reduced_modeid = modeid + 0x30

For example, in order to start Linux with 1024 x 748 x 16, the standard mode 0x117 (1024 x 768 x 16) is used as a base. The Linux video mode kernel parameter can then be calculated using:

vga = 0x200 | 0x117 + 0x30
vga = 839

The reason for duplicating the standard modes instead of only supplying the adjusted modes is that most guest operating systems require the standard VESA modes to be fixed and refuse to start with different modes.

When using the X.org VESA driver, custom modelines have to be calculated and added to the configuration (usually in /etc/X11/xorg.conf. A handy tool to determine modeline entries can be found at http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html.)

Releasing modifiers with VBoxSDL on Linux

When switching from a X virtual terminal (VT) to another VT using Ctrl-Alt-Fx while the VBoxSDL window has the input focus, the guest will receive Ctrl and Alt keypress events without receiving the corresponding key release events. This is an architectural limitation of Linux. In order to reset the modifier keys, it is possible to send SIGUSR1 to the VBoxSDL main thread (first entry in the ps list). For example, when switching away to another VT and saving the virtual machine from this terminal, the following sequence can be used to make sure the VM is not saved with stuck modifiers:

kill -usr1 <pid>
VBoxManage controlvm "Windows 2000" savestate

Automated guest logons

VirtualBox provides Guest Addition modules for Windows, Linux and Solaris to enable automated logons on the guest.

When a guest operating system is running in a virtual machine, it might be desirable to perform coordinated and automated logons using credentials from a master logon system. (With "credentials", we are referring to logon information consisting of user name, password and domain name, where each value might be empty.)

Automated Windows guest logons

Since Windows NT, Windows has provided a modular system logon subsystem ("Winlogon") which can be customized and extended by means of so-called GINA modules (Graphical Identification and Authentication). With Windows Vista and Windows 7, the GINA modules were replaced with a new mechanism called "credential providers". The VirtualBox Guest Additions for Windows come with both, a GINA and a credential provider module, and therefore enable any Windows guest to perform automated logons.

To activate the VirtualBox GINA or credential provider module, install the Guest Additions with 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 VirtualBox GINA module, extract the Guest Additions (see the section called “Manual file extraction”) and copy the file VBoxGINA.dll to the Windows SYSTEM32 directory. Then, in the registry, create the following key:

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

with a value of VBoxGINA.dll.

Note

The VirtualBox GINA module is implemented as a wrapper around the standard Windows GINA module (MSGINA.DLL). As a result, it will most likely not work correctly with 3rd party GINA modules.

To manually install the VirtualBox credential provider module, extract the Guest Additions (see the section called “Manual file extraction”) and copy the file VBoxCredProv.dll to the Windows SYSTEM32 directory. Then, 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

with all default values (the key named (Default) in each key) set to VBoxCredProv. After that a new string named

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

with a value of Apartment has to be created.

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 VirtualBox logon modules (GINA or credential provider) using the VirtualBox Guest Additions device driver. When Windows is in "logged out" mode, the logon modules will constantly poll for credentials and if they are present, a logon will be attempted. After retrieving the credentials, the logon modules will erase them so that the above command will have to be repeated for subsequent logons.

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", i.e. 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 particular variant of the Windows guest, the following restrictions apply:

  1. For Windows XP guests, the logon subsystem needs to be configured to use the classic logon dialog as the VirtualBox GINA module does not support the XP-style welcome dialog.

  2. For Windows Vista and Windows 7 guests, the logon 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 (internally, Windows never renames user accounts).

  3. Auto-logon handling of the built-in Windows Remote Desktop Service (formerly known as Terminal Services) is disabled by default. To enable it, create the registry key

    HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon

    with a DWORD value of 1.

The following command forces 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.

Automated Linux/Unix guest logons

Starting with version 3.2, VirtualBox provides a custom PAM module (Pluggable Authentication Module) which can be used to perform automated guest logons on platforms which support this framework. Virtually all modern Linux/Unix distributions rely on PAM.

For automated logons on Ubuntu (or Ubuntu-derived) distributions using LightDM as the display manager, please see the section called “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.

Note

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

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>/lib/VBoxGuestAdditions/ to the security modules directory, usually /lib/security/ on 32-bit guest Linuxes or /lib64/security/ on 64-bit ones. 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 GDM (the GNOME Desktop Manager) to logon users automatically with the credentials passed by the host, the guest OS has to be configured like the following:

  1. The pam_vbox.so module has to be copied to the security modules directory, in this case it is /lib/security.

  2. Edit the PAM configuration file for GDM found at /etc/pam.d/gdm, adding the line auth requisite pam_vbox.so at the top. Additionaly, 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 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 argument tells the PAM module to use credentials already present in the stack, i.e. the ones provided by the 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 will not wait for credentials to arrive from the host, in other words: 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.

Starting with VirtualBox 4.1.4 pam_vbox supports various guest property parameters which all reside 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:

  1. 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 get deleted no waiting for credentials will be performed and pam_vbox will act like before (see paragraph above). This property must be set read-only for the guest (RDONLYGUEST).

  2. CredsWaitAbort: Aborts waiting for credentials when set to any value. Can be set from host and the guest.

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

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

  2. CredsMsgWaitTimeout: Custom message showed when waiting for credentials by pam_vbox timed out, e.g. 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 set the right flags (RDONLYGUEST) this property will be ignored then and - depending on the property - a default value will be set. This can result in pam_vbox not waiting for credentials. Consult the appropriate syslog file for more information and use the debug option.

VirtualBox Greeter for Ubuntu / LightDM

Starting with version 4.2.12, VirtualBox comes with an own greeter module named vbox-greeter which can be used with LightDM 1.0.1 or later. LightDM is the default display manager since Ubuntu 10.11 and therefore also can be used for automated guest logons.

vbox-greeter does not need the pam_vbox module described above in order to function -- it comes with its own authentication mechanism provided by LightDM. However, to provide maximum of flexibility both modules can be used together on the same guest.

As for the pam_vbox module, vbox-greeter is shipped as part of the Guest Additions but it is not installed and/or activated on the guest OS by default For installing vbox-greeter automatically upon Guest Additions installation, use the --with-autologon switch when starting the VBoxLinuxAdditions.run file:

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

For manual or postponed installation, the vbox-greeter.desktop file has to be copied from /opt/VBoxGuestAdditions-<version>/shared/VBoxGuestAdditions/ to the xgreeters directory, usually /usr/share/xgreeters/. Please refer to your guest OS documentation for the correct LightDM greeter directory.

The vbox-greeter module itself already was installed by the VirtualBox Guest Additions installer and resides in /usr/sbin/. To enable vbox-greeter as the standard greeter module, the file /etc/lightdm/lightdm.conf needs to be edited:

        [SeatDefaults]
        greeter-session=vbox-greeter

Note

The LightDM server needs to be fully restarted in order to get vbox-greeter used as the default greeter. As root, do a service lightdm --full-restart on Ubuntu, or simply restart the guest.

Note

vbox-greeter is independent of the graphical session chosen by the user (like Gnome, KDE, Unity etc). However it requires FLTK 1.3 for representing its own user interface.

There are numerous guest properties which can be used to further customize the login experience. For automatically logging in users, the same guest properties apply as for pam_vbox, see the section called “Automated Linux/Unix guest logons”.

In addition to the above mentioned guest properties, vbox-greeter allows further customization of its user interface. These special guest properties all reside in /VirtualBox/GuestAdd/Greeter/:

  1. HideRestart: Set to "1" if vbox-greeter should hide the button to restart the guest. This property must be set read-only for the guest (RDONLYGUEST).

  2. HideShutdown: Set to "1" if vbox-greeter should hide the button to shutdown the guest. This property must be set read-only for the guest (RDONLYGUEST).

  3. BannerPath: Path to a .PNG file for using it as a banner on the top. The image size must be 460 x 90 pixels, any bit depth. This property must be set read-only for the guest (RDONLYGUEST).

  4. UseTheming: Set to "1" for turning on the following theming options. This property must be set read-only for the guest (RDONLYGUEST).

  5. Theme/BackgroundColor: Hexadecimal RRGGBB color for the background. This property must be set read-only for the guest (RDONLYGUEST).

  6. Theme/LogonDialog/HeaderColor: Hexadecimal RRGGBB foreground color for the header text. This property must be set read-only for the guest (RDONLYGUEST).

  7. Theme/LogonDialog/BackgroundColor: Hexadecimal RRGGBB color for the logon dialog background. This property must be set read-only for the guest (RDONLYGUEST).

  8. Theme/LogonDialog/ButtonColor: Hexadecimal RRGGBB background color for the logon dialog button. This property must be set read-only for the guest (RDONLYGUEST).

Note

The same restrictions for the guest properties above apply as for the ones specified in the pam_vbox section.

Advanced configuration for Windows guests

Automated Windows system preparation

Beginning with Windows NT 4.0, Microsoft offers a "system preparation" tool (in short: Sysprep) to prepare a Windows system for deployment or redistribution. Whereas Windows 2000 and XP ship with Sysprep on the installation medium, the tool also is available for download on the Microsoft web site. In a standard installation of Windows Vista and 7, Sysprep is already included. Sysprep mainly consists of an executable called sysprep.exe which is invoked by the user to put the Windows installation into preparation mode.

Starting with VirtualBox 3.2.2, 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. To achieve that, see the section called “Guest control” for using the feature with the special identifier sysprep as the program to execute, along with the user name sysprep and password sysprep for the credentials. Sysprep then gets launched with the required system rights.

Note

Specifying the location of "sysprep.exe" is not possible -- instead the following paths are used (based on the operating system):

  • C:\sysprep\sysprep.exe for Windows NT 4.0, 2000 and XP

  • %WINDIR%\System32\Sysprep\sysprep.exe for Windows Vista, 2008 Server and 7

The Guest Additions will automatically use the appropriate path to execute the system preparation tool.

Advanced configuration for Linux and Solaris guests

Manual setup of selected guest services on Linux

The VirtualBox Guest Additions contain several different drivers. If for any reason you do not wish to set them all up, you can install the Guest Additions using the following command:

  sh ./VBoxLinuxAdditions.run no_setup

After this, you will need to at least compile the kernel modules by running the command

  /usr/lib/VBoxGuestAdditions/vboxadd setup

as root (you will need to replace lib by lib64 on some 64bit guests), and on older guests without the udev service you will need to add the vboxadd service to the default runlevel to ensure that the modules get loaded.

To setup the time synchronization service, run the command

  /usr/lib/VBoxGuestAdditions/vboxadd-service setup

and add the service vboxadd-service to the default runlevel. To set up the X11 and OpenGL part of the Guest Additions, run the command

  /usr/lib/VBoxGuestAdditions/vboxadd-x11 setup

(you do not need to enable any services for this).

To recompile the guest kernel modules, use this command:

  /usr/lib/VBoxGuestAdditions/vboxadd setup

After compilation you should reboot your guest to ensure that the new modules are actually used.

Guest graphics and mouse driver setup in depth

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 VirtualBox Guest Additions come with drivers for X.Org versions

  • X11R6.8/X11R6.9 and XFree86 version 4.3 (vboxvideo_drv_68.o and vboxmouse_drv_68.o)
  • X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so)
  • X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so)
  • X.Org Server versions 1.3 and later (vboxvideo_drv_13.so and vboxmouse_drv_13.so and so on).

By default these drivers can be found in the directory

/opt/VBoxGuestAdditions-<version>/lib/VBoxGuestAdditions

and 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 VirtualBox) and 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 and in addition, in X servers from X.Org X11R6.8 to X11R7.1 and in XFree86 version 4.3 the right vboxmouse driver must be loaded and associated with /dev/mouse or /dev/psaux; in X.Org server 1.3 or later a driver for a PS/2 mouse must be loaded and the right vboxmouse driver must be associated with /dev/vboxguest.

The 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 the section called “Display settings”. The driver will offer a range of standard modes at least up to the default guest resolution for all active guest monitors. In X.Org Server 1.3 and later 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 pre-1.3 X Servers you can also add your own modes to the X server configuration file. You simply need to add them to the "Modes" list in the "Display" subsection of the "Screen" section. For example, the section shown here 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

CPU hot-plugging

With virtual machines running modern server operating systems, VirtualBox supports CPU hot-plugging.[38] Whereas on a physical computer this would mean that a CPU can be added or removed while the machine is running, VirtualBox supports adding and removing virtual CPUs while a virtual machine is running.

CPU hot-plugging works only with guest operating systems that support it. So far this applies only to Linux and Windows Server 2008 x64 Data Center Edition. Windows supports only hot-add while Linux supports hot-add and hot-remove but to use this feature with more than 8 CPUs a 64bit Linux guest is required.

At this time, CPU hot-plugging requires using the VBoxManage command-line interface. First, hot-plugging needs to be enabled for a virtual machine:

VBoxManage modifyvm "VM name" --cpuhotplug on

After that, the --cpus option specifies the maximum number of CPUs that the virtual machine can have:

VBoxManage modifyvm "VM name" --cpus 8

When the VM is off, you can then add and remove virtual CPUs with the modifyvm --plugcpu and --unplugcpu subcommands, which take the number of the virtual CPU as a parameter, like this:

VBoxManage modifyvm "VM name" --plugcpu 3
VBoxManage modifyvm "VM name" --unplugcpu 3

Note that CPU 0 can never be removed.

While the VM is running, CPUs can be added with the controlvm plugcpu/unplugcpu commands instead:

VBoxManage controlvm "VM name" plugcpu 3
VBoxManage controlvm "VM name" unplugcpu 3

See the section called “VBoxManage modifyvm” and the section called “VBoxManage controlvm” for details.

With Linux guests, the following applies: To prevent ejection while the CPU is still used it has to be ejected from within the guest before. The Linux Guest Additions contain a service which receives hot-remove events and ejects the CPU. Also, after a CPU is added to the VM it is not automatically used by Linux. The Linux Guest Additions service will take care of that if installed. If not a CPU can be started with the following command:

echo 1 > /sys/devices/system/cpu/cpu<id>/online

PCI passthrough

When running on Linux hosts, with a recent enough kernel (at least version 2.6.31) experimental host PCI devices passthrough is available.[39]

Note

The PCI passthrough module is shipped as a VirtualBox extension package, which must be installed separately. See the section called “Installing VirtualBox and extension packs” for more information.

Essentially this feature allows to directly use physical PCI devices on the host by the guest even if host doesn't have drivers for this particular device. Both, regular PCI and some PCI Express cards, are supported. AGP and certain PCI Express cards are not supported at the moment if they rely on GART (Graphics Address Remapping Table) unit programming for texture management as it does rather nontrivial operations with pages remapping interfering with IOMMU. This limitation may be lifted in future releases.

To be fully functional, PCI passthrough support in VirtualBox depends upon an IOMMU hardware unit which is not yet too widely available. If the device uses bus mastering (i.e. it performs DMA to the OS memory on its own), then an IOMMU is required, otherwise such DMA transactions may write to the wrong physical memory address as the device DMA engine is programmed using a device-specific protocol to perform memory transactions. The IOMMU functions as translation unit mapping physical memory access requests from the device using knowledge of the guest physical address to host physical addresses translation rules.

Intel's solution for IOMMU is marketed as "Intel Virtualization Technology for Directed I/O" (VT-d), and AMD's one is called AMD-Vi. So please check if your motherboard datasheet has appropriate technology. Even if your hardware doesn't have a IOMMU, certain PCI cards may work (such as serial PCI adapters), but the guest will show a warning on boot and the VM execution will terminate if the guest driver will attempt to enable card bus mastering.

It is very common that the BIOS or the host OS disables the IOMMU by default. So before any attempt to use it please make sure that

  1. Your motherboard has an IOMMU unit.

  2. Your CPU supports the IOMMU.

  3. The IOMMU is enabled in the BIOS.

  4. The VM must run with VT-x/AMD-V and nested paging enabled.

  5. Your Linux kernel was compiled with IOMMU support (including DMA remapping, see CONFIG_DMAR kernel compilation option). The PCI stub driver (CONFIG_PCI_STUB) is required as well.

  6. Your Linux kernel recognizes and uses the IOMMU unit (intel_iommu=on boot option could be needed). Search for DMAR and PCI-DMA in kernel boot log.

Once you made sure that the host kernel supports the IOMMU, the next step is to select the PCI card and attach it to the guest. To figure out the list of available PCI devices, use the lspci command. The output will look like this

        01:00.0 VGA compatible controller: ATI Technologies Inc Cedar PRO [Radeon HD 5450]
        01:00.1 Audio device: ATI Technologies Inc Manhattan HDMI Audio [Mobility Radeon HD 5000 Series]
        02:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168B PCI Express Gigabit Ethernet controller (rev 03)
        03:00.0 SATA controller: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
        03:00.1 IDE interface: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
        06:00.0 VGA compatible controller: nVidia Corporation G86 [GeForce 8500 GT] (rev a1)
      

The first column is a PCI address (in format bus:device.function). This address could be used to identify the device for further operations. For example, to attach a PCI network controller on the system listed above to the second PCI bus in the guest, as device 5, function 0, use the following command:

VBoxManage modifyvm "VM name" --pciattach 02:00.0@01:05.0

To detach same device, use

VBoxManage modifyvm "VM name" --pcidetach 02:00.0

Please note that both host and guest could freely assign a different PCI address to the card attached during runtime, so those addresses only apply to the address of the card at the moment of attachment (host), and during BIOS PCI init (guest).

If the virtual machine has a PCI device attached, certain limitations apply:

  1. Only PCI cards with non-shared interrupts (such as using MSI on host) are supported at the moment.
  2. No guest state can be reliably saved/restored (as the internal state of the PCI card could not be retrieved).
  3. Teleportation (live migration) doesn't work (for the same reason).
  4. No lazy physical memory allocation. The host will preallocate the whole RAM required for the VM on startup (as we cannot catch physical hardware accesses to the physical memory).

Advanced display configuration

Custom VESA resolutions

Apart from the standard VESA resolutions, the VirtualBox VESA BIOS allows you to add up to 16 custom video modes which will be reported to the guest operating system. When using Windows guests with the 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 CustomVideoMode<x> 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 be supplied to Linux:

vga = 0x200 | 0x160
vga = 864

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

Configuring the maximum resolution of guests when using the graphical frontend

When guest systems with the Guest Additions installed are started using the graphical frontend (the normal 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, it is possible to change it by issuing one of the following commands from the command line:

VBoxManage setextradata global GUI/MaxGuestResolution any

will remove all limits on guest resolutions.

VBoxManage setextradata global GUI/MaxGuestResolution >width,height<

manually specifies a maximum resolution.

VBoxManage setextradata global GUI/MaxGuestResolution auto

restores the default settings. Note that these settings apply globally to all guest systems, not just to a single machine.

Advanced storage configuration

Using a raw host hard disk from a guest

Starting with version 1.4, as an alternative to using virtual disk images (as described in detail in Chapter 5, Virtual storage), VirtualBox can also present either entire physical hard disks or selected partitions thereof as virtual disks to virtual machines.

With VirtualBox, this type of access is called "raw hard disk access"; it allows 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 vs. 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, i.e. whether the virtual disk contains all data written before a host OS crash. Consult your host OS documentation for details on this.

Warning

Raw hard disk access is for expert users only. Incorrect use or use of an outdated configuration can lead to total loss of data on the physical disk. Most importantly, do not attempt to boot the partition with the currently running host operating system in a guest. This will lead to severe data corruption.

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 VirtualBox Manager (the section called “The Virtual Media Manager”) or VBoxManage to assign the image to a virtual machine.

Access to entire physical hard disk

While this variant is the simplest to set up, you must be aware that this will give a guest operating system direct and full access to an entire physical disk. If your host operating system is also booted from this disk, please take special care to not access the partition from the guest at all. On the positive side, the physical disk can be repartitioned in arbitrary ways without having to recreate the image file that gives access to the raw disk.

To create an image that represents an entire physical hard disk (which will not contain any actual data, as this will all be stored on the physical disk), on a Linux host, use the command

VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
      -rawdisk /dev/sda

This creates the image /path/to/file.vmdk (must be absolute), and all data will be read and written from /dev/sda.

On a Windows host, instead of the above device specification, use e.g. \\.\PhysicalDrive0. On a Mac OS X host, instead of the above device specification use e.g. /dev/disk1. Note that on OS X you can only get access to an entire disk if no volume is mounted from it.

Creating the image requires read/write access for the given device. Read/write access is also later needed when using the image from a virtual machine. On some host platforms (e.g. Windows Vista and later), raw disk access may be restricted and not permitted by the host OS in some situations.

Just like with regular disk images, this does not automatically attach the newly created image to a virtual machine. This can be done with e.g.

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

When this is done the selected virtual machine will boot from the specified physical disk.

Access to individual physical hard disk partitions

This "raw partition support" is quite similar to the "full hard disk" access described above. However, in this case, any partitioning information will be stored inside the VMDK image, so you can e.g. install a different boot loader in the virtual hard disk without affecting the host's partitioning information. While the guest will be able to see all partitions that exist on the physical disk, access will be filtered in that reading from partitions for which no access is allowed the partitions will only yield zeroes, and all writes to them are ignored.

To create a special image for raw partition support (which will contain a small amount of data, as already mentioned), on a Linux host, use the command

VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
      -rawdisk /dev/sda -partitions 1,5

As you can see, the command is identical to the one for "full hard disk" access, except for the additional -partitions parameter. This example would create the image /path/to/file.vmdk (which, again, must be absolute), and partitions 1 and 5 of /dev/sda would be made accessible to the guest.

VirtualBox uses the same partition numbering as your Linux host. As a result, the numbers given in the above example would refer to the first primary partition and the first logical drive in the extended partition, respectively.

On a Windows host, instead of the above device specification, use e.g. \\.\PhysicalDrive0. On a Mac OS X host, instead of the above device specification use e.g. /dev/disk1. Note that on OS X you can only use partitions which are not mounted (eject the respective volume first). Partition numbers are the same on Linux, Windows and Mac OS X hosts.

The numbers for the list of partitions can be taken from the output of

VBoxManage internalcommands listpartitions -rawdisk /dev/sda

The output lists the partition types and sizes to give the user enough information to identify the partitions necessary for the guest.

Images which give access to individual partitions are specific to a particular host disk setup. You cannot transfer these images to another host; also, whenever the host partitioning changes, the image must be recreated.

Creating the image requires read/write access for the given device. Read/write access is also later needed when using the image from a virtual machine. If this is not feasible, there is a special variant for raw partition access (currently only available on Linux hosts) that avoids having to give the current user access to the entire disk. To set up such an image, use

VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
      -rawdisk /dev/sda -partitions 1,5 -relative

When used from a virtual machine, the image will then refer not to the entire disk, but only to the individual partitions (in the example /dev/sda1 and /dev/sda5). As a consequence, read/write access is only required for the affected partitions, not for the entire disk. During creation however, read-only access to the entire disk is required to obtain the partitioning information.

In some configurations it may be necessary to change the MBR code of the created image, e.g. to replace the Linux boot loader that is used on the host by another boot loader. This allows e.g. the guest to boot directly to Windows, while the host boots Linux from the "same" disk. For this purpose the -mbr parameter is provided. It specifies a file name from which to take the MBR code. The partition table is not modified at all, so a MBR file from a system with totally different partitioning can be used. An example of this is

VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
      -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr

The modified MBR will be stored inside the image, not on the host disk.

The created image can be attached to a storage controller in a VM configuration as usual.

Configuring the hard disk vendor product data (VPD)

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 it's also possible to mark the drive as having a non-rotational medium with:

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.

Access iSCSI targets via Internal Networking

As an experimental feature, VirtualBox allows for accessing an iSCSI target running in a virtual machine which is configured for using Internal Networking mode. Please see the section called “iSCSI servers”; the section called “Internal networking”; and the section called “VBoxManage storageattach” for additional information.

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 seven 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/IsService 1

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

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

Compared to a "regular" iSCSI setup, 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.

Launching more than 128 VMs on Linux hosts

Linux hosts have a fixed number of IPC semaphores IDs per process preventing users from starting substantially many VMs. The exact number may vary with each Linux distribution. While trying to launch more VMs you would be shown a "Cannot create IPC semaphore" error. In order to run more VMs, you will need to increase the semaphore ID limit of the VBoxSVC process. Find the current semaphore limits imposed by the kernel by executing as root:

#/sbin/sysctl kernel.sem
kernel.sem = 250  32000  32  128

The "kernel.sem" parameter bundles together 4 values, the one we are interested in is called "SEMMNI", the maximum number of semaphore IDs which is 128 in the above example. Increase this semaphore ID limit by executing as root:

echo "kernel.sem = 250 32000 32 2048" >> /etc/sysctl.conf
/sbin/sysctl -p

The above commands will add the new limits to the config file, thus making the effect persistent across reboots, and will activate the new limits into the currently running kernel.

Launching more than 120 VMs on Solaris hosts

Solaris hosts have a fixed number of IPC semaphores IDs per process preventing users from starting more than 120 VMs. While trying to launch more VMs you would be shown a "Cannot create IPC semaphore" error. In order to run more VMs, you will need to increase the semaphore ID limit of the VBoxSVC process.

Temporary solution while VirtualBox is running

Execute as root the prctl command as shown below for the currently running VBoxSVC process. The process ID of VBoxSVC can be obtained using the ps command.

prctl -r -n project.max-sem-ids -v 2048 <pid-of-VBoxSVC>

This will immediately increase the semaphore limit of the currently running VBoxSVC process and allow you to launch more VMs. However, this change is not persistent and will be lost when VBoxSVC terminates.

Persistent solution, requires user to re-login

If the user running VirtualBox is root, execute the following command:

prctl -n project.max-sem-ids -v 2048 -r -i project user.root

From this point, starting new processes will have the increased limit of 2048. You may then re-login or close all VMs and restart VBoxSVC. You can check the current VBoxSVC semaphore ID limit using the following command:

prctl -n project.max-sem-ids -i process <pid-of-VBoxSVC>

If the user running VirtualBox is not root, you must add the property to the user's default project. Create the default project and set the limit by executing as root:

projadd -U <username> user.<username>
projmod -s -K "project.max-sem-ids=(priv,2048,deny)" user.<username>

Substitute "<username>" with the name of the user running VirtualBox. Then re-login as this user to be able to run more than 120 VMs.

Legacy commands for using serial ports

Starting with version 1.4, VirtualBox provided support for virtual serial ports, which, at the time, was rather complicated to set up with a sequence of VBoxManage setextradata statements. Since version 1.5, that way of setting up serial ports is no longer necessary and deprecated. To set up virtual serial ports, use the methods now described in the section called “Serial ports”.

Note

For backwards compatibility, the old setextradata statements, whose description is retained below from the old version of the manual, take precedence over the new way of configuring serial ports. As a result, if configuring serial ports the new way doesn't work, make sure the VM in question does not have old configuration data such as below still active.

The old sequence of configuring a serial port used the following 6 commands:

VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/serial/0/Config/IRQ" 4
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/serial/0/Config/IOBase" 0x3f8
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/serial/0/LUN#0/Driver" Char
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Driver" NamedPipe
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/Location" "\\.\pipe\vboxCOM1"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/IsServer" 1

This sets up a serial port in the guest with the default settings for COM1 (IRQ 4, I/O address 0x3f8) and the Location setting assumes that this configuration is used on a Windows host, because the Windows named pipe syntax is used. Keep in mind that on Windows hosts a named pipe must always start with \\.\pipe\. On Linux the same config settings apply, except that the path name for the Location can be chosen more freely. Local domain sockets can be placed anywhere, provided the user running VirtualBox has the permission to create a new file in the directory. The final command above defines that VirtualBox acts as a server, i.e. it creates the named pipe itself instead of connecting to an already existing one.

Fine-tuning the VirtualBox NAT engine

Configuring the address of a NAT network interface

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, for any reason, the NAT network needs to be changed, this can be achieved with 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.

Configuring the boot server (next server) of a NAT network interface

For network booting in NAT mode, by default VirtualBox uses a built-in TFTP server at the IP address 10.0.2.3. 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

Tuning TCP/IP buffers for NAT

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

Binding NAT sockets to a specific interface

By default, 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, for some reason, you want to change this behavior, you can tell the NAT engine to bind to a particular IP address instead. 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. Please make sure that this interface is up and running prior to this assignment.

Enabling DNS proxy in NAT mode

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

Using the host's resolver as a DNS proxy in NAT mode

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

User-defined host name resolving

In some cases it might be useful to intercept the name resolving mechanism, providing a user-defined IP address on a particular DNS request. The intercepting mechanism allows the user to map not only a single host but domains and even more complex namings conventions if required.

The following command sets a rule for mapping a name to a specified IP:

VBoxManage setextradata "VM name" \
      "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
      <uniq name of interception rule>/HostIP" <IPv4>
VBoxManage setextradata "VM name" \
      "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
      <uniq name of interception rule>/HostName" <name of host>

The following command sets a rule for mapping a pattern name to a specified IP:

VBoxManage setextradata "VM name" \
      "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
      <uniq name of interception rule>/HostIP" <IPv4>
VBoxManage setextradata "VM name" \
      "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
      <uniq name of interception rule>/HostNamePattern" <hostpattern>

The host pattern may include "|", "?" and "*".

This example demonstrates how to instruct the host-resolver mechanism to resolve all domain and probably some mirrors of www.blocked-site.info site with IP 127.0.0.1:

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

Note

The host resolver mechanism should be enabled to use user-defined mapping rules (please see the section called “Using the host's resolver as a DNS proxy in NAT mode” for more details).

Configuring aliasing of the NAT engine

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. It is possible to change the NAT mode via the VBoxManage frontend with the following commands:

VBoxManage modifyvm "VM name" --nataliasmode1 proxyonly

and

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.

Configuring the BIOS DMI information

The DMI data VirtualBox provides to guests can be changed for a specific VM. Use the following commands to configure the DMI BIOS information:

DMI BIOS information (type 0)

VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor"        "BIOS Vendor"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion"       "BIOS Version"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate"   "BIOS Release Date"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor"  1
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor"  2
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4

DMI system information (type 1)

VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor"      "System Vendor"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct"     "System Product"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion"     "System Version"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial"      "System Serial"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU"         "System SKU"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily"      "System Family"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid"
                                               "9852bf98-b83c-49db-a8de-182c42c7226b"

DMI board information (type 2)

VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVendor"       "Board Vendor"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardProduct"      "Board Product"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVersion"      "Board Version"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardSerial"       "Board Serial"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardAssetTag"     "Board Tag"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardLocInChass"   "Board Location"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardType"         10

DMI system enclosure or chassis (type 3)

VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVendor"     "Chassis Vendor"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVersion"    "Chassis Version"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiChassisSerial"     "Chassis Serial"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiChassisAssetTag"   "Chassis Tag"

DMI processor informatiion (type 4)

VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiProcManufacturer"  "GenuineIntel"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiProcVersion"       "Pentium(R) III"

DMI OEM strings (type 11)

VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxVer"        "vboxVer_1.2.3"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxRev"        "vboxRev_12345"

If a DMI string is not set, the default value of VirtualBox is used. To set an empty string use "<EMPTY>".

Note that in the above list, all quoted parameters (DmiBIOSVendor, DmiBIOSVersion but not DmiBIOSReleaseMajor) are expected to be strings. If such a string is a valid number, the parameter is treated as number and the VM will most probably refuse to start with an VERR_CFGM_NOT_STRING error. In that case, use "string:<value>", for instance

VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial"      "string:1234"

Changing this information can be necessary to provide the DMI information of the host to the guest to prevent Windows from asking for a new product key. On Linux hosts the DMI BIOS information can be obtained with

dmidecode -t0

and the DMI system information can be obtained with

dmidecode -t1

Configuring the custom ACPI table

VirtualBox can be configured to present an custom ACPI table to the guest. Use the following command to configure this:

VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/acpi/0/Config/CustomTable" "/path/to/table.bin"

Configuring a custom ACPI table can prevent Windows Vista and Windows 7 from asking for a new product key. On Linux hosts, one of the host tables can be read from /sys/firmware/acpi/tables/.

Fine-tuning timers and time synchronization

Configuring the guest time stamp counter (TSC) to reflect guest execution

By default, 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 TSC (time stamp counter) 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.

Accelerate or slow down the guest clock

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 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 the section called “Tuning the Guest Additions time synchronization parameters”).

Tuning the Guest Additions time synchronization parameters

The 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/PARAMETER" VALUE

where PARAMETER is one of the following:

--timesync-interval

Specifies the interval at which to synchronize the time with the host. The default is 10000 ms (10 seconds).

--timesync-min-adjust

The minimum absolute drift value measured in milliseconds to make adjustments for. The default is 1000 ms on OS/2 and 100 ms elsewhere.

--timesync-latency-factor

The factor to multiply the time query latency with to calculate the dynamic minimum adjust time. The default is 8 times, that means in detail: Measure the time it takes to determine the host time (the guest has to contact the VM host service which may take some time), multiply this value by 8 and do an adjustment only if the time difference between host and guest is bigger than this value. Don't do any time adjustment otherwise.

--timesync-max-latency

The max host timer query latency to accept. The default is 250 ms.

--timesync-set-threshold

The absolute drift threshold, given as milliseconds where to start setting the time instead of trying to smoothly adjust it. The default is 20 minutes.

--timesync-set-start

Set the time when starting the time sync service.

--timesync-set-on-restore 0|1

Set the time after the VM was restored from a saved state when passing 1 as parameter (default). Disable by passing 0. In the latter case, the time will be adjusted smoothly which can take a long time.

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

Disabling the Guest Additions time synchronization

Once installed and started, the 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

Installing the alternate bridged networking driver on Solaris 11 hosts

Starting with VirtualBox 4.1, VirtualBox ships a new network filter driver that utilizes Solaris 11's Crossbow functionality. By default, this new driver is installed for Solaris 11 hosts (builds 159 and above) that has support for it.

To force installation of the older STREAMS based network filter driver, execute as root the following command before installing the VirtualBox package:

touch /etc/vboxinst_vboxflt

To force installation of the Crossbow based network filter driver, execute as root the following command before installing the VirtualBox package:

touch /etc/vboxinst_vboxbow

To check which driver is currently being used by VirtualBox, execute:

modinfo | grep vbox

If the output contains "vboxbow", it indicates VirtualBox is using the Crossbow network filter driver, while the name "vboxflt" indicates usage of the older STREAMS network filter.

VirtualBox VNIC templates for VLANs on Solaris 11 hosts

VirtualBox supports VNIC (Virtual Network Interface) templates for configuring VMs over VLANs.[40] A VirtualBox VNIC template is a VNIC whose name starts with "vboxvnic_template".

Here is an example of how to use a VNIC template to configure a VLAN for VMs. Create a VirtualBox VNIC template, by executing as root:

dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0

This will create a temporary VNIC over interface "nge0" with the VLAN ID 23. To create VNIC templates that are persistent across host reboots, skip the -t parameter in the above command. You may check the current state of links using:

$ dladm show-link
LINK        CLASS     MTU    STATE    BRIDGE     OVER
nge0        phys      1500   up       --         --
nge1        phys      1500   down     --         --
vboxvnic_template0 vnic 1500 up       --         nge0

$ dladm show-vnic
LINK         OVER         SPEED  MACADDRESS        MACADDRTYPE         VID
vboxvnic_template0 nge0   1000   2:8:20:25:12:75   random              23

Once the VNIC template is created, all VMs that need to be part of VLAN 23 over the physical interface "nge0" can use the same VNIC template. This makes managing VMs on VLANs simpler and efficient, as the VLAN details are not stored as part of every VM's configuration but rather picked from the VNIC template which can be modified anytime using dladm. Apart from the VLAN ID, VNIC templates can be created with additional properties such as bandwidth limits, CPU fanout etc. Refer to your Solaris network documentation on how to accomplish this. These additional properties, if any, are also applied to VMs which use the VNIC template.

Configuring multiple host-only network interfaces on Solaris hosts

By default VirtualBox provides you with one host-only network interface. Adding more host-only network interfaces on Solaris hosts requires manual configuration. Here's how to add two more host-only network interfaces.

You first need to stop all running VMs and unplumb all existing "vboxnet" interfaces. Execute the following commands as root:

ifconfig vboxnet0 unplumb

Once you make sure all vboxnet interfaces are unplumbed, remove the driver using:

rem_drv vboxnet

then edit the file /platform/i86pc/kernel/drv/vboxnet.conf and add a line for the new interfaces:

name="vboxnet" parent="pseudo" instance=1;
name="vboxnet" parent="pseudo" instance=2;

Add as many of these lines as required and make sure "instance" number is uniquely incremented. Next reload the vboxnet driver using:

add_drv vboxnet

Now plumb all the interfaces using ifconfig vboxnetX plumb (where X can be 0, 1 or 2 in this case) and once plumbed you can then configure the interface like any other network interface.

To make your newly added interfaces' settings persistent across reboots you will need to edit the files /etc/netmasks, and if you are using NWAM /etc/nwam/llp and add the appropriate entries to set the netmask and static IP for each of those interfaces. The VirtualBox installer only updates these configuration files for the one "vboxnet0" interface it creates by default.

Configuring the VirtualBox CoreDumper on Solaris hosts

VirtualBox is capable of producing its own core files for extensive debugging when things go wrong. Currently this is only available on Solaris hosts.

The VirtualBox CoreDumper can be enabled using the following command:

VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpEnabled 1

You can specify which directory to use for core dumps with this command:

VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir <path-to-directory>

Make sure the directory you specify is on a volume with sufficient free space and that the VirtualBox process has sufficient permissions to write files to this directory. If you skip this command and don't specify any core dump directory, the current directory of the VirtualBox executable will be used (which would most likely fail when writing cores as they are protected with root permissions). It is recommended you explicitly set a core dump directory.

You must specify when the VirtualBox CoreDumper should be triggered. This is done using the following commands:

VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpReplaceSystemDump 1
VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpLive 1

At least one of the above two commands will have to be provided if you have enabled the VirtualBox CoreDumper.

Setting CoreDumpReplaceSystemDump sets up the VM to override the host's core dumping mechanism and in the event of any crash only the VirtualBox CoreDumper would produce the core file.

Setting CoreDumpLive sets up the VM to produce cores whenever the VM process receives a SIGUSR2 signal. After producing the core file, the VM will not be terminated and will continue to run. You can thus take cores of the VM process using:

kill -s SIGUSR2 <VM-process-id>

Core files produced by the VirtualBox CoreDumper are of the form core.vb.<ProcessName>.<ProcessID>, for example core.vb.VBoxHeadless.11321.

Locking down the VirtualBox manager GUI

GUI customization

GUI customization

There are several advanced customization settings for locking down the VirtualBox manager, that is, removing some features that the user should not see.

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

where OPTION is one of the following keywords:

noSelector

Don't allow to start the VirtualBox manager. Trying to do so will show a window containing a proper error message.

noMenuBar

VM windows will not contain a menu bar.

noStatusBar

VM windows will not contain a status bar.

To disable any GUI customization do

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 SETTING true

where SETTING can be:

GUI/HideDetails

Don't show the VM configuration of a certain VM. The details window will remain just empty if this VM is selected.

GUI/PreventReconfiguration

Don't allow the user to open the settings dialog for a certain VM.

GUI/HideFromManager

Hide a certain VM in the VM selector window.

Please note that these settings wouldn't prevent the user from reconfiguring the VM by VBoxManage modifyvm.

Host Key customization

To disable all host key combinations, open the preferences and change the host key to None. This might be useful when using 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 list shows the possible host key actions together with their default host key shortcut. Setting an action to None will disable that host key action.

Table 9.1. ignoreme

ActionDefault Host KeyAction
SettingsDialogSopen the VM settings dialog
TakeSnapshotStake a snapshot
InformationsDialogNshow the VM information dialog
MouseIntegrationItoggle mouse integration
TypeCADDelinject Ctrl+Alt+Del
TypeCABSBackspaceinject Ctrl+Alt+Backspace
PausePPause the VM
ResetR(hard) reset the guest
ShutdownHpress the ACPI power button
CloseQshow the VM close dialog
FullscreenModeFswitch the VM into fullscreen
SeamlessModeLswitch the VM into seamless mode
ScaleModeCswitch the VM into scale mode
PopupMenuHomeshow popup menu in fullscreen / seamless mode

To disable the fullscreen mode as well as the seamless mode, use the following command:

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

Action when terminating the VM

You can disallow certain actions when terminating a VM. To disallow specific actions, type:

VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...]

where OPTION is one of the following keywords:

SaveState

Don't allow the user to save the VM state when terminating the VM.

Shutdown

Don't allow the user to shutdown the VM by sending the ACPI power-off event to the guest.

PowerOff

Don't allow the user to power off the VM.

Restore

Don't allow the user to return to the last snapshot when powering off the VM.

Any combination of the above is allowed. If all options are specified, the VM cannot be shut down at all.

Starting the VirtualBox web service automatically

The VirtualBox web service (vboxwebsrv) is used for controlling VirtualBox remotely. It is documented in detail in the VirtualBox Software Development Kit (SDK); please see Chapter 11, VirtualBox programming interfaces. As the client base using this interface is growing, we added start scripts for the various operation systems we support. The following sections describe how to use them. The VirtualBox web service is never started automatically as a result of a standard installation.

Linux: starting the webservice via init

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 paramters in the table below all start with VBOXWEB_ (VBOXWEB_HOST, VBOXWEB_PORT etc.):

Table 9.2. ignored

ParameterDescriptionDefault
USERThe user as which the web service runs 
HOSTThe host to bind the web service tolocalhost
PORTThe port to bind the web service to18083
SSL_KEYFILEServer key and certificate file, PEM format 
SSL_PASSWORDFILEFile name for password to server key 
SSL_CACERTCA certificate file, PEM format 
SSL_CAPATHCA certificate path 
SSL_DHFILEDH file name or DH key length in bits 
SSL_RANDFILEFile containing seed for random number generator 
TIMEOUTSession timeout in seconds; 0 disables timeouts300
CHECK_INTERVALFrequency of timeout checks in seconds5
THREADSMaximum number of worker threads to run in parallel100
KEEPALIVEMaximum number of requests before a socket will be closed100
ROTATENumber of log files; 0 disables log rotation10
LOGSIZEMaximum size of a log file in bytes to trigger rotation1MB
LOGINTERVALMaximum time interval in seconds to trigger log rotation1 day

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.

Solaris: starting the web service via SMF

On Solaris hosts, the VirtualBox web service daemon is integrated into the SMF framework. You can change the parameters, but don't 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 the previous section showing the parameter names and defaults also applies to Solaris. The parameter names must be changed to lowercase and a prefix of config/ has to be added, e.g. config/user or config/ssl_keyfile. If you made any change, don't 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 will be used when enabling the service. Check the current property settings with:

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

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

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

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

Mac OS X: starting the webservice via launchd

On Mac OS X, launchd is used to start the 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 http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html.

VirtualBox Watchdog

Starting with VirtualBox 4.2 the memory ballooning service formerly known as VBoxBalloonCtrl was renamed to VBoxWatchdog, which now incorporates several host services that are meant to be run in a server environment.

These services are:

  • Memory ballooning control, which automatically takes care of a VM's configured memory balloon (see the section called “Memory ballooning” for an introduction to memory ballooning). This especially is useful for server environments where VMs may dynamically require more or less memory during runtime.

    The service periodically checks a VM's current memory balloon and its free guest RAM and automatically adjusts the current memory balloon by inflating or deflating it accordingly. This handling only applies to running VMs having recent Guest Additions installed.

  • Host isolation detection, which provides a way to detect whether the host cannot reach the specific VirtualBox server instance anymore and take appropriate actions, such as shutting down, saving the current state or even powering down certain VMs.

All configuration values can be either specified via command line or global extradata, whereas command line values always have a higher priority when set. Some of the configuration values also be be specified on a per-VM basis. So the overall lookup order is: command line, per-VM basis extradata (if available), global extradata.

Memory ballooning control

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 via command line with

--balloon-max <Size in MB>

, on a per-VM basis extradata value with

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

or using a global extradata value with

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

Note

If no maximum ballooning size is specified by at least one of the parameters above, no ballooning will be performed at all.

Setting the ballooning increment in MB can be either done via command line with

--balloon-inc <Size in MB>

or using a global extradata value with

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

Default ballooning increment is 256 MB if not specified.

Same goes with the ballooning decrement: Via command line with

--balloon-dec <Size in MB>

or using a global extradata value with

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

Default ballooning decrement is 128 MB if not specified.

To define the lower limit in MB a balloon can be the command line with

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

can be used or using a global extradata value with

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

is available. Default lower limit is 128 if not specified.

Host isolation detection

To detect whether a host is being isolated, that is, the host cannot reach the 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.

To set the groups handled by the host isolation detection via command line:

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

or using a global extradata value with

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

To set the host isolation timeout via command line:

--apimon-isln-timeout=<ms>

or using a global extradata value with

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

To set the actual host isolation response via command line:

--apimon-isln-response=<cmd>

or using a global extradata value with

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

The following response commands are available:

  • none, which does nothing.

  • pause, which pauses the execution of a VM.

  • poweroff, which shuts down the VM by pressing the virtual power button. The VM will not have the chance of saving any data or veto the shutdown process.

  • save, which saves the current machine state and powers off the VM afterwards. If saving the machine state fails the VM will be paused.

  • shutdown, which shuts down the VM in a gentle way by sending an ACPI shutdown event to the VM's operating system. The OS then has the chance of doing a clean shutdown.

More information

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

Other extension packs

Starting with VirtualBox 4.2.0 there is another extension pack, VNC, which is open source and replaces the previous integration of the VNC remote access protocol. This is experimental code, and will be initially available in the VirtualBox source code package only. It is to a large portion code contributed by users, and is not supported in any way by Oracle.

The keyboard handling is severely limited, and only the US keyboard layout works. Other keyboard layouts will have at least some keys which produce the wrong results (often quite surprising effects), and for layouts which have significant differences to the US keyboard layout it is most likely unusable.

It is possible to install both the Oracle VM VirtualBox Extension Pack and VNC, but only one VRDE module can be active at any time. The following command switches to the VNC VRDE module in VNC:

VBoxManage setproperty vrdeextpack VNC

Configuring the remote access works very similarly to VRDP (see the section called “Remote display (VRDP support)”), with some limitations: VNC does not support specifying several port numbers, and the authentication is done differently. VNC can only deal with password authentication, and there is no option to use password hashes. This leaves no other choice than having a clear-text password in the VM configuration, which can be set with the following command:

VBoxManage modifyvm VMNAME --vrdeproperty VNCPassword=secret

The user is responsible for keeping this password secret, and it should be removed when a VM configuration is passed to another person, for whatever purpose. Some VNC servers claim to have "encrypted" passwords in the configuration. This is not true encryption, it is only concealing the passwords, which is exactly as secure as clear-text passwords.

The following command switches back to VRDP (if installed):

VBoxManage setproperty vrdeextpack "Oracle VM VirtualBox Extension Pack"

Starting virtual machines during system boot

Starting with VirtualBox 4.2.0 it is possible to start VMs automatically during system boot on Linux, Solaris and Mac OS X for all users.

Linux: starting the autostart service via init

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 config 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 seperated 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
}
      

Every user who wants to enable autostart for individual machines has to set the path to the autostart database directory with

VBoxManage setproperty autostartdbpath <Autostart directory>

Solaris: starting the autostart service via SMF

On Solaris hosts, the VirtualBox autostart daemon is integrated into the SMF framework. To enable it you have to point the service to an existing configuration file which has the same format as on Linux (see the section called “Linux: starting the autostart service via init):

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

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

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

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

Mac OS X: starting the autostart service via launchd

On Mac OS X, launchd is used to start the 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 the section called “Linux: starting the autostart service via 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 could be configured see http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html.



[38] Support for CPU hot-plugging was introduced with VirtualBox 3.2.

[39] Experimental support for PCI passthrough was introduced with VirtualBox 4.1.

[40] Support for Crossbow based bridged networking was introduced with VirtualBox 4.1 and requires Solaris 11 build 159 or above.