user_AdvancedTopics.xml revision 2eb85afb963be602d58f63aa6d70884fb5bf6717
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
<chapter id="AdvancedTopics">
<title>Advanced topics</title>
<sect1 id="vboxsdl">
<title>VBoxSDL, the simplified VM displayer</title>
<sect2>
<title>Introduction</title>
<para>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>
<para>VBoxSDL is not available on the Mac OS X host platform.</para>
</note></para>
<para>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:</para>
<para><mediaobject>
<imageobject>
width="10cm" />
</imageobject>
</mediaobject></para>
<para>To start a virtual machine with VBoxSDL instead of the VirtualBox
GUI, enter the following on a command line:<screen>VBoxSDL --startvm <vm></screen></para>
<para>where <computeroutput><vm></computeroutput> is, as usual
with VirtualBox command line parameters, the name or UUID of an existing
virtual machine.</para>
</sect2>
<sect2>
<title>Secure labeling with VBoxSDL</title>
<para>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.</para>
<para>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:</para>
<screen>VBoxSDL --startvm "VM name"
--seclabelsiz 14 --seclabelfgcol 00FF00 --seclabelbgcol 00FFFF</screen>
<para>In addition to enabling secure labeling, a TrueType font has to be
supplied. To use another font size than 12 point use the parameter
<computeroutput>--seclabelsiz</computeroutput>.</para>
<para>The label text can be set with <screen>VBoxManage setextradata "VM name" "VBoxSDL/SecureLabel" "The Label"</screen>
Changing this label will take effect immediately.</para>
<para>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:</para>
<screen>reduced_modeid = modeid + 0x30</screen>
<para>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:</para>
<screen>vga = 0x200 | 0x117 + 0x30
vga = 839</screen>
<para>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.</para>
<para>When using the X.org VESA driver, custom modelines have to be
calculated and added to the configuration (usually in
modeline entries can be found at <literal><ulink
url="http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html">http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html</ulink></literal>.)</para>
</sect2>
<sect2>
<title>Releasing modifiers with VBoxSDL on Linux</title>
<para>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
<computeroutput>SIGUSR1</computeroutput> to the VBoxSDL main thread
(first entry in the <computeroutput>ps</computeroutput> 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:</para>
<para><screen>kill -usr1 <pid>
VBoxManage controlvm "Windows 2000" savestate</screen></para>
</sect2>
</sect1>
<sect1>
<title id="autologon">Automated guest logons</title>
<para>VirtualBox provides Guest Addition modules for Windows, Linux and
Solaris to enable automated logons on the guest.</para>
<para>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.)</para>
<sect2 id="autologon_win">
<title>Automated Windows guest logons</title>
<para>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.</para>
<para>To activate the VirtualBox GINA or credential provider module,
install the Guest Additions with using the command line switch
<computeroutput>/with_autologon</computeroutput>. All the following
manual steps required for installing these modules will be then done by
the installer.</para>
<para>To manually install the VirtualBox GINA module, extract the Guest
Additions (see <xref linkend="windows-guest-file-extraction" />) and
Windows <computeroutput>SYSTEM32</computeroutput> directory. Then, in
the registry, create the following key: <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen>
<note>
<para>The VirtualBox GINA module is implemented as a wrapper around
the standard Windows GINA module
most likely not work correctly with 3rd party GINA modules.</para>
</note>
<para>To manually install the VirtualBox credential provider module,
extract the Guest Additions (see <xref
linkend="windows-guest-file-extraction" />) and copy the file
<computeroutput>SYSTEM32</computeroutput> directory. Then, in the
registry, create the following keys:<screen>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</screen></para>
<para>with all default values (the key named
<computeroutput>(Default)</computeroutput> in each key) set to
<computeroutput>VBoxCredProv</computeroutput>. After that a new string
named <screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen>
with a value of <computeroutput>Apartment</computeroutput> has to be
created.</para>
<para>To set credentials, use the following command on a
<emphasis>running</emphasis> VM:</para>
<screen>VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</screen>
<para>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.</para>
<para>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.</para>
<para>Depending on the particular variant of the Windows guest, the
following restrictions apply: <orderedlist>
<listitem>
<para>For <emphasis role="bold">Windows XP guests,</emphasis> 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.</para>
</listitem>
<listitem>
<para>For <emphasis role="bold">Windows Vista and Windows 7
guests,</emphasis> the logon subsystem does not support the
so-called Secure Attention Sequence
(<computeroutput>CTRL+ALT+DEL</computeroutput>). 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).</para>
</listitem>
<listitem>
<para>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 <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen>
with a <computeroutput>DWORD</computeroutput> value of
<computeroutput>1</computeroutput>.</para>
</listitem>
</orderedlist></para>
<para>The following command forces VirtualBox to keep the credentials
after they were read by the guest and on VM reset: <screen>VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</screen>Note
that this is a potential security risk as a malicious application
running on the guest could request this information using the proper
interface.</para>
</sect2>
<sect2 id="autologon_unix">
<para>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
<emphasis role="bold">does not</emphasis> do an actual verification of
the credentials passed to the guest OS; instead it relies on other
do the actual validation using the credentials retrieved by
authentication PAM service list.</para>
<note>
the <computeroutput>auth</computeroutput> primitive. Other primitives
such as <computeroutput>account</computeroutput>,
<computeroutput>session</computeroutput> or
<computeroutput>password</computeroutput> are not supported.</para>
</note>
on the guest OS by default. In order to install it, it has to be copied
from
to the security modules directory, usually
Please refer to your guest OS documentation for the correct PAM module
directory.</para>
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:</para>
<orderedlist>
<listitem>
be copied to the security modules directory, in this case it is
</listitem>
<listitem>
<para>Edit the PAM configuration file for GDM found at
top. Additionaly, in most Linux distributions there is a file called
is included in many other services (like the GDM file mentioned
above). There you also have to add the line <computeroutput>auth
</listitem>
<listitem>
<para>If authentication against the shadow database using
argument <computeroutput>try_first_pass</computeroutput> for
<computeroutput>use_first_pass</computeroutput> for
pass the credentials from the VirtualBox module to the shadow
database authentication module. For Ubuntu, this needs to be added
end of the line referencing
the PAM module to use credentials already present in the stack, i.e.
the ones provided by the VirtualBox PAM module.</para>
</listitem>
</orderedlist>
<para><warning>
<para>An incorrectly configured PAM stack can effectively prevent
you from logging into your guest system!</para>
</warning></para>
<para>To make deployment easier, you can pass the argument
<computeroutput>debug</computeroutput> right after the
will then be recorded using syslog.</para>
<para><note>
<para>By default, pam_vbox will not wait for credentials to arrive
from the host, in other words: When a login prompt is shown (for
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.</para>
</note></para>
<para>Starting with VirtualBox 4.1.4 pam_vbox supports various guest
property parameters which all reside in
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:</para>
<orderedlist>
<listitem>
<para><computeroutput>CredsWait</computeroutput>: 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
(<computeroutput>RDONLYGUEST</computeroutput>).</para>
</listitem>
<listitem>
<para><computeroutput>CredsWaitAbort</computeroutput>: Aborts waiting
for credentials when set to any value. Can be set from host and the
guest.</para>
</listitem>
<listitem>
<para><computeroutput>CredsWaitTimeout</computeroutput>: 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
(<computeroutput>RDONLYGUEST</computeroutput>).</para>
</listitem>
</orderedlist>
<para>To customize pam_vbox further there are the following guest
properties:</para>
<orderedlist>
<listitem>
<para><computeroutput>CredsMsgWaiting</computeroutput>: Custom
message showed while pam_vbox is waiting for credentials from the
host. This property must be set read-only for the guest
(<computeroutput>RDONLYGUEST</computeroutput>).</para>
</listitem>
<listitem>
<para><computeroutput>CredsMsgWaitTimeout</computeroutput>: 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 (<computeroutput>RDONLYGUEST</computeroutput>).</para>
</listitem>
</orderedlist>
<para><note>
<para>If a pam_vbox guest property does not have set the right flags
(<computeroutput>RDONLYGUEST</computeroutput>) 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
<computeroutput>debug</computeroutput> option.</para>
</note></para>
</sect2>
</sect1>
<sect1>
<title>Advanced configuration for Windows guests</title>
<sect2 id="sysprep">
<title>Automated Windows system preparation</title>
<para>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
user to put the Windows installation into preparation mode.</para>
<para>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
<xref linkend="guestadd-guestcontrol" /> for using the feature with the
special identifier <computeroutput>sysprep</computeroutput> as the
program to execute, along with the user name
<computeroutput>sysprep</computeroutput> and password
<computeroutput>sysprep</computeroutput> for the credentials. Sysprep
then gets launched with the required system rights.</para>
<note>
role="bold">not possible</emphasis> -- instead the following paths are
used (based on the operating system): <itemizedlist>
<listitem>
for Windows NT 4.0, 2000 and XP</para>
</listitem>
<listitem>
for Windows Vista, 2008 Server and 7</para>
</listitem>
</itemizedlist> The Guest Additions will automatically use the
appropriate path to execute the system preparation tool.</para>
</note>
</sect2>
</sect1>
<sect1>
<title>Advanced configuration for Linux and Solaris guests</title>
<sect2>
<title>Manual setup of selected guest services on Linux</title>
<para>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:</para>
<para>After this, you will need to at least compile the kernel modules
as root (you will need to replace <emphasis>lib</emphasis> by
<emphasis>lib64</emphasis> on some 64bit guests), and on older guests
without the udev service you will need to add the
<emphasis>vboxadd</emphasis> service to the default runlevel to ensure
that the modules get loaded.</para>
<para>To setup the time synchronization service, run the command
add the service vboxadd-service to the default runlevel. To set up the
X11 and OpenGL part of the Guest Additions, run the command <screen> /usr/lib/VBoxGuestAdditions/vboxadd-x11 setup</screen>
(you do not need to enable any services for this).</para>
<para>To recompile the guest kernel modules, use this command: <screen> /usr/lib/VBoxGuestAdditions/vboxadd setup</screen>
After compilation you should reboot your guest to ensure that the new
modules are actually used.</para>
</sect2>
<sect2 id="guestxorgsetup">
<title>Guest graphics and mouse driver setup in depth</title>
<para>This section assumes that you are familiar with configuring the
hal or udev and xorg.conf.d. If not you can learn about them by studying
the documentation which comes with X.Org.</para>
<para>The VirtualBox Guest Additions come with drivers for X.Org
versions <itemizedlist>
<listitem>
</listitem>
<listitem>
X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so)
</listitem>
<listitem>
X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so)
</listitem>
<listitem>
</listitem>
</itemizedlist> By default these drivers can be found in the
directory</para>
<para><computeroutput>/opt/VBoxGuestAdditions-<version>/lib/VBoxGuestAdditions</computeroutput></para>
<para>and the correct versions for the X server are symbolically linked
into the X.Org driver directories.</para>
<para>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
or later a driver for a PS/2 mouse must be loaded and the right
<para>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 <xref
linkend="settings-display" />. 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.</para>
<para>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:</para>
<screen>Section "Screen"
Identifier "Default Screen"
Device "VirtualBox graphics card"
Monitor "Generic Monitor"
DefaultDepth 24
SubSection "Display"
Depth 24
Modes "2048x800" "800x600" "640x480"
EndSubSection
EndSection</screen>
</sect2>
</sect1>
<sect1 id="cpuhotplug">
<title>CPU hot-plugging</title>
<para>With virtual machines running modern server operating systems,
VirtualBox supports CPU hot-plugging.<footnote>
<para>Support for CPU hot-plugging was introduced with VirtualBox
3.2.</para>
</footnote> 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.</para>
<para>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.</para>
<para>At this time, CPU hot-plugging requires using the VBoxManage
command-line interface. First, hot-plugging needs to be enabled for a
virtual machine:<screen>VBoxManage modifyvm "VM name" --cpuhotplug on</screen></para>
<para>After that, the --cpus option specifies the maximum number of CPUs
that the virtual machine can have:<screen>VBoxManage modifyvm "VM name" --cpus 8</screen>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:<screen>VBoxManage modifyvm "VM name" --plugcpu 3
VBoxManage modifyvm "VM name" --unplugcpu 3</screen>Note that CPU 0 can never
be removed.</para>
<para>While the VM is running, CPUs can be added with the
instead:<screen>VBoxManage controlvm "VM name" plugcpu 3
VBoxManage controlvm "VM name" unplugcpu 3</screen></para>
<para>See <xref linkend="vboxmanage-modifyvm" /> and <xref
linkend="vboxmanage-controlvm" /> for details.</para>
<para>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
</sect1>
<sect1 id="pcipassthrough">
<title>PCI passthrough</title>
<para>When running on Linux hosts, with a recent enough kernel (at least
version <computeroutput>2.6.31</computeroutput>) experimental host PCI
devices passthrough is available.<footnote>
<para>Experimental support for PCI passthrough was introduced with
VirtualBox 4.1.</para>
</footnote></para>
<note>
<para>The PCI passthrough module is shipped as a VirtualBox extension
package, which must be installed separately. See <xref
linkend="intro-installing" /> for more information.</para>
</note>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<para>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
<orderedlist>
<listitem>
<para>Your motherboard has an IOMMU unit.</para>
</listitem>
<listitem>
<para>Your CPU supports the IOMMU.</para>
</listitem>
<listitem>
<para>The IOMMU is enabled in the BIOS.</para>
</listitem>
<listitem>
enabled.</para>
</listitem>
<listitem>
<para>Your Linux kernel was compiled with IOMMU support (including
DMA remapping, see <computeroutput>CONFIG_DMAR</computeroutput>
kernel compilation option). The PCI stub driver
(<computeroutput>CONFIG_PCI_STUB</computeroutput>) is required as
well.</para>
</listitem>
<listitem>
<para>Your Linux kernel recognizes and uses the IOMMU unit
(<computeroutput>intel_iommu=on</computeroutput> boot option could
be needed). Search for DMAR and PCI-DMA in kernel boot log.</para>
</listitem>
</orderedlist></para>
<para>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
<computeroutput>lspci</computeroutput> command. The output will look like
this <screen>
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)
06:00.0 VGA compatible controller: nVidia Corporation G86 [GeForce 8500 GT] (rev a1)
</screen> The first column is a PCI address (in format
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:
<screen>VBoxManage modifyvm "VM name" --pciattach 02:00.0@01:05.0</screen>
To detach same device, use <screen>VBoxManage modifyvm "VM name" --pcidetach 02:00.0</screen>
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).</para>
<para>If the virtual machine has a PCI device attached, certain
limitations apply: <orderedlist>
<listitem>
Only PCI cards with non-shared interrupts (such as using MSI on host) are supported at the moment.
</listitem>
<listitem>
No guest state can be reliably saved/restored (as the internal state of the PCI card could not be retrieved).
</listitem>
<listitem>
Teleportation (live migration) doesn't work (for the same reason).
</listitem>
<listitem>
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).
</listitem>
</orderedlist></para>
</sect1>
<sect1>
<title>Advanced display configuration</title>
<sect2>
<title>Custom VESA resolutions</title>
<para>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.</para>
<para>Additional video modes can be configured for each VM using the
extra data facility. The extra data key is called
<literal>CustomVideoMode<x></literal> with <literal>x</literal>
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:</para>
<screen>VBoxManage setextradata "VM name" "CustomVideoMode1" "1400x1050x16"</screen>
<para>The VESA mode IDs for custom video modes start at
<literal>0x160</literal>. In order to use the above defined custom video
mode, the following command line has be supplied to Linux:</para>
<screen>vga = 0x200 | 0x160
vga = 864</screen>
<para>For guest operating systems with VirtualBox Guest Additions, a
custom video mode can be set using the video mode hint feature.</para>
</sect2>
<sect2>
<title>Configuring the maximum resolution of guests when using the
graphical frontend</title>
<para>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:</para>
<para>will remove all limits on guest resolutions.</para>
<para>manually specifies a maximum resolution.</para>
<para>restores the default settings. Note that these settings apply
globally to all guest systems, not just to a single machine.</para>
</sect2>
</sect1>
<sect1>
<title>Advanced storage configuration</title>
<sect2 id="rawdisk">
<title>Using a raw host hard disk from a guest</title>
<para>Starting with version 1.4, as an alternative to using virtual disk
images (as described in detail in <xref linkend="storage" />),
VirtualBox can also present either entire physical hard disks or
selected partitions thereof as virtual disks to virtual machines.</para>
<para>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.</para>
<para><warning>
<para>Raw hard disk access is for expert users only. Incorrect use
or use of an outdated configuration can lead to <emphasis
role="bold">total loss of data </emphasis>on the physical disk. Most
importantly, <emphasis>do not</emphasis> attempt to boot the
partition with the currently running host operating system in a
guest. This will lead to severe data corruption.</para>
</warning></para>
<para>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 (<xref linkend="vdis" />)
or <computeroutput>VBoxManage</computeroutput> to assign the image to a
virtual machine.</para>
<sect3>
<title>Access to entire physical hard disk</title>
<para>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 <emphasis>entire physical disk</emphasis>. If your
<emphasis>host</emphasis> 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.</para>
<para>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<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
<para>On a Windows host, instead of the above device specification,
Note that on OS X you can only get access to an entire disk if no
volume is mounted from it.</para>
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.</para>
<para>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. <screen>VBoxManage storageattach WindowsXP --storagectl "IDE Controller"
this is done the selected virtual machine will boot from the specified
physical disk.</para>
</sect3>
<sect3>
<title>Access to individual physical hard disk partitions</title>
<para>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 <emphasis>see</emphasis> 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.</para>
<para>To create a special image for raw partition support (which will
contain a small amount of data, as already mentioned), on a Linux
<para>As you can see, the command is identical to the one for "full
hard disk" access, except for the additional
<computeroutput>-partitions</computeroutput> parameter. This example
would be made accessible to the guest.</para>
<para>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.</para>
<para>On a Windows host, instead of the above device specification,
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.</para>
<para>The numbers for the list of partitions can be taken from the
output lists the partition types and sizes to give the user enough
information to identify the partitions necessary for the guest.</para>
<para>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
<emphasis>must be recreated</emphasis>.</para>
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<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
virtual machine, the image will then refer not to the entire disk, but
only to the individual partitions (in the example
for the entire disk. During creation however, read-only access to the
entire disk is required to obtain the partitioning information.</para>
<para>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
<computeroutput>-mbr</computeroutput> 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<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
MBR will be stored inside the image, not on the host disk.</para>
<para>The created image can be attached to a storage controller in a
VM configuration as usual.</para>
</sect3>
</sect2>
<sect2 id="changevpd">
<title>Configuring the hard disk vendor product data (VPD)</title>
<para>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:</para>
<screen>VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
<para>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.</para>
<para>The above commands apply to virtual machines with an AHCI (SATA)
controller. The commands for virtual machines with an IDE controller
are:</para>
<screen>VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
<para>For hard disks it's also possible to mark the
drive as having a non-rotational medium with:</para>
<screen>VBoxManage setextradata "VM name"
the vendor product data:</para>
<screen>VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
<para>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.</para>
</sect2>
<sect2>
<title id="iscsi-intnet">Access iSCSI targets via Internal
Networking</title>
<para>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 <xref linkend="storage-iscsi" />;
<xref linkend="network_internal" />; and <xref
linkend="vboxmanage-storageattach" /> for additional information.</para>
<para>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
VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen></para>
<para>Finally the iSCSI disk must be attached with the
<computeroutput>--intnet</computeroutput> option to tell the iSCSI
initiator to use internal networking:<screen>VBoxManage storageattach ... --medium iscsi
<para>Compared to a "regular" iSCSI setup, IP address of the target
<emphasis>must</emphasis> be specified as a numeric IP address, as there
is no DNS resolver for internal networking.</para>
<para>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.</para>
</sect2>
</sect1>
<sect1>
<title>Launching more than 128 VMs on Linux hosts</title>
<para>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
<para>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
<para>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.</para>
</sect1>
<sect1>
<title>Launching more than 120 VMs on Solaris hosts</title>
<para>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.</para>
<sect2>
<title>Temporary solution while VirtualBox is running</title>
<para>Execute as root the <computeroutput>prctl</computeroutput> command
as shown below for the currently running VBoxSVC process. The process ID
of VBoxSVC can be obtained using the <computeroutput>ps</computeroutput>
command.</para>
<para>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.</para>
</sect2>
<sect2>
<title>Persistent solution, requires user to re-login</title>
<para>If the user running VirtualBox is root, execute the following
command:</para>
<para>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:</para>
<para>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:</para>
<screen>projadd -U <username> user.<username>
projmod -s -K "project.max-sem-ids=(priv,2048,deny)" user.<username></screen>
<para>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.</para>
</sect2>
</sect1>
<sect1>
<title>Legacy commands for using serial ports</title>
<para>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 <computeroutput>VBoxManage setextradata</computeroutput>
statements. Since version 1.5, that way of setting up serial ports is no
longer necessary and <emphasis>deprecated.</emphasis> To set up virtual
serial ports, use the methods now described in <xref
linkend="serialports" />.<note>
<para>For backwards compatibility, the old
<computeroutput>setextradata</computeroutput> statements, whose
description is retained below from the old version of the manual, take
<emphasis>precedence</emphasis> 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.</para>
</note></para>
<para>The old sequence of configuring a serial port used the following 6
commands:</para>
<screen>VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
<para>This sets up a serial port in the guest with the default settings
for COM1 (IRQ 4, I/O address 0x3f8) and the
<computeroutput>Location</computeroutput> 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 <computeroutput>\\.\pipe\</computeroutput>. On Linux the
same config settings apply, except that the path name for the
<computeroutput>Location</computeroutput> 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.</para>
</sect1>
<sect1 id="changenat">
<title>Fine-tuning the VirtualBox NAT engine</title>
<sect2>
<title>Configuring the address of a NAT network interface</title>
<para>In NAT mode, the guest network interface is assigned to the IPv4
<computeroutput>x</computeroutput> corresponds to the instance of the
NAT interface +2. So <computeroutput>x</computeroutput> is 2 when there
is only one NAT instance active. In that case the guest is assigned to
the address <computeroutput>10.0.2.15</computeroutput>, the gateway is
set to <computeroutput>10.0.2.2</computeroutput> and the name server can
be found at <computeroutput>10.0.2.3</computeroutput>.</para>
<para>If, for any reason, the NAT network needs to be changed, this can
be achieved with the following command:</para>
<para>This command would reserve the network addresses from
<computeroutput>192.168.0.0</computeroutput> to
<computeroutput>192.168.254.254</computeroutput> for the first NAT
network instance of "VM name". The guest IP would be assigned to
<computeroutput>192.168.0.15</computeroutput> and the default gateway
could be found at <computeroutput>192.168.0.2</computeroutput>.</para>
</sect2>
<sect2 id="nat-adv-tftp">
<title>Configuring the boot server (next server) of a NAT network
interface</title>
<para>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: <screen>VBoxManage modifyvm "VM name" --nattftpserver1 10.0.2.2
</sect2>
<sect2 id="nat-adv-settings">
<para>The VirtualBox NAT stack performance is often determined by its
(<computeroutput>SO_RCVBUF</computeroutput> and
<computeroutput>SO_SNDBUF</computeroutput>). 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): <screen>VBoxManage modifyvm "VM name" --natsettings1 16000,128,128,0,0</screen>
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.</para>
<para>Each of these buffers has a default size of 64KB and default MTU
is 1500.</para>
</sect2>
<sect2>
<title>Binding NAT sockets to a specific interface</title>
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: <screen>VBoxManage modifyvm "VM name" --natbindip1 "10.45.0.2"</screen></para>
<para>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.</para>
</sect2>
<sect2 id="nat-adv-dns">
<title>Enabling DNS proxy in NAT mode</title>
<para>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: <screen>VBoxManage modifyvm "VM name" --natdnsproxy1 on</screen></para>
</sect2>
<sect2 id="nat_host_resolver_proxy">
<title>Using the host's resolver as a DNS proxy in NAT mode</title>
<para>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:
<screen>VBoxManage modifyvm "VM name" --natdnshostresolver1 on</screen>
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.</para>
</sect2>
<sect2 id="nat-adv-alias">
<title>Configuring aliasing of the NAT engine</title>
<para>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: <screen>VBoxManage modifyvm "VM name" --nataliasmode1 proxyonly</screen>
and <screen>VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</screen>
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.</para>
</sect2>
</sect1>
<sect1 id="changedmi">
<title>Configuring the BIOS DMI information</title>
<para>The DMI data VirtualBox provides to guests can be changed for a
specific VM. Use the following commands to configure the DMI BIOS
information:</para>
<screen>VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
VBoxManage setextradata "VM name"
"9852bf98-b83c-49db-a8de-182c42c7226b"</screen>
<para>If a DMI string is not set, the default value of VirtualBox is used.
To set an empty string use
<computeroutput>"<EMPTY>"</computeroutput>.</para>
<para>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
<computeroutput>VERR_CFGM_NOT_STRING</computeroutput> error. In that case,
use <computeroutput>"string:<value>"</computeroutput>, for instance
<screen>VBoxManage setextradata "VM name"
<para>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 <screen>dmidecode -t0</screen>and the DMI system information can be
obtained with <screen>dmidecode -t1</screen></para>
</sect1>
<sect1 id="changeacpicust">
<title>Configuring the custom ACPI table</title>
<para>VirtualBox can be configured to present an custom ACPI table to
the guest. Use the following command to configure this:</para>
<screen>VBoxManage setextradata "VM name"
<para>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
</sect1>
<sect1>
<title>Fine-tuning timers and time synchronization</title>
<sect2 id="changetscmode">
<title>Configuring the guest time stamp counter (TSC) to reflect guest
execution</title>
<para>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.</para>
<para>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:</para>
<para>To revert to the default TSC handling mode use:</para>
<para>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 they use the TSC.</para>
</sect2>
<sect2 id="warpguest">
<title>Accelerate or slow down the guest clock</title>
<para>For certain purposes it can be useful to accelerate or to slow
down the (virtual) guest clock. This can be achieved as follows:</para>
<para>The above example will double the speed of the guest clock
while</para>
<para>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 <xref linkend="changetimesync" />).</para>
</sect2>
<sect2 id="changetimesync">
<title>Tuning the Guest Additions time synchronization
parameters</title>
<para>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:</para>
<screen>VBoxManage guestproperty set VM_NAME "/VirtualBox/GuestAdd/VBoxService/PARAMETER" VALUE</screen>
<para>where <computeroutput>PARAMETER</computeroutput> is one of the
following:</para>
<para><glosslist>
<glossentry>
<glossterm><computeroutput>--timesync-interval</computeroutput></glossterm>
<glossdef>
<para>Specifies the interval at which to synchronize the time
with the host. The default is 10000 ms (10 seconds).</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><computeroutput>--timesync-min-adjust</computeroutput></glossterm>
<glossdef>
<para>The minimum absolute drift value measured in milliseconds
to make adjustments for. The default is 1000 ms on OS/2 and 100
ms elsewhere.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><computeroutput>--timesync-latency-factor</computeroutput></glossterm>
<glossdef>
<para>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.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><computeroutput>--timesync-max-latency</computeroutput></glossterm>
<glossdef>
<para>The max host timer query latency to accept. The default is
250 ms.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><computeroutput>--timesync-set-threshold</computeroutput></glossterm>
<glossdef>
<para>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.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><computeroutput>--timesync-set-start</computeroutput></glossterm>
<glossdef>
<para>Set the time when starting the time sync service.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><computeroutput>--timesync-set-on-restore
0|1</computeroutput></glossterm>
<glossdef>
<para>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.</para>
</glossdef>
</glossentry>
</glosslist></para>
<para>All these parameters can be specified as command line parameters
to VBoxService as well.</para>
</sect2>
</sect1>
<sect1 id="vboxbowsolaris11">
<title>Installing the alternate bridged networking driver on Solaris 11
hosts</title>
<para>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.</para>
<para>To force installation of the older STREAMS based network filter
driver, execute as root the following command before installing the
VirtualBox package:</para>
<para>To force installation of the Crossbow based network filter driver,
execute as root the following command before installing the VirtualBox
package:</para>
<para>To check which driver is currently being used by VirtualBox,
execute:</para>
<screen>modinfo | grep vbox</screen>
<para>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.</para>
</sect1>
<sect1 id="vboxbowvnictemplates">
<title>VirtualBox VNIC templates for VLANs on Solaris 11 hosts</title>
<para>VirtualBox supports VNIC (Virtual Network Interface) templates for
configuring VMs over VLANs.<footnote>
<para>Support for Crossbow based bridged networking was introduced
with VirtualBox 4.1 and requires Solaris 11 build 159 or above.</para>
</footnote> A VirtualBox VNIC template is a VNIC whose name starts with
"vboxvnic_template".</para>
<para>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:</para>
<screen>dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0
</screen>
<para>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 <computeroutput>-t</computeroutput> parameter in the
above command. You may check the current state of links using:</para>
<para><screen>$ 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
</screen></para>
<para>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
<computeroutput>dladm</computeroutput>. 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.</para>
</sect1>
<sect1 id="addhostonlysolaris">
<title>Configuring multiple host-only network interfaces on Solaris
hosts</title>
<para>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.</para>
<para>You first need to stop all running VMs and unplumb all existing
"vboxnet" interfaces. Execute the following commands as root:</para>
<screen>ifconfig vboxnet0 unplumb</screen>
<para>Once you make sure all vboxnet interfaces are unplumbed, remove the
driver using:</para>
<para><screen>rem_drv vboxnet</screen>then edit the file
and add a line for the new interfaces:</para>
<para><screen>name="vboxnet" parent="pseudo" instance=1;
name="vboxnet" parent="pseudo" instance=2;</screen>Add as many of these lines
as required and make sure "instance" number is uniquely incremented. Next
reload the vboxnet driver using:</para>
<para><screen>add_drv vboxnet</screen>Now plumb all the interfaces using
<computeroutput>ifconfig vboxnetX plumb</computeroutput> (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.</para>
<para>To make your newly added interfaces' settings persistent across
reboots you will need to edit the files
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.</para>
</sect1>
<sect1 id="solariscodedumper">
<title>Configuring the VirtualBox CoreDumper on Solaris hosts</title>
<para>VirtualBox is capable of producing its own core files for extensive
debugging when things go wrong. Currently this is only available on
Solaris hosts.</para>
<para>The VirtualBox CoreDumper can be enabled using the following
command:</para>
<para>You can specify which directory to use for core dumps with this
command:</para>
<para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir <path-to-directory></screen>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.</para>
<para>You must specify when the VirtualBox CoreDumper should be triggered.
This is done using the following commands:</para>
least one of the above two commands will have to be provided if you have
enabled the VirtualBox CoreDumper.</para>
<para>Setting <computeroutput>CoreDumpReplaceSystemDump</computeroutput>
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.</para>
<para>Setting <computeroutput>CoreDumpLive</computeroutput> sets up the VM
to produce cores whenever the VM process receives a
<computeroutput>SIGUSR2</computeroutput> 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:</para>
<para><screen>kill -s SIGUSR2 <VM-process-id></screen></para>
<para>Core files produced by the VirtualBox CoreDumper are of the form
</sect1>
<sect1 id="guitweaks">
<title>Locking down the VirtualBox manager GUI</title>
<sect2>
<title>GUI customization</title>
<para>There are several advanced customization settings for locking down
the VirtualBox manager, that is, removing some features that the user
should not see.</para>
<para>where <computeroutput>OPTION</computeroutput> is one of the
following keywords:<glosslist>
<glossentry>
<glossterm><computeroutput>noSelector</computeroutput></glossterm>
<glossdef>
<para>Don't allow to start the VirtualBox manager. Trying to do so
will show a window containing a proper error message.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><computeroutput>noMenuBar</computeroutput></glossterm>
<glossdef>
<para>VM windows will not contain a menu bar.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><computeroutput>noStatusBar</computeroutput></glossterm>
<glossdef>
<para>VM windows will not contain a status bar.</para>
</glossdef>
</glossentry>
</glosslist></para>
<para>To disable any GUI customization do <screen>VBoxManage setextradata global GUI/Customizations</screen></para>
</sect2>
<sect2>
<title>Host Key customization</title>
<para>To disable all host key combinations, open the preferences and
change the host key to <emphasis>None</emphasis>. This might be useful
when using VirtualBox in a kiosk mode.</para>
<para>To redefine or disable certain host key actions, use the following command:</para>
<para>The following list shows the possible host key actions together with their default
host key shortcut. Setting an action to <emphasis>None</emphasis> will disable
that host key action.</para>
<table>
<title>ignoreme</title>
<tgroup cols="3">
<tbody>
<row>
<entry><emphasis role="bold">Action</emphasis></entry>
<entry><emphasis role="bold">Default Host Key</emphasis></entry>
<entry><emphasis role="bold">Action</emphasis></entry>
</row>
<row>
<entry>SettingsDialog</entry>
<entry>S</entry>
<entry>open the VM settings dialog</entry>
</row>
<row>
<entry>TakeSnapshot</entry>
<entry>S</entry>
<entry>take a snapshot</entry>
</row>
<row>
<entry>InformationsDialog</entry>
<entry>N</entry>
<entry>show the VM information dialog</entry>
</row>
<row>
<entry>MouseIntegration</entry>
<entry>I</entry>
<entry>toggle mouse integration</entry>
</row>
<row>
<entry>TypeCAD</entry>
<entry>Del</entry>
<entry>inject Ctrl+Alt+Del</entry>
</row>
<row>
<entry>TypeCABS</entry>
<entry>Backspace</entry>
<entry>inject Ctrl+Alt+Backspace</entry>
</row>
<row>
<entry>Pause</entry>
<entry>P</entry>
<entry>Pause the VM</entry>
</row>
<row>
<entry>Reset</entry>
<entry>R</entry>
<entry>(hard) reset the guest</entry>
</row>
<row>
<entry>Shutdown</entry>
<entry>H</entry>
<entry>press the ACPI power button</entry>
</row>
<row>
<entry>Close</entry>
<entry>Q</entry>
<entry>show the VM close dialog</entry>
</row>
<row>
<entry>FullscreenMode</entry>
<entry>F</entry>
<entry>switch the VM into fullscreen</entry>
</row>
<row>
<entry>SeamlessMode</entry>
<entry>L</entry>
<entry>switch the VM into seamless mode</entry>
</row>
<row>
<entry>ScaleMode</entry>
<entry>C</entry>
<entry>switch the VM into scale mode</entry>
</row>
<row>
<entry>PopupMenu</entry>
<entry>Home</entry>
<entry>show popup menu in fullscreen / seamless mode</entry>
</row>
</tbody>
</tgroup>
</table>
<para>To disable the fullscreen mode as well as the seamless mode, use the following command:
<screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</screen>
</para>
</sect2>
<sect2>
<title>Action when terminating the VM</title>
<para>You can disallow certain actions when terminating a VM. To disallow specific actions, type:</para>
<para><screen>VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...]</screen></para>
<para>where <computeroutput>OPTION</computeroutput> is one of the
following keywords:<glosslist>
<glossentry>
<glossterm><computeroutput>SaveState</computeroutput></glossterm>
<glossdef>
<para>Don't allow the user to save the VM state when terminating
the VM.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><computeroutput>Shutdown</computeroutput></glossterm>
<glossdef>
<para>Don't allow the user to shutdown the VM by sending the ACPI
power-off event to the guest.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><computeroutput>PowerOff</computeroutput></glossterm>
<glossdef>
<para>Don't allow the user to power off the VM.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><computeroutput>Restore</computeroutput></glossterm>
<glossdef>
<para>Don't allow the user to return to the last snapshot when
powering off the VM.</para>
</glossdef>
</glossentry>
</glosslist></para>
<para>Any combination of the above is allowed. If all options are
specified, the VM cannot be shut down at all.</para>
</sect2>
</sect1>
<sect1 id="vboxwebsrv-daemon">
<title>Starting the VirtualBox web service automatically</title>
<para>The VirtualBox web service
(<computeroutput>vboxwebsrv</computeroutput>) is used for controlling
VirtualBox remotely. It is documented in detail in the VirtualBox Software
Development Kit (SDK); please see <xref linkend="VirtualBoxAPI" />. As the
client base using this interface is growing, we added start scripts for
the various operation systems we support. The following describes how to
use them. Please be aware that the web service is never started automatically
as a result of a standard installation.<itemizedlist>
<listitem>
<para>On Mac OS X, launchd is used. An example configuration file
can be found in
It can be enabled by changing the
<computeroutput>Disabled</computeroutput> key from
<computeroutput>true</computeroutput> to
<computeroutput>false</computeroutput>. To manually start the
service use the following command: <screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
For additional information on how launchd services could be
configured see <literal><ulink
url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html">http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html</ulink></literal>.</para>
</listitem>
<listitem>
<para>On Linux, the web service can be automatically started during
There is one mandatory parameter, VBOXWEB_USER which must be set to
the user which will later start the VMs.
<table>
<title>ignored</title>
<tgroup cols="2">
<tbody>
<row>
<entry><emphasis role="bold">Parameter</emphasis></entry>
<entry><emphasis role="bold">Description</emphasis></entry>
<entry><emphasis role="bold">Default</emphasis></entry>
</row>
<row>
<entry>VBOXWEB_HOST</entry>
<entry>The host to bind the web service to</entry>
<entry>localhost</entry>
</row>
<row>
<entry>VBOXWEB_PORT</entry>
<entry>The port to bind the web service to</entry>
<entry>18083</entry>
</row>
<row>
<entry>VBOXWEB_TIMEOUT</entry>
<entry>Session timeout in seconds; 0 disables timeouts</entry>
<entry>300</entry>
</row>
<row>
<entry>VBOXWEB_ CHECK_INTERVAL</entry>
<entry>Frequency of timeout checks in seconds</entry>
<entry>5</entry>
</row>
<row>
<entry>VBOXWEB_THREADS</entry>
<entry>Maximum number of worker threads to run in parallel</entry>
<entry>100</entry>
</row>
<row>
<entry>VBOXWEB_KEEPALIVE</entry>
<entry>Maximum number of requests before a socket will be closed</entry>
<entry>100</entry>
</row>
<row>
<entry>VBOXWEB_LOGFILE</entry>
<entry>Name of file to write log to</entry>
<entry><emphasis>no file</emphasis></entry>
</row>
<row>
<entry>VBOXWEB_ROTATE</entry>
<entry>Number of log files; 0 disables log rotation</entry>
<entry>10</entry>
</row>
<row>
<entry>VBOXWEB_LOGSIZE</entry>
<entry>Maximum size of a log file in bytes to trigger rotation</entry>
<entry>1MB</entry>
</row>
<row>
<entry>VBOXWEB_LOGINTERVAL</entry>
<entry>Maximum time interval in seconds to trigger log rotation</entry>
<entry>1 day</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
</itemizedlist></para>
</sect1>
<sect1 id="vboxballoonctrl">
<title>Memory Ballooning Service</title>
<para>Starting with VirtualBox 4.0.8 a new host executable called
<computeroutput>VBoxBalloonCtrl</computeroutput> is available to
automatically take care of a VM's configured memory balloon (see <xref
linkend="guestadd-balloon" /> for an introduction to memory ballooning).
This is especially useful for server environments where VMs may
dynamically require more or less memory during runtime.</para>
<para>VBoxBalloonCtrl 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.</para>
<para>To set up VBoxBalloonCtrl and adjust the maximum ballooning size a
VM can reach the following parameters will be checked in the following
order: <itemizedlist>
<listitem>
specified via VBoxBalloonCtrl command line parameter
<computeroutput>--balloon-max</computeroutput>
</listitem>
<listitem>
per-VM parameter using
<screen>VBoxManage setextradata "VM-Name" VBoxInternal/Guest/BalloonSizeMax <Size in MB></screen>
</listitem>
<listitem>
global parameter for all VMs using
<screen>VBoxManage setextradata global VBoxInternal/Guest/BalloonSizeMax <Size in MB></screen>
</listitem>
</itemizedlist> <note>
<para>If no maximum ballooning size is specified by at least one of
the parameters above, no ballooning will be performed at all.</para>
</note></para>
<para>For more options and parameters check the built-in command line help
accessible with <computeroutput>--help</computeroutput>.</para>
</sect1>
</chapter>