2N/A<?
xml version="1.0" encoding="UTF-8"?>
2N/A<!
DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 2N/A<
chapter id="AdvancedTopics">
2N/A <
title>Advanced topics</
title>
2N/A <
sect1 id="vboxconfigdata">
2N/A <
title>Where VirtualBox stores its files</
title>
2N/A <
para>In VirtualBox, a virtual machine and its settings are described in a
2N/A virtual machine settings file in XML format. In addition, most virtual
2N/A machine have one or more virtual hard disks, which are typically
2N/A represented by disk images (
e.g. in VDI format). Where all these files are
2N/A stored depends on which version of VirtualBox created the machine.</
para>
2N/A <
title>Machines created by VirtualBox version 4.0 or later</
title>
2N/A <
para>Starting with version 4.0, by default, each virtual machine has
2N/A one directory on your host computer where all the files of that machine
2N/A are stored -- the XML settings file (with a
2N/A <
computeroutput>.vbox</
computeroutput> file extension) and its disk
2N/A <
para>By default, this "machine folder" is placed in a common folder
2N/A called "VirtualBox VMs", which VirtualBox creates in the current system
2N/A user's home directory. The location of this home directory depends on
2N/A the conventions of the host operating system:</
para>
2N/A <
para>On Windows, this is
2N/A <
computeroutput>%HOMEDRIVE%%HOMEPATH%</
computeroutput>; typically
2N/A something like <
computeroutput>C:\Documents and
2N/A Settings\Username\</
computeroutput>.</
para>
2N/A <
para>On Mac OS X, this is
2N/A <
para>On Linux and Solaris, this is
2N/A <
para>For simplicity, we will abbreviate this as
2N/A <
computeroutput>$HOME</
computeroutput> below. Using that convention, the
2N/A common folder for all virtual machines is
2N/A <
para>As an example, when you create a virtual machine called "Example
2N/A VM", you will find that VirtualBox creates<
orderedlist>
2N/A VM/</
computeroutput> and, in that folder, </
para>
2N/A <
para>the settings file <
computeroutput>Example
2N/A <
para>the virtual disk image <
computeroutput>Example
2N/A </
orderedlist></
para>
2N/A <
para>This is the default layout if you use the "Create new virtual
2N/A machine" wizard as described in <
xref linkend="gui-createvm" />. Once
2N/A you start working with the VM, additional files will show up: you will
2N/A find log files in a subfolder called
2N/A <
computeroutput>Logs</
computeroutput>, and once you have taken
2N/A snapshots, they will appear in a
2N/A <
computeroutput>Snapshots</
computeroutput> subfolder. For each VM, you
2N/A can change the location of its snapsnots folder in the VM
2N/A <
para>You can change the default machine folder by selecting
2N/A "Preferences" from the "File" menu in the VirtualBox main window. Then,
2N/A in the window that pops up, click on the "General" tab. Alternatively,
2N/A use <
computeroutput>VBoxManage setproperty
2N/A machinefolder</
computeroutput>; see <
xref 2N/A linkend="vboxmanage-setproperty" />.</
para>
2N/A <
title>Machines created by VirtualBox versions before 4.0</
title>
2N/A <
para>If you have upgraded to VirtualBox 4.0 from an earlier version of
2N/A VirtualBox, you probably have settings files and disks in the earlier
2N/A file system layout.</
para>
2N/A <
para>Before version 4.0, VirtualBox separated the machine settings
2N/A files from virtual disk images. The machine settings files had an
2N/A <
computeroutput>.xml</
computeroutput> file extension and resided in a
2N/A folder called "Machines" under the global VirtualBox configuration
2N/A directory (see the next section). So, for example, on Linux, this was
2N/A directory. The default hard disks folder was called "HardDisks" and
2N/A resided in the <
computeroutput>.VirtualBox</
computeroutput> folder as
2N/A well. Both locations could be changed by the user in the global
2N/A preferences. (The concept of a "default hard disk folder" has been
2N/A abandoned with VirtualBox 4.0, since disk images now reside in each
2N/A machine's folder by default.)</
para>
2N/A <
para>The old layout had several severe disadvantages.<
orderedlist>
2N/A <
para>It was very difficult to move a virtual machine from one
2N/A host to another because the files involved did not reside in the
2N/A same folder. In addition, the virtual media of all machines were
2N/A registered with a global registry in the central VirtualBox
2N/A <
para>To move a machine to another host, it was therefore not
2N/A enough to move the XML settings file and the disk images (which
2N/A were in different locations), but the hard disk entries from the
2N/A global media registry XML had to be meticulously copied as well,
2N/A which was close to impossible if the machine had snapshots and
2N/A therefore differencing images.</
para>
2N/A <
para>Storing virtual disk images, which can grow very large,
2N/A under the hidden <
computeroutput>.VirtualBox</
computeroutput>
2N/A directory (at least on Linux and Solaris hosts) made many users
2N/A wonder where their disk space had gone.</
para>
2N/A </
orderedlist></
para>
2N/A <
para>Whereas new VMs created with VirtualBox 4.0 or later will conform
2N/A to the new layout, for maximum compatibility, old VMs are
2N/A <
emphasis>not</
emphasis> converted to the new layout. Otherwise machine
2N/A settings would be irrevocably broken if a user downgraded from 4.0 back
2N/A to an older version of VirtualBox.</
para>
2N/A <
title>Global configuration data</
title>
2N/A <
para>In addition to the files of the virtual machines, VirtualBox
2N/A maintains global configuration data. On Windows, Linux and Solaris, this
2N/A hidden on Linux and Solaris), whereas on a Mac this resides in
2N/A <
para>VirtualBox creates this configuration directory automatically if
2N/A necessary. Optionally, you can supply an alternate configuration
2N/A directory by setting the
2N/A <
computeroutput><
literal>VBOX_USER_HOME</
literal></
computeroutput>
2N/A environment variable. (Since the global
2N/A all other configuration files, this allows for switching between several
2N/A VirtualBox configurations entirely.)</
para>
2N/A <
para>Most importantly, in this directory, VirtualBox stores its global
2N/A settings file, another XML file called
2N/A configuration options and the list of registered virtual machines with
2N/A pointers to their XML settings files. (Neither the location of this file
2N/A nor its directory has changed with VirtualBox 4.0.)</
para>
2N/A <
para>Before VirtualBox 4.0, all virtual media (disk image files) were
2N/A also contained in a global registry in this settings file. For
2N/A compatibility, this media registry still exists if you upgrade
2N/A VirtualBox and there are media from machines which were created with a
2N/A version before 4.0. If you have no such machines, then there will be no
2N/A global media registry; with VirtualBox 4.0, each machine XML file has
2N/A its own media registry.</
para>
2N/A <
para>Also before VirtualBox 4.0, the default "Machines" folder and the
2N/A default "HardDisks" folder resided under the VirtualBox configuration
2N/A If you are upgrading from a VirtualBox version before 4.0, files in
2N/A these directories are not automatically moved in order not to break
2N/A backwards compatibility.</
para>
2N/A <
title>Summary of 4.0 configuration changes</
title>
2N/A <
title>ignoreme</
title>
2N/A <
entry><
emphasis role="bold">Before 4.0</
emphasis></
entry>
2N/A <
entry><
emphasis role="bold">4.0 or above</
emphasis></
entry>
2N/A <
entry>Default machines folder</
entry>
2N/A VMs</
computeroutput></
entry>
2N/A <
entry>Default disk image location</
entry>
2N/A <
entry>In each machine's folder</
entry>
2N/A <
entry>Machine settings file extension</
entry>
2N/A <
entry><
computeroutput>.xml</
computeroutput></
entry>
2N/A <
entry><
computeroutput>.vbox</
computeroutput></
entry>
2N/A <
entry>Media registry</
entry>
2N/A <
entry>Each machine settings file</
entry>
2N/A <
entry>Media registration</
entry>
2N/A <
entry>Automatic on attach</
entry>
2N/A <
title>VirtualBox XML files</
title>
2N/A <
para>VirtualBox uses XML for both the machine settings files and the
2N/A global configuration file,
2N/A <
para>All VirtualBox XML files are versioned. When a new settings file
2N/A is created (
e.g. because a new virtual machine is created), VirtualBox
2N/A automatically uses the settings format of the current VirtualBox
2N/A version. These files may not be readable if you downgrade to an earlier
2N/A version of VirtualBox. However, when VirtualBox encounters a settings
2N/A file from an earlier version (
e.g. after upgrading VirtualBox), it
2N/A attempts to preserve the settings format as much as possible. It will
2N/A only silently upgrade the settings format if the current settings cannot
2N/A be expressed in the old format, for example because you enabled a
2N/A feature that was not present in an earlier version of
2N/A VirtualBox.<
footnote>
2N/A <
para>As an example, before VirtualBox 3.1, it was only possible to
2N/A enable or disable a single DVD drive in a virtual machine. If it was
2N/A enabled, then it would always be visible as the secondary master of
2N/A the IDE controller. With VirtualBox 3.1, DVD drives can be attached
2N/A to arbitrary slots of arbitrary controllers, so they could be the
2N/A secondary slave of an IDE controller or in a SATA slot. If you have
2N/A a machine settings file from an earlier version and upgrade
2N/A VirtualBox to 3.1 and then move the DVD drive from its default
2N/A position, this cannot be expressed in the old settings format; the
2N/A XML machine file would get written in the new format, and a backup
2N/A file of the old format would be kept.</
para>
2N/A </
footnote> In such cases, VirtualBox backs up the old settings file
2N/A in the virtual machine's configuration directory. If you need to go back
2N/A to the earlier version of VirtualBox, then you will need to manually
2N/A copy these backup files back.</
para>
2N/A <
para>We intentionally do not document the specifications of the
2N/A VirtualBox XML files, as we must reserve the right to modify them in the
2N/A future. We therefore strongly suggest that you do not edit these files
2N/A manually. VirtualBox provides complete access to its configuration data
2N/A through its the <
computeroutput>VBoxManage</
computeroutput> command line
2N/A tool (see <
xref linkend="vboxmanage" />) and its API (see <
xref 2N/A linkend="VirtualBoxAPI" />).</
para>
2N/A <
sect1 id="vboxsdl">
2N/A <
title>VBoxSDL, the simplified VM displayer</
title>
2N/A <
title>Introduction</
title>
2N/A <
para>VBoxSDL is a simple graphical user interface (GUI) that lacks the
2N/A nice point-and-click support which VirtualBox, our main GUI, provides.
2N/A VBoxSDL is currently primarily used internally for debugging VirtualBox
2N/A and therefore not officially supported. Still, you may find it useful
2N/A for environments where the virtual machines are not necessarily
2N/A controlled by the same person that uses the virtual machine.<
note>
2N/A <
para>VBoxSDL is not available on the Mac OS X host platform.</
para>
2N/A <
para>As you can see in the following screenshot, VBoxSDL does indeed
2N/A only provide a simple window that contains only the "pure" virtual
2N/A machine, without menus or other controls to click upon and no additional
2N/A indicators of virtual machine activity:</
para>
2N/A </
mediaobject></
para>
2N/A <
para>To start a virtual machine with VBoxSDL instead of the VirtualBox
2N/A GUI, enter the following on a command line:<
screen>VBoxSDL --startvm <vm></
screen></
para>
2N/A <
para>where <
computeroutput><vm></
computeroutput> is, as usual
2N/A with VirtualBox command line parameters, the name or UUID of an existing
2N/A virtual machine.</
para>
2N/A <
title>Secure labeling with VBoxSDL</
title>
2N/A <
para>When running guest operating systems in fullscreen mode, the guest
2N/A operating system usually has control over the whole screen. This could
2N/A present a security risk as the guest operating system might fool the
2N/A user into thinking that it is either a different system (which might
2N/A have a higher security level) or it might present messages on the screen
2N/A that appear to stem from the host operating system.</
para>
2N/A <
para>In order to protect the user against the above mentioned security
2N/A risks, the secure labeling feature has been developed. Secure labeling
2N/A is currently available only for VBoxSDL. When enabled, a portion of the
2N/A display area is reserved for a label in which a user defined message is
2N/A displayed. The label height in set to 20 pixels in VBoxSDL. The label
2N/A font color and background color can be optionally set as hexadecimal RGB
2N/A color values. The following syntax is used to enable secure
2N/A <
screen>VBoxSDL --startvm "VM name"
2N/A --seclabelsiz 14 --seclabelfgcol 00FF00 --seclabelbgcol 00FFFF</
screen>
2N/A <
para>In addition to enabling secure labeling, a TrueType font has to be
2N/A supplied. To use another font size than 12 point use the parameter
2N/A <
computeroutput>--seclabelsiz</
computeroutput>.</
para>
2N/A <
para>The label text can be set with <
screen>VBoxManage setextradata "VM name" "
VBoxSDL/
SecureLabel" "The Label"</
screen>
2N/A Changing this label will take effect immediately.</
para>
2N/A <
para>Typically, full screen resolutions are limited to certain
2N/A "standard" geometries such as 1024 x 768. Increasing this by twenty
2N/A lines is not usually feasible, so in most cases, VBoxSDL will chose the
2N/A next higher resolution,
e.g. 1280 x 1024 and the guest's screen will not
2N/A cover the whole display surface. If VBoxSDL is unable to choose a higher
2N/A resolution, the secure label will be painted on top of the guest's
2N/A screen surface. In order to address the problem of the bottom part of
2N/A the guest screen being hidden, VBoxSDL can provide custom video modes to
2N/A the guest that are reduced by the height of the label. For Windows
2N/A guests and recent Solaris and Linux guests, the VirtualBox Guest
2N/A Additions automatically provide the reduced video modes. Additionally,
2N/A the VESA BIOS has been adjusted to duplicate its standard mode table
2N/A with adjusted resolutions. The adjusted mode IDs can be calculated using
2N/A the following formula:</
para>
2N/A <
screen>reduced_modeid = modeid + 0x30</
screen>
2N/A <
para>For example, in order to start Linux with 1024 x 748 x 16, the
2N/A standard mode 0x117 (1024 x 768 x 16) is used as a base. The Linux video
2N/A mode kernel parameter can then be calculated using:</
para>
2N/A <
screen>vga = 0x200 | 0x117 + 0x30
2N/A <
para>The reason for duplicating the standard modes instead of only
2N/A supplying the adjusted modes is that most guest operating systems
2N/A require the standard VESA modes to be fixed and refuse to start with
2N/A different modes.</
para>
2N/A <
para>When using the
X.org VESA driver, custom modelines have to be
2N/A calculated and added to the configuration (usually in
2N/A modeline entries can be found at <
literal><
ulink 2N/A <
title>Releasing modifiers with VBoxSDL on Linux</
title>
2N/A <
para>When switching from a X virtual terminal (VT) to another VT using
2N/A Ctrl-Alt-Fx while the VBoxSDL window has the input focus, the guest will
2N/A receive Ctrl and Alt keypress events without receiving the corresponding
2N/A key release events. This is an architectural limitation of Linux. In
2N/A order to reset the modifier keys, it is possible to send
2N/A <
computeroutput>SIGUSR1</
computeroutput> to the VBoxSDL main thread
2N/A (first entry in the <
computeroutput>ps</
computeroutput> list). For
2N/A example, when switching away to another VT and saving the virtual
2N/A machine from this terminal, the following sequence can be used to make
2N/A sure the VM is not saved with stuck modifiers:</
para>
2N/A <
para><
screen>kill -usr1 <pid>
2N/AVBoxManage controlvm "Windows 2000" savestate</
screen></
para>
2N/A <
title id="autologon">Automated guest logons</
title>
2N/A <
para>VirtualBox provides Guest Addition modules for Windows, Linux and
2N/A Solaris to enable automated logons on the guest.</
para>
2N/A <
para>When a guest operating system is running in a virtual machine, it
2N/A might be desirable to perform coordinated and automated logons using
2N/A credentials from a master logon system. (With "credentials", we are
2N/A referring to logon information consisting of user name, password and
2N/A domain name, where each value might be empty.)</
para>
2N/A <
sect2 id="autologon_win">
2N/A <
title>Automated Windows guest logons</
title>
2N/A <
para>Since Windows NT, Windows has provided a modular system logon
2N/A subsystem ("Winlogon") which can be customized and extended by means of
2N/A so-called GINA modules (Graphical Identification and Authentication).
2N/A With Windows Vista and Windows 7, the GINA modules were replaced with a
2N/A new mechanism called "credential providers". The VirtualBox Guest
2N/A Additions for Windows come with both, a GINA and a credential provider
2N/A module, and therefore enable any Windows guest to perform automated
2N/A <
para>To activate the VirtualBox GINA or credential provider module,
2N/A install the Guest Additions with using the command line switch
2N/A <
computeroutput>/with_autologon</
computeroutput>. All the following
2N/A manual steps required for installing these modules will be then done by
2N/A the installer.</
para>
2N/A <
para>To manually install the VirtualBox GINA module, extract the Guest
2N/A Additions (see <
xref linkend="windows-guest-file-extraction" />) and
2N/A Windows <
computeroutput>SYSTEM32</
computeroutput> directory. Then, in
2N/A the registry, create the following key: <
screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</
screen>
2N/A <
para>The VirtualBox GINA module is implemented as a wrapper around
2N/A the standard Windows GINA module
2N/A (<
computeroutput>
MSGINA.DLL</
computeroutput>). As a result, it will
2N/A most likely not work correctly with 3rd party GINA modules.</
para>
2N/A <
para>To manually install the VirtualBox credential module, extract the
2N/A Guest Additions (see <
xref linkend="windows-guest-file-extraction" />)
2N/A the Windows <
computeroutput>SYSTEM32</
computeroutput> directory. Then,
2N/A in the registry, create the following keys:<
screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
2N/A Authentication\Credential Providers\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
2N/AHKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
2N/AHKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32</
screen></
para>
2N/A <
para>with all default values (the key named
2N/A <
computeroutput>(Default)</
computeroutput> in each key) set to
2N/A <
computeroutput>VBoxCredProv</
computeroutput>. After that a new string
2N/A named <
screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</
screen>
2N/A with a value of <
computeroutput>Apartment</
computeroutput> has to be
2N/A <
para>To set credentials, use the following command on a
2N/A <
emphasis>running</
emphasis> VM:</
para>
2N/A <
screen>VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</
screen>
2N/A <
para>While the VM is running, the credentials can be queried by the
2N/A VirtualBox logon modules (GINA or credential provider) using the
2N/A VirtualBox Guest Additions device driver. When Windows is in "logged
2N/A out" mode, the logon modules will constantly poll for credentials and if
2N/A they are present, a logon will be attempted. After retrieving the
2N/A credentials, the logon modules will erase them so that the above command
2N/A will have to be repeated for subsequent logons.</
para>
2N/A <
para>For security reasons, credentials are not stored in any persistent
2N/A manner and will be lost when the VM is reset. Also, the credentials are
2N/A "write-only",
i.e. there is no way to retrieve the credentials from the
2N/A host side. Credentials can be reset from the host side by setting empty
2N/A <
para>Depending on the particular variant of the Windows guest, the
2N/A following restrictions apply: <
orderedlist>
2N/A <
para>For <
emphasis role="bold">Windows XP guests,</
emphasis> the
2N/A logon subsystem needs to be configured to use the classic logon
2N/A dialog as the VirtualBox GINA module does not support the XP-style
2N/A welcome dialog.</
para>
2N/A <
para>For <
emphasis role="bold">Windows Vista and Windows 7
2N/A guests,</
emphasis> the logon subsystem does not support the
2N/A so-called Secure Attention Sequence
2N/A (<
computeroutput>CTRL+ALT+DEL</
computeroutput>). As a result, the
2N/A guest's group policy settings need to be changed to not use the
2N/A Secure Attention Sequence. Also, the user name given is only
2N/A compared to the true user name, not the user friendly name. This
2N/A means that when you rename a user, you still have to supply the
2N/A original user name (internally, Windows never renames user
2N/A </
orderedlist></
para>
2N/A <
para>The following command forces VirtualBox to keep the credentials
2N/A that this is a potential security risk as a malicious application
2N/A running on the guest could request this information using the proper
2N/A <
sect2 id="autologon_unix">
2N/A <
para>Starting with version 3.2, VirtualBox provides a custom PAM module
2N/A (Pluggable Authentication Module) which can be used to perform automated
2N/A guest logons on platforms which support this framework. Virtually all
2N/A <
emphasis role="bold">does not</
emphasis> do an actual verification of
2N/A the credentials passed to the guest OS; instead it relies on other
2N/A do the actual validation using the credentials retrieved by
2N/A authentication PAM service list.</
para>
2N/A the <
computeroutput>auth</
computeroutput> primitive. Other primitives
2N/A such as <
computeroutput>account</
computeroutput>,
2N/A <
computeroutput>session</
computeroutput> or
2N/A <
computeroutput>password</
computeroutput> are not supported.</
para>
2N/A <
para>The <
computeroutput>
pam_vbox.so</
computeroutput> module is shipped
2N/A as part of the Guest Additions but it is not installed
and/
or activated
2N/A on the guest OS by default. In order to install it, it has to be copied
2N/A to the security modules directory, usually
2N/A guest OS documentation for the correct PAM module directory.</
para>
2N/A <
para>For example, to use <
computeroutput>
pam_vbox.so</
computeroutput>
2N/A with a Ubuntu Linux guest OS and GDM (the GNOME Desktop Manager) to
2N/A logon users automatically with the credentials passed by the host, the
2N/A guest OS has to be configured like the following:</
para>
2N/A be copied to the security modules directory, in this case it is
2N/A <
para>Edit the PAM configuration file for GDM found at
2N/A top. Additionaly, in most Linux distributions there is a file called
2N/A is included in many other services (like the GDM file mentioned
2N/A above). There you also have to add add the line <
computeroutput>auth
2N/A <
para>If authentication against the shadow database using
2N/A argument <
computeroutput>try_first_pass</
computeroutput> is needed
2N/A in order to pass the credentials from the VirtualBox module to the
2N/A shadow database authentication module. For Ubuntu, this needs to be
2N/A the end of the line referencing
2N/A the PAM module to use credentials already present in the stack,
i.e. 2N/A the ones provided by the VirtualBox PAM module.</
para>
2N/A <
para>An incorrectly configured PAM stack can effectively prevent
2N/A you from logging into your guest system!</
para>
2N/A <
para>To make deployment easier, you can pass the argument
2N/A <
computeroutput>debug</
computeroutput> right after the
2N/A <
computeroutput>
pam_vbox.so</
computeroutput> statement. Debug log output
2N/A will then be recorded using syslog.</
para>
2N/A <
para>At present, the GDM display manager only retrieves credentials
2N/A at startup so unless the credentials have been supplied to the guest
2N/A before GDM starts, automatic logon will not work. This limitation
2N/A needs to be addressed by the GDM developers or another display
2N/A manager must be used.</
para>
2N/A <
title>Advanced configuration for Windows guests</
title>
2N/A <
sect2 id="sysprep">
2N/A <
title>Automated Windows system preparation</
title>
2N/A <
para>Beginning with Windows NT 4.0, Microsoft offers a "system
2N/A preparation" tool (in short: Sysprep) to prepare a Windows system for
2N/A deployment or redistribution. Whereas Windows 2000 and XP ship with
2N/A Sysprep on the installation medium, the tool also is available for
2N/A download on the Microsoft web site. In a standard installation of
2N/A Windows Vista and 7, Sysprep is already included. Sysprep mainly
2N/A consists of an executable called
2N/A user to put the Windows installation into preparation mode.</
para>
2N/A <
para>Starting with VirtualBox 3.2.2, the Guest Additions offer a way to
2N/A launch a system preparation on the guest operating system in an
2N/A automated way, controlled from the host system. To achieve that, see
2N/A <
xref linkend="guestadd-guestcontrol" /> for using the feature with the
2N/A special identifier <
computeroutput>sysprep</
computeroutput> as the
2N/A program to execute, along with the user name
2N/A <
computeroutput>sysprep</
computeroutput> and password
2N/A <
computeroutput>sysprep</
computeroutput> for the credentials. Sysprep
2N/A then gets launched with the required system rights.</
para>
2N/A role="bold">not possible</
emphasis> -- instead the following paths are
2N/A used (based on the operating system): <
itemizedlist>
2N/A for Windows NT 4.0, 2000 and XP</
para>
2N/A <
para><
computeroutput>%WINDIR%\System32\Sysprep\
sysprep.exe</
computeroutput>
2N/A for Windows Vista, 2008 Server and 7</
para>
2N/A </
itemizedlist> The Guest Additions will automatically use the
2N/A appropriate path to execute the system preparation tool.</
para>
2N/A <
sect1 id="cpuhotplug">
2N/A <
title>CPU hot-plugging</
title>
2N/A <
para>With virtual machines running modern server operating systems,
2N/A VirtualBox supports CPU hot-plugging.<
footnote>
2N/A <
para>Support for CPU hot-plugging was introduced with VirtualBox
2N/A </
footnote> Whereas on a physical computer this would mean that a CPU
2N/A can be added or removed while the machine is running, VirtualBox supports
2N/A adding and removing virtual CPUs while a virtual machine is
2N/A <
para>CPU hot-plugging works only with guest operating systems that
2N/A support it. So far this applies only to Linux and Windows Server 2008 x64
2N/A Data Center Edition. Windows supports only hot-add while Linux supports
2N/A hot-add and hot-remove but to use this feature with more than 8 CPUs a
2N/A 64bit Linux guest is required.</
para>
2N/A <
para>At this time, CPU hot-plugging requires using the VBoxManage
2N/A command-line interface. First, hot-plugging needs to be enabled for a
2N/A virtual machine:<
screen>VBoxManage modifyvm "VM name" --cpuhotplug on</
screen></
para>
2N/A <
para>After that, the --cpus option specifies the maximum number of CPUs
2N/A that the virtual machine can have:<
screen>VBoxManage modifyvm "VM name" --cpus 8</
screen>When
2N/A the VM is off, you can then add and remove virtual CPUs with the modifyvm
2N/A --plugcpu and --unplugcpu subcommands, which take the number of the
2N/A virtual CPU as a parameter, like this:<
screen>VBoxManage modifyvm "VM name" --plugcpu 3
2N/AVBoxManage modifyvm "VM name" --unplugcpu 3</
screen>Note that CPU 0 can never
2N/A <
para>While the VM is running, CPUs can be added with the
2N/A instead:<
screen>VBoxManage controlvm "VM name" plugcpu 3
2N/AVBoxManage controlvm "VM name" unplugcpu 3</
screen></
para>
2N/A <
para>See <
xref linkend="vboxmanage-modifyvm" /> and <
xref 2N/A linkend="vboxmanage-controlvm" /> for details.</
para>
2N/A <
para>With Linux guests, the following applies: To prevent ejection while
2N/A the CPU is still used it has to be ejected from within the guest before.
2N/A The Linux Guest Additions contain a service which receives hot-remove
2N/A events and ejects the CPU. Also, after a CPU is added to the VM it is not
2N/A automatically used by Linux. The Linux Guest Additions service will take
2N/A care of that if installed. If not a CPU can be started with the following
2N/A <
title>Advanced display configuration</
title>
2N/A <
title>Custom VESA resolutions</
title>
2N/A <
para>Apart from the standard VESA resolutions, the VirtualBox VESA BIOS
2N/A allows you to add up to 16 custom video modes which will be reported to
2N/A the guest operating system. When using Windows guests with the
2N/A VirtualBox Guest Additions, a custom graphics driver will be used
2N/A instead of the fallback VESA solution so this information does not
2N/A <
para>Additional video modes can be configured for each VM using the
2N/A extra data facility. The extra data key is called
2N/A <
literal>CustomVideoMode<x></
literal> with <
literal>x</
literal>
2N/A being a number from 1 to 16. Please note that modes will be read from 1
2N/A until either the following number is not defined or 16 is reached. The
2N/A following example adds a video mode that corresponds to the native
2N/A display resolution of many notebook computers:</
para>
2N/A <
screen>VBoxManage setextradata "VM name" "CustomVideoMode1" "1400x1050x16"</
screen>
2N/A <
para>The VESA mode IDs for custom video modes start at
2N/A <
literal>0x160</
literal>. In order to use the above defined custom video
2N/A mode, the following command line has be supplied to Linux:</
para>
2N/A <
screen>vga = 0x200 | 0x160
2N/A <
para>For guest operating systems with VirtualBox Guest Additions, a
2N/A custom video mode can be set using the video mode hint feature.</
para>
2N/A <
title>Configuring the maximum resolution of guests when using the
2N/A graphical frontend</
title>
2N/A <
para>When guest systems with the Guest Additions installed are started
2N/A using the graphical frontend (the normal VirtualBox application), they
2N/A will not be allowed to use screen resolutions greater than the host's
2N/A screen size unless the user manually resizes them by dragging the
2N/A window, switching to fullscreen or seamless mode or sending a video mode
2N/A hint using VBoxManage. This behavior is what most users will want, but
2N/A if you have different needs, it is possible to change it by issuing one
2N/A of the following commands from the command line:</
para>
2N/A <
para>will remove all limits on guest resolutions.</
para>
2N/A <
para>manually specifies a maximum resolution.</
para>
2N/A <
para>restores the default settings. Note that these settings apply
2N/A globally to all guest systems, not just to a single machine.</
para>
2N/A <
sect2 id="vbox-authenticate-sdk">
2N/A <
title>Custom external authentication modules</
title>
2N/A <
para>As described in <
xref linkend="vbox-auth" />, VirtualBox supports
2N/A arbitrary external modules to perform authentication. When the
2N/A authentication method is set to "external" for a particular VM,
2N/A VirtualBox calls the library that was specified with
2N/A <
computeroutput>VBoxManage setproperty vrdeauthlibrary</
computeroutput>.
2N/A This library will be loaded by the VM process on demand,
i.e. when the
2N/A first RDP connection is made by an external client.</
para>
2N/A <
para>External authentication is the most flexible as the external
2N/A handler can both choose to grant access to everyone (like the "null"
2N/A authentication method would) and delegate the request to the guest
2N/A authentication component. When delegating the request to the guest
2N/A component, it will still be called afterwards with the option to
2N/A override the result.</
para>
2N/A <
para>An authentication library is required to implement exactly one
2N/A * Authentication library entry point. Decides whether to allow
2N/A * a client connection.
2N/A * pUuid Pointer to the UUID of the virtual machine
2N/A * which the client connected to.
2N/A * guestJudgement Result of the guest authentication.
2N/A * szUser User name passed in by the client (UTF8).
2N/A * szPassword Password passed in by the client (UTF8).
2N/A * szDomain Domain passed in by the client (UTF8).
2N/A * fLogon Boolean flag. Indicates whether the entry point is called
2N/A * for a client logon or the client disconnect.
2N/A * clientId Server side unique identifier of the client.
2N/A * AuthResultAccessDenied Client access has been denied.
2N/A * AuthResultAccessGranted Client has the right to use the
2N/A * AuthResultDelegateToGuest Guest operating system must
2N/A * authenticate the client and the
2N/A * library must be called again with
2N/A * the result of the guest
2N/AAuthResult AUTHCALL AuthEntry(
2N/A const char *szCaller,
2N/A PVRDPAUTHUUID pUuid,
2N/A VRDPAuthGuestJudgement guestJudgement,
2N/A const char *szPassword
2N/A const char *szDomain
2N/A /* process request against your authentication source of choice */
2N/A return AuthResultAccessGranted;
2N/A <
para>A note regarding the UUID implementation of the first argument:
2N/A VirtualBox uses a consistent binary representation of UUIDs on all
2N/A platforms. For this reason the integer fields comprising the UUID are
2N/A stored as little endian values. If you want to pass such UUIDs to code
2N/A which assumes that the integer fields are big endian (often also called
2N/A network byte order), you need to adjust the contents of the UUID to
e.g. 2N/A achieve the same string representation. The required changes
2N/A <
para>reverse the order of byte 0, 1, 2 and 3</
para>
2N/A <
para>reverse the order of byte 4 and 5</
para>
2N/A <
para>reverse the order of byte 6 and 7.</
para>
2N/A </
itemizedlist>Using this conversion you will get identical results
2N/A when converting the binary UUID to the string representation.</
para>
2N/A <
para>The second arguments contains information about the guest
2N/A authentication status. For the first call, it is always set to
2N/A <
computeroutput>AuthGuestNotAsked</
computeroutput>. In case the
2N/A <
computeroutput>AuthResultDelegateToGuest</
computeroutput>, a guest
2N/A authentication will be attempted and another call to the method is made
2N/A with its result. This can be either granted / denied or no judgement
2N/A (the guest component chose for whatever reason to not make a decision).
2N/A In case there is a problem with the guest authentication module (
e.g. 2N/A the Additions are not installed or not running or the guest did not
2N/A respond within a timeout), the "not reacted" status will be
2N/A <
title>Advanced storage configuration</
title>
2N/A <
sect2 id="rawdisk">
2N/A <
title>Using a raw host hard disk from a guest</
title>
2N/A <
para>Starting with version 1.4, as an alternative to using virtual disk
2N/A images (as described in detail in <
xref linkend="storage" />),
2N/A VirtualBox can also present either entire physical hard disks or
2N/A selected partitions thereof as virtual disks to virtual machines.</
para>
2N/A <
para>With VirtualBox, this type of access is called "raw hard disk
2N/A access"; it allows a guest operating system to access its virtual hard
2N/A disk without going through the host OS file system. The actual
2N/A performance difference for image files vs. raw disk varies greatly
2N/A depending on the overhead of the host file system, whether dynamically
2N/A growing images are used and on host OS caching strategies. The caching
2N/A indirectly also affects other aspects such as failure behavior,
i.e. 2N/A whether the virtual disk contains all data written before a host OS
2N/A crash. Consult your host OS documentation for details on this.</
para>
2N/A <
para>Raw hard disk access is for expert users only. Incorrect use
2N/A or use of an outdated configuration can lead to <
emphasis 2N/A role="bold">total loss of data </
emphasis>on the physical disk. Most
2N/A importantly, <
emphasis>do not</
emphasis> attempt to boot the
2N/A partition with the currently running host operating system in a
2N/A guest. This will lead to severe data corruption.</
para>
2N/A <
para>Raw hard disk access -- both for entire disks and individual
2N/A partitions -- is implemented as part of the VMDK image format support.
2N/A As a result, you will need to create a special VMDK image file which
2N/A defines where the data will be stored. After creating such a special
2N/A VMDK image, you can use it like a regular virtual disk image. For
2N/A example, you can use the Virtual Media Manager (<
xref linkend="vdis" />)
2N/A or <
computeroutput>VBoxManage</
computeroutput> to assign the image to a
2N/A virtual machine.</
para>
2N/A <
title>Access to entire physical hard disk</
title>
2N/A <
para>While this variant is the simplest to set up, you must be aware
2N/A that this will give a guest operating system direct and full access to
2N/A an <
emphasis>entire physical disk</
emphasis>. If your
2N/A <
emphasis>host</
emphasis> operating system is also booted from this
2N/A disk, please take special care to not access the partition from the
2N/A guest at all. On the positive side, the physical disk can be
2N/A repartitioned in arbitrary ways without having to recreate the image
2N/A file that gives access to the raw disk.</
para>
2N/A <
para>To create an image that represents an entire physical hard disk
2N/A (which will not contain any actual data, as this will all be stored on
2N/A the physical disk), on a Linux host, use the command<
screen>VBoxManage internalcommands createrawvmdk -filename /
path/
to/
file.vmdk 2N/A -rawdisk /
dev/
sda</
screen>This creates the image
2N/A be read and written from <
code>/
dev/
sda</
code>.</
para>
2N/A <
para>On a Windows host, instead of the above device specification,
2N/A use
e.g. <
code>\\.\PhysicalDrive0</
code>. On a Mac OS X host, instead
2N/A Note that on OS X you can only get access to an entire disk if no
2N/A volume is mounted from it.</
para>
2N/A <
para>Creating the image requires
read/
write access for the given
2N/A device.
Read/
write access is also later needed when using the image
2N/A from a virtual machine.</
para>
2N/A <
para>Just like with regular disk images, this does not automatically
2N/A register the newly created image in the internal registry of hard
2N/A disks. If you want this done automatically, add
2N/A <
code>-register</
code>: <
screen>VBoxManage internalcommands createrawvmdk -filename /
path/
to/
file.vmdk 2N/A -rawdisk /
dev/
sda -register</
screen>After registering, you can assign
2N/A the newly created image to a virtual machine with
e.g. <
screen>VBoxManage storageattach WindowsXP --storagectl "IDE Controller"
2N/A this is done the selected virtual machine will boot from the specified
2N/A physical disk.</
para>
2N/A <
title>Access to individual physical hard disk partitions</
title>
2N/A <
para>This "raw partition support" is quite similar to the "full hard
2N/A disk" access described above. However, in this case, any partitioning
2N/A information will be stored inside the VMDK image, so you can
e.g. 2N/A install a different boot loader in the virtual hard disk without
2N/A affecting the host's partitioning information. While the guest will be
2N/A able to <
emphasis>see</
emphasis> all partitions that exist on the
2N/A physical disk, access will be filtered in that reading from partitions
2N/A for which no access is allowed the partitions will only yield zeroes,
2N/A and all writes to them are ignored.</
para>
2N/A <
para>To create a special image for raw partition support (which will
2N/A contain a small amount of data, as already mentioned), on a Linux
2N/A host, use the command<
screen>VBoxManage internalcommands createrawvmdk -filename /
path/
to/
file.vmdk 2N/A -rawdisk /
dev/
sda -partitions 1,5</
screen></
para>
2N/A <
para>As you can see, the command is identical to the one for "full
2N/A hard disk" access, except for the additional
2N/A <
computeroutput>-partitions</
computeroutput> parameter. This example
2N/A must be absolute), and partitions 1 and 5 of <
code>/
dev/
sda</
code>
2N/A would be made accessible to the guest.</
para>
2N/A <
para>VirtualBox uses the same partition numbering as your Linux host.
2N/A As a result, the numbers given in the above example would refer to the
2N/A first primary partition and the first logical drive in the extended
2N/A partition, respectively.</
para>
2N/A <
para>On a Windows host, instead of the above device specification,
2N/A use
e.g. <
code>\\.\PhysicalDrive0</
code>. On a Mac OS X host, instead
2N/A Note that on OS X you can only use partitions which are not mounted
2N/A (eject the respective volume first). Partition numbers are the same on
2N/A Linux, Windows and Mac OS X hosts.</
para>
2N/A <
para>The numbers for the list of partitions can be taken from the
2N/A output of<
screen>VBoxManage internalcommands listpartitions -rawdisk /
dev/
sda</
screen>The
2N/A output lists the partition types and sizes to give the user enough
2N/A information to identify the partitions necessary for the guest.</
para>
2N/A <
para>Images which give access to individual partitions are specific
2N/A to a particular host disk setup. You cannot transfer these images to
2N/A another host; also, whenever the host partitioning changes, the image
2N/A <
emphasis>must be recreated</
emphasis>.</
para>
2N/A <
para>Creating the image requires
read/
write access for the given
2N/A device.
Read/
write access is also later needed when using the image
2N/A from a virtual machine. If this is not feasible, there is a special
2N/A variant for raw partition access (currently only available on Linux
2N/A hosts) that avoids having to give the current user access to the
2N/A entire disk. To set up such an image, use<
screen>VBoxManage internalcommands createrawvmdk -filename /
path/
to/
file.vmdk 2N/A -rawdisk /
dev/
sda -partitions 1,5 -relative</
screen>When used from a
2N/A virtual machine, the image will then refer not to the entire disk, but
2N/A only to the individual partitions (in the example
2N/A read/
write access is only required for the affected partitions, not
2N/A for the entire disk. During creation however, read-only access to the
2N/A entire disk is required to obtain the partitioning information.</
para>
2N/A <
para>In some configurations it may be necessary to change the MBR
2N/A code of the created image,
e.g. to replace the Linux boot loader that
2N/A is used on the host by another boot loader. This allows
e.g. the guest
2N/A to boot directly to Windows, while the host boots Linux from the
2N/A "same" disk. For this purpose the
2N/A <
computeroutput>-mbr</
computeroutput> parameter is provided. It
2N/A specifies a file name from which to take the MBR code. The partition
2N/A table is not modified at all, so a MBR file from a system with totally
2N/A different partitioning can be used. An example of this is<
screen>VBoxManage internalcommands createrawvmdk -filename /
path/
to/
file.vmdk 2N/A MBR will be stored inside the image, not on the host disk.</
para>
2N/A <
para>For each of the above variants, you can register the resulting
2N/A image for immediate use in VirtualBox by adding
2N/A <
computeroutput>-register</
computeroutput> to the respective command
2N/A line. The image will then immediately appear in the list of registered
2N/A disk images. An example is<
screen>VBoxManage internalcommands createrawvmdk -filename /
path/
to/
file.vmdk 2N/A -rawdisk /
dev/
sda -partitions 1,5 -relative -register</
screen> which
2N/A creates an image referring to individual partitions, and registers it
2N/A when the image is successfully created.</
para>
2N/A <
sect2 id="changevpd">
2N/A <
title>Configuring the hard disk vendor product data (VPD)</
title>
2N/A <
para>VirtualBox reports vendor product data for its virtual hard disks
2N/A which consist of hard disk serial number, firmware revision and model
2N/A number. These can be changed using the following commands:</
para>
2N/A <
screen>VBoxManage setextradata "VM name"
2N/AVBoxManage setextradata "VM name"
2N/AVBoxManage setextradata "VM name"
2N/A <
para>The serial number is a 20 byte alphanumeric string, the firmware
2N/A revision an 8 byte alphanumeric string and the model number a 40 byte
2N/A alphanumeric string. Instead of "Port0" (referring to the first port),
2N/A specify the desired SATA hard disk port.</
para>
2N/A <
para>Additional three parameters are needed for
CD/
DVD drives to report
2N/A the vendor product data:</
para>
2N/A <
screen>VBoxManage setextradata "VM name"
2N/AVBoxManage setextradata "VM name"
2N/AVBoxManage setextradata "VM name"
2N/A <
para>The vendor id is an 8 byte alphanumeric string, the product id an
2N/A 16 byte alphanumeric string and the revision a 4 byte alphanumeric
2N/A string. Instead of "Port0" (referring to the first port), specify the
2N/A desired SATA hard disk port.</
para>
2N/A <
title>Launching more than 120 VMs on Solaris hosts</
title>
2N/A <
para>Solaris hosts have a fixed number of IPC semaphores IDs per process
2N/A preventing users from starting more than 120 VMs. While trying to launch
2N/A more VMs you would be shown a "Cannot create IPC semaphore" error.</
para>
2N/A <
para>In order to run more VMs, you will need to bump the semaphore ID
2N/A limit of the VBoxSVC process. Execute as root the
2N/A <
computeroutput>prctl</
computeroutput> command as shown below. The process
2N/A ID of VBoxSVC can be obtained using the
2N/A <
computeroutput>ps</
computeroutput> list command.</
para>
2N/A <
title>Legacy commands for using serial ports</
title>
2N/A <
para>Starting with version 1.4, VirtualBox provided support for virtual
2N/A serial ports, which, at the time, was rather complicated to set up with a
2N/A sequence of <
computeroutput>VBoxManage setextradata</
computeroutput>
2N/A statements. Since version 1.5, that way of setting up serial ports is no
2N/A longer necessary and <
emphasis>deprecated.</
emphasis> To set up virtual
2N/A serial ports, use the methods now described in <
xref 2N/A linkend="serialports" />.<
note>
2N/A <
para>For backwards compatibility, the old
2N/A <
computeroutput>setextradata</
computeroutput> statements, whose
2N/A description is retained below from the old version of the manual, take
2N/A <
emphasis>precedence</
emphasis> over the new way of configuring serial
2N/A ports. As a result, if configuring serial ports the new way doesn't
2N/A work, make sure the VM in question does not have old configuration
2N/A data such as below still active.</
para>
2N/A <
para>The old sequence of configuring a serial port used the following 6
2N/A <
screen>VBoxManage setextradata "VM name"
2N/AVBoxManage setextradata "VM name"
2N/AVBoxManage setextradata "VM name"
2N/AVBoxManage setextradata "VM name"
2N/AVBoxManage setextradata "VM name"
2N/AVBoxManage setextradata "VM name"
2N/A <
para>This sets up a serial port in the guest with the default settings
2N/A for COM1 (IRQ 4, I/O address 0x3f8) and the
2N/A <
computeroutput>Location</
computeroutput> setting assumes that this
2N/A configuration is used on a Windows host, because the Windows named pipe
2N/A syntax is used. Keep in mind that on Windows hosts a named pipe must
2N/A always start with <
computeroutput>\\.\pipe\</
computeroutput>. On Linux the
2N/A same config settings apply, except that the path name for the
2N/A <
computeroutput>Location</
computeroutput> can be chosen more freely. Local
2N/A domain sockets can be placed anywhere, provided the user running
2N/A VirtualBox has the permission to create a new file in the directory. The
2N/A final command above defines that VirtualBox acts as a server,
i.e. it
2N/A creates the named pipe itself instead of connecting to an already existing
2N/A <
sect1 id="changenat">
2N/A <
title>Fine-tuning the VirtualBox NAT engine</
title>
2N/A <
title>Configuring the address of a NAT network interface</
title>
2N/A <
para>In NAT mode, the guest network interface is assigned to the IPv4
2N/A range <
computeroutput>
10.0.x.0/
24</
computeroutput> by default where
2N/A <
computeroutput>x</
computeroutput> corresponds to the instance of the
2N/A NAT interface +2. So <
computeroutput>x</
computeroutput> is 2 when there
2N/A is only one NAT instance active. In that case the guest is assigned to
2N/A the address <
computeroutput>10.0.2.15</
computeroutput>, the gateway is
2N/A set to <
computeroutput>10.0.2.2</
computeroutput> and the name server can
2N/A be found at <
computeroutput>10.0.2.3</
computeroutput>.</
para>
2N/A <
para>If, for any reason, the NAT network needs to be changed, this can
2N/A be achieved with the following command:</
para>
2N/A <
screen>VBoxManage modifyvm "VM name" --natnet1 "
192.168/
16"</
screen>
2N/A <
para>This command would reserve the network addresses from
2N/A <
computeroutput>192.168.0.0</
computeroutput> to
2N/A <
computeroutput>192.168.254.254</
computeroutput> for the first NAT
2N/A network instance of "VM name". The guest IP would be assigned to
2N/A <
computeroutput>192.168.0.15</
computeroutput> and the default gateway
2N/A could be found at <
computeroutput>192.168.0.2</
computeroutput>.</
para>
2N/A <
sect2 id="nat-adv-tftp">
2N/A <
title>Configuring the boot server (next server) of a NAT network
2N/A <
para>For network booting in NAT mode, by default VirtualBox uses a
2N/A built-in TFTP server at the IP address 10.0.2.3. This default behavior
2N/A should work fine for typical remote-booting scenarios. However, it is
2N/A possible to change the boot server IP and the location of the boot image
2N/A with the following commands: <
screen>VBoxManage modifyvm "VM name" --nattftpserver1 10.0.2.2
2N/A <
sect2 id="nat-adv-settings">
2N/A <
title>Tuning
TCP/
IP buffers for NAT</
title>
2N/A <
para>The VirtualBox NAT stack performance is often determined by its
2N/A interaction with the host's
TCP/
IP stack and the size of several buffers
2N/A (<
computeroutput>SO_RCVBUF</
computeroutput> and
2N/A <
computeroutput>SO_SNDBUF</
computeroutput>). For certain setups users
2N/A might want to adjust the buffer size for a better performance. This can
2N/A by achieved using the following commands (values are in kilobytes and
2N/A can range from 8 to 1024): <
screen>VBoxManage modifyvm "VM name" --natsettings1 16000,128,128,0,0</
screen>
2N/A This example illustrates tuning the NAT settings. The first parameter is
2N/A the MTU, then the size of the socket's send buffer and the size of the
2N/A socket's receive buffer, the initial size of the TCP send window, and
2N/A lastly the initial size of the TCP receive window. Note that specifying
2N/A zero means fallback to the default value.</
para>
2N/A <
para>Each of these buffers has a default size of 64KB and default MTU
2N/A <
title>Binding NAT sockets to a specific interface</
title>
2N/A <
para>By default, VirtualBox's NAT engine will route
TCP/
IP packets
2N/A through the default interface assigned by the host's
TCP/
IP stack. (The
2N/A technical reason for this is that the NAT engine uses sockets for
2N/A communication.) If, for some reason, you want to change this behavior,
2N/A you can tell the NAT engine to bind to a particular IP address instead.
2N/A Use the following command: <
screen>VBoxManage modifyvm "VM name" --natbindip1 "10.45.0.2"</
screen></
para>
2N/A <
para>After this, all outgoing traffic will be sent through the
2N/A interface with the IP address 10.45.0.2. Please make sure that this
2N/A interface is up and running prior to this assignment.</
para>
2N/A <
sect2 id="nat-adv-dns">
2N/A <
title>Enabling DNS proxy in NAT mode</
title>
2N/A <
para>The NAT engine by default offers the same DNS servers to the guest
2N/A that are configured on the host. In some scenarios, it can be desirable
2N/A to hide the DNS server IPs from the guest, for example when this
2N/A information can change on the host due to expiring DHCP leases. In this
2N/A case, you can tell the NAT engine to act as DNS proxy using the
2N/A following command: <
screen>VBoxManage modifyvm "VM name" --natdnsproxy1 on</
screen></
para>
2N/A <
sect2 id="nat_host_resolver_proxy">
2N/A <
title>Using the host's resolver as a DNS proxy in NAT mode</
title>
2N/A <
para>For resolving network names, the DHCP server of the NAT engine
2N/A offers a list of registered DNS servers of the host. If for some reason
2N/A you need to hide this DNS server list and use the host's resolver
2N/A settings, thereby forcing the VirtualBox NAT engine to intercept DNS
2N/A requests and forward them to host's resolver, use the following command:
2N/A <
screen>VBoxManage modifyvm "VM name" --natdnshostresolver1 on</
screen>
2N/A Note that this setting is similar to the DNS proxy mode, however whereas
2N/A the proxy mode just forwards DNS requests to the appropriate servers,
2N/A the resolver mode will interpret the DNS requests and use the host's DNS
2N/A API to query the information and return it to the guest.</
para>
2N/A <
sect2 id="nat-adv-alias">
2N/A <
title>Configuring aliasing of the NAT engine</
title>
2N/A <
para>By default, the NAT core uses aliasing and uses random ports when
2N/A generating an alias for a connection. This works well for the most
2N/A protocols like SSH, FTP and so on. Though some protocols might need a
2N/A more transparent behavior or may depend on the real port number the
2N/A packet was sent from. It is possible to change the NAT mode via the
2N/A VBoxManage frontend with the following commands: <
screen>VBoxManage modifyvm "VM name" --nataliasmode proxyonly</
screen>
2N/A and <
screen>VBoxManage modifyvm "Linux Guest" --nataliasmode sameports</
screen>
2N/A The first example disables aliasing and switches NAT into transparent
2N/A mode, the second example enforces preserving of port values. These modes
can be combined if necessary.</
para>
<
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
<
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>
<
title>Fine-tuning timers and time synchronization</
title>
<
sect2 id="changetscmode">
<
title>Configuring the guest time stamp counter (TSC) to reflect guest
<
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
<
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>
<
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
<
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 id="changetimesync">
<
title>Tuning the Guest Additions time synchronization
<
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>
<
para>where <
computeroutput>PARAMETER</
computeroutput> is one of the
<
glossterm><
computeroutput>--timesync-interval</
computeroutput></
glossterm>
<
para>Specifies the interval at which to synchronize the time
with the host. The default is 10000 ms (10 seconds).</
para>
<
glossterm><
computeroutput>--timesync-min-adjust</
computeroutput></
glossterm>
<
para>The minimum absolute drift value measured in milliseconds
to make adjustments for. The default is 1000 ms on OS/2 and 100
<
glossterm><
computeroutput>--timesync-latency-factor</
computeroutput></
glossterm>
<
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
<
glossterm><
computeroutput>--timesync-max-latency</
computeroutput></
glossterm>
<
para>The max host timer query latency to accept. The default is
<
glossterm><
computeroutput>--timesync-set-threshold</
computeroutput></
glossterm>
<
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>
<
glossterm><
computeroutput>--timesync-set-start</
computeroutput></
glossterm>
<
para>Set the time when starting the time sync service.</
para>
<
glossterm><
computeroutput>--timesync-set-on-restore
0|1</
computeroutput></
glossterm>
<
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
<
para>All these parameters can be specified as command line parameters
to VBoxService as well.</
para>
<
sect1 id="addhostonlysolaris">
<
title>Configuring multiple host-only network interfaces on Solaris
<
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
<
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
<
computeroutput>/
etc/
netmasks</
computeroutput>, and if you are using NWAM
<
computeroutput>/
etc/
nwam/
llp</
computeroutput> 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.</
para>
<
sect1 id="solariscodedumper">
<
title>Configuring the VirtualBox CoreDumper on Solaris hosts</
title>
<
para>VirtualBox is capable of producing its own core files when things go
wrong and for more extensive debugging. Currently this is only available
<
para>The VirtualBox CoreDumper can be enabled using the following
<
para>You can specify which directory to use for core dumps with this
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 explicity 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
<
para>Setting <
computeroutput>CoreDumpLive</
computeroutput> sets up the VM
to produce cores whenever the VM receives a
<
computeroutput>SIGUSR2</
computeroutput> signal. After producing the core
file, the VM will not be terminated and will continue to run. You can then
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
<
computeroutput>
core.vb.<ProcessName>.<ProcessID></
computeroutput>,
<
title>Locking down the VirtualBox manager GUI</
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.<
screen>VBoxManage setextradata global
GUI/
Customizations OPTION[,OPTION...]</
screen></
para>
<
para>where <
computeroutput>OPTION</
computeroutput> is one of the
following keywords:<
glosslist>
<
glossterm><
computeroutput>noSelector</
computeroutput></
glossterm>
<
para>Don't allow to start the VirtualBox manager. Trying to do so
will show a window containing a proper error message.</
para>
<
glossterm><
computeroutput>noMenuBar</
computeroutput></
glossterm>
<
para>VM windows will not contain a menu bar.</
para>
<
glossterm><
computeroutput>noStatusBar</
computeroutput></
glossterm>
<
para>VM windows will not contain a status bar.</
para>
<
para>To disable any GUI customization do <
screen>VBoxManage setextradata global
GUI/
Customizations</
screen></
para>
<
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>Furthermore, you can disallow certain actions when terminating a VM.
To disallow specific actions, type:</
para>
<
para>where <
computeroutput>OPTION</
computeroutput> is one of the
following keywords:<
glosslist>
<
glossterm><
computeroutput>SaveState</
computeroutput></
glossterm>
<
para>Don't allow the user to save the VM state when terminating
<
glossterm><
computeroutput>Shutdown</
computeroutput></
glossterm>
<
para>Don't allow the user to shutdown the VM by sending the ACPI
power-off event to the guest.</
para>
<
glossterm><
computeroutput>PowerOff</
computeroutput></
glossterm>
<
para>Don't allow the user to power off the VM.</
para>
<
glossterm><
computeroutput>Restore</
computeroutput></
glossterm>
<
para>Don't allow the user to return to the last snapshot when
powering off the VM.</
para>
<
para>Any combination of the above is allowed. If all options are
specified, the VM cannot be shut down at all.</
para>
<
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
<
para>On Mac OS X, launchd is used. An example configuration file
It can be enabled by changing the
<
computeroutput>Disabled</
computeroutput> key from
<
computeroutput>true</
computeroutput> to
<
computeroutput>false</
computeroutput>. To manually start the
For additional information on how launchd services could be
configured see <
literal><
ulink