user_AdvancedTopics.xml revision b0ba64ce3f992684d01d57af5e1dac52799e0757
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>VBoxSDL, the simplified VM displayer</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VBoxSDL is a simple graphical user interface (GUI) that lacks the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync nice point-and-click support which VirtualBox, our main GUI, provides.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VBoxSDL is currently primarily used internally for debugging VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and therefore not officially supported. Still, you may find it useful
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for environments where the virtual machines are not necessarily
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync controlled by the same person that uses the virtual machine.<note>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VBoxSDL is not available on the Mac OS X host platform.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As you can see in the following screenshot, VBoxSDL does indeed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync only provide a simple window that contains only the "pure" virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine, without menus or other controls to click upon and no additional
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync indicators of virtual machine activity:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <imageobject>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <imagedata align="center" fileref="images/vbox-sdl.png"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync width="10cm" />
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </imageobject>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To start a virtual machine with VBoxSDL instead of the VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync GUI, enter the following on a command line:<screen>VBoxSDL --startvm <vm></screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>where <computeroutput><vm></computeroutput> is, as usual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with VirtualBox command line parameters, the name or UUID of an existing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual machine.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>When running guest operating systems in fullscreen mode, the guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync operating system usually has control over the whole screen. This could
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync present a security risk as the guest operating system might fool the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync user into thinking that it is either a different system (which might
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync have a higher security level) or it might present messages on the screen
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync that appear to stem from the host operating system.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In order to protect the user against the above mentioned security
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync risks, the secure labeling feature has been developed. Secure labeling
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is currently available only for VBoxSDL. When enabled, a portion of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync display area is reserved for a label in which a user defined message is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync displayed. The label height in set to 20 pixels in VBoxSDL. The label
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync font color and background color can be optionally set as hexadecimal RGB
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync color values. The following syntax is used to enable secure
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync labeling:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxSDL --startvm "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync --seclabelsiz 14 --seclabelfgcol 00FF00 --seclabelbgcol 00FFFF</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In addition to enabling secure labeling, a TrueType font has to be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync supplied. To use another font size than 12 point use the parameter
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--seclabelsiz</computeroutput>.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The label text can be set with <screen>VBoxManage setextradata "VM name" "VBoxSDL/SecureLabel" "The Label"</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Changing this label will take effect immediately.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Typically, full screen resolutions are limited to certain
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "standard" geometries such as 1024 x 768. Increasing this by twenty
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync lines is not usually feasible, so in most cases, VBoxSDL will chose the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync next higher resolution, e.g. 1280 x 1024 and the guest's screen will not
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync cover the whole display surface. If VBoxSDL is unable to choose a higher
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync resolution, the secure label will be painted on top of the guest's
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync screen surface. In order to address the problem of the bottom part of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the guest screen being hidden, VBoxSDL can provide custom video modes to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the guest that are reduced by the height of the label. For Windows
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guests and recent Solaris and Linux guests, the VirtualBox Guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Additions automatically provide the reduced video modes. Additionally,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the VESA BIOS has been adjusted to duplicate its standard mode table
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with adjusted resolutions. The adjusted mode IDs can be calculated using
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the following formula:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For example, in order to start Linux with 1024 x 748 x 16, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync standard mode 0x117 (1024 x 768 x 16) is used as a base. The Linux video
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync mode kernel parameter can then be calculated using:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>vga = 0x200 | 0x117 + 0x30
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncvga = 839</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The reason for duplicating the standard modes instead of only
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync supplying the adjusted modes is that most guest operating systems
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync require the standard VESA modes to be fixed and refuse to start with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync different modes.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>When using the X.org VESA driver, custom modelines have to be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync calculated and added to the configuration (usually in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <literal>/etc/X11/xorg.conf</literal>. A handy tool to determine
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync url="http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html">http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html</ulink></literal>.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Releasing modifiers with VBoxSDL on Linux</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>When switching from a X virtual terminal (VT) to another VT using
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Ctrl-Alt-Fx while the VBoxSDL window has the input focus, the guest will
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync receive Ctrl and Alt keypress events without receiving the corresponding
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync key release events. This is an architectural limitation of Linux. In
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync order to reset the modifier keys, it is possible to send
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>SIGUSR1</computeroutput> to the VBoxSDL main thread
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (first entry in the <computeroutput>ps</computeroutput> list). For
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync example, when switching away to another VT and saving the virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine from this terminal, the following sequence can be used to make
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync sure the VM is not saved with stuck modifiers:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage controlvm "Windows 2000" savestate</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title id="autologon">Automated guest logons</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox provides Guest Addition modules for Windows, Linux and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Solaris to enable automated logons on the guest.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>When a guest operating system is running in a virtual machine, it
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync might be desirable to perform coordinated and automated logons using
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync credentials from a master logon system. (With "credentials", we are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync referring to logon information consisting of user name, password and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync domain name, where each value might be empty.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Since Windows NT, Windows has provided a modular system logon
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync subsystem ("Winlogon") which can be customized and extended by means of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync so-called GINA modules (Graphical Identification and Authentication).
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync With Windows Vista and Windows 7, the GINA modules were replaced with a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync new mechanism called "credential providers". The VirtualBox Guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Additions for Windows come with both, a GINA and a credential provider
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync module, and therefore enable any Windows guest to perform automated
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync logons.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To activate the VirtualBox GINA or credential provider module,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync install the Guest Additions with using the command line switch
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/with_autologon</computeroutput>. All the following
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync manual steps required for installing these modules will be then done by
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the installer.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To manually install the VirtualBox GINA module, extract the Guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Additions (see <xref linkend="windows-guest-file-extraction" />) and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync copy the file <computeroutput>VBoxGINA.dll</computeroutput> to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Windows <computeroutput>SYSTEM32</computeroutput> directory. Then, in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the registry, create the following key: <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with a value of <computeroutput>VBoxGINA.dll</computeroutput>.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The VirtualBox GINA module is implemented as a wrapper around
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the standard Windows GINA module
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (<computeroutput>MSGINA.DLL</computeroutput>). As a result, it will
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync most likely not work correctly with 3rd party GINA modules.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>To manually install the VirtualBox credential provider module, extract the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Guest Additions (see <xref linkend="windows-guest-file-extraction" />)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and copy the file <computeroutput>VBoxCredProv.dll</computeroutput> to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the Windows <computeroutput>SYSTEM32</computeroutput> directory. Then,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in the registry, create the following keys:<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Authentication\Credential Providers\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncHKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncHKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>with all default values (the key named
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>(Default)</computeroutput> in each key) set to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxCredProv</computeroutput>. After that a new string
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync named <screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with a value of <computeroutput>Apartment</computeroutput> has to be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync created.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To set credentials, use the following command on a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>While the VM is running, the credentials can be queried by the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox logon modules (GINA or credential provider) using the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox Guest Additions device driver. When Windows is in "logged
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync out" mode, the logon modules will constantly poll for credentials and if
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync they are present, a logon will be attempted. After retrieving the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync credentials, the logon modules will erase them so that the above command
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync will have to be repeated for subsequent logons.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For security reasons, credentials are not stored in any persistent
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync manner and will be lost when the VM is reset. Also, the credentials are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "write-only", i.e. there is no way to retrieve the credentials from the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync host side. Credentials can be reset from the host side by setting empty
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync values.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Depending on the particular variant of the Windows guest, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following restrictions apply: <orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For <emphasis role="bold">Windows XP guests,</emphasis> the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync logon subsystem needs to be configured to use the classic logon
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync dialog as the VirtualBox GINA module does not support the XP-style
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync welcome dialog.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For <emphasis role="bold">Windows Vista and Windows 7
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guests,</emphasis> the logon subsystem does not support the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync so-called Secure Attention Sequence
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (<computeroutput>CTRL+ALT+DEL</computeroutput>). As a result, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guest's group policy settings need to be changed to not use the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Secure Attention Sequence. Also, the user name given is only
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync compared to the true user name, not the user friendly name. This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync means that when you rename a user, you still have to supply the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync original user name (internally, Windows never renames user
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync accounts).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Auto-logon handling of the built-in Windows Remote Desktop Service
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (formerly known as Terminal Services) is disabled by default. To enable
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync it, create the registry key
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync with a <computeroutput>DWORD</computeroutput> value of <computeroutput>1</computeroutput>.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following command forces VirtualBox to keep the credentials
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 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
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync that this is a potential security risk as a malicious application
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync running on the guest could request this information using the proper
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Starting with version 3.2, VirtualBox provides a custom PAM module
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (Pluggable Authentication Module) which can be used to perform automated
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guest logons on platforms which support this framework. Virtually all
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync modern Linux/Unix distributions rely on PAM.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>pam_vbox.so</computeroutput> module itself
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <emphasis role="bold">does not</emphasis> do an actual verification of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the credentials passed to the guest OS; instead it relies on other
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync modules such as <computeroutput>pam_unix.so</computeroutput> or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>pam_unix2.so</computeroutput> down in the PAM stack to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync do the actual validation using the credentials retrieved by
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>pam_vbox.so</computeroutput>. Therefore
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>pam_vbox.so</computeroutput> has to be on top of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync authentication PAM service list.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>pam_vbox.so</computeroutput> only supports
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the <computeroutput>auth</computeroutput> primitive. Other primitives
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>password</computeroutput> are not supported.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>pam_vbox.so</computeroutput> module is shipped
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync as part of the Guest Additions but it is not installed and/or activated
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on the guest OS by default. In order to install it, it has to be copied
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/opt/VBoxGuestAdditions-<version>/lib/VBoxGuestAdditions/</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to the security modules directory, usually
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>/lib/security/</computeroutput> on 32-bit guest Linuxes or
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>/lib64/security/</computeroutput> on 64-bit ones. Please refer to your
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guest OS documentation for the correct PAM module directory.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For example, to use <computeroutput>pam_vbox.so</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with a Ubuntu Linux guest OS and GDM (the GNOME Desktop Manager) to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync logon users automatically with the credentials passed by the host, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guest OS has to be configured like the following:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>pam_vbox.so</computeroutput> module has to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be copied to the security modules directory, in this case it is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/lib/security</computeroutput>.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Edit the PAM configuration file for GDM found at
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/etc/pam.d/gdm</computeroutput>, adding the line
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>auth requisite pam_vbox.so</computeroutput> at the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync top. Additionaly, in most Linux distributions there is a file called
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/etc/pam.d/common-auth</computeroutput>. This file
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is included in many other services (like the GDM file mentioned
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync above). There you also have to add the line <computeroutput>auth
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If authentication against the shadow database using
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>pam_unix2.so</computeroutput> is desired, the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync argument <computeroutput>try_first_pass</computeroutput> for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>use_first_pass</computeroutput> for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>pam_unix2.so</computeroutput> is needed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in order to pass the credentials from the VirtualBox module to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync shadow database authentication module. For Ubuntu, this needs to be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync added to <computeroutput>/etc/pam.d/common-auth</computeroutput>, to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the end of the line referencing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>pam_unix.so</computeroutput>. This argument tells
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the PAM module to use credentials already present in the stack, i.e.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the ones provided by the VirtualBox PAM module.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>An incorrectly configured PAM stack can effectively prevent
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you from logging into your guest system!</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To make deployment easier, you can pass the argument
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>debug</computeroutput> right after the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>pam_vbox.so</computeroutput> statement. Debug log output
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync will then be recorded using syslog.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>At present, the GDM display manager only retrieves credentials
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync at startup so unless the credentials have been supplied to the guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync before GDM starts, automatic logon will not work. This limitation
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync needs to be addressed by the GDM developers or another display
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync manager must be used.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Advanced configuration for Windows guests</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Automated Windows system preparation</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Beginning with Windows NT 4.0, Microsoft offers a "system
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync preparation" tool (in short: Sysprep) to prepare a Windows system for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync deployment or redistribution. Whereas Windows 2000 and XP ship with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Sysprep on the installation medium, the tool also is available for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync download on the Microsoft web site. In a standard installation of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Windows Vista and 7, Sysprep is already included. Sysprep mainly
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync consists of an executable called
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>sysprep.exe</computeroutput> which is invoked by the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync user to put the Windows installation into preparation mode.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Starting with VirtualBox 3.2.2, the Guest Additions offer a way to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync launch a system preparation on the guest operating system in an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync automated way, controlled from the host system. To achieve that, see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="guestadd-guestcontrol" /> for using the feature with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync special identifier <computeroutput>sysprep</computeroutput> as the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync program to execute, along with the user name
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>sysprep</computeroutput> and password
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>sysprep</computeroutput> for the credentials. Sysprep
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync then gets launched with the required system rights.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Specifying the location of "sysprep.exe" is <emphasis
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync role="bold">not possible</emphasis> -- instead the following paths are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync used (based on the operating system): <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>C:\sysprep\sysprep.exe</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for Windows NT 4.0, 2000 and XP</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>%WINDIR%\System32\Sysprep\sysprep.exe</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for Windows Vista, 2008 Server and 7</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist> The Guest Additions will automatically use the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync appropriate path to execute the system preparation tool.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <title>Advanced configuration for Linux and Solaris guests</title>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <title>Manual setup of selected guest services on Linux</title>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The VirtualBox Guest Additions contain several different
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync drivers. If for any reason you do not wish to set them all up, you can
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync install the Guest Additions using the following command:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen> sh /VBoxLinuxAdditions.run no_setup</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>After this, you will need to at least compile the kernel modules
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync by running the command <screen> /usr/lib/VBoxGuestAdditions/vboxadd setup</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync as root (you will need to replace <emphasis>lib</emphasis> by
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <emphasis>lib64</emphasis> on some 64bit guests), and on older guests
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync without the udev service you will need to add the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <emphasis>vboxadd</emphasis> service to the default runlevel to ensure
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync that the modules get loaded.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>To setup the time synchronization service, run the command
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen> /usr/lib/VBoxGuestAdditions/vboxadd-service setup</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync and add the service vboxadd-service to the default runlevel. To set up
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the X11 and OpenGL part of the Guest Additions, run the command
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen> /usr/lib/VBoxGuestAdditions/vboxadd-x11 setup</screen> (you
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync do not need to enable any services for this).</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>To recompile the guest kernel modules, use this command:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen> /usr/lib/VBoxGuestAdditions/vboxadd setup</screen> After
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync compilation you should reboot your guest to ensure that the new
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync modules are actually used.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <title>Guest graphics and mouse driver setup in depth</title>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This section assumes that you are familiar with configuring
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the X.Org server using xorg.conf and optionally the newer mechanisms
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync using hal or udev and xorg.conf.d. If not you can learn about
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync them by studying the documentation which comes with X.Org.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The VirtualBox Guest Additions come with drivers for X.Org
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (vboxvideo_drv_68.o and vboxmouse_drv_68.o)</listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem>X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so)
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem>X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so)
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem>X.Org Server versions 1.3 and later (vboxvideo_drv_13.so
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync By default these drivers can be found in the directory</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>/opt/VBoxGuestAdditions-<version>/lib/VBoxGuestAdditions</computeroutput>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>and the correct versions for the X server are symbolically linked
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>For graphics integration to work correctly, the X server must
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync load the vboxvideo driver (many recent X server versions look for it
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync automatically if they see that they are running in VirtualBox) and for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync an optimal user experience the guest kernel drivers must be loaded and
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the Guest Additions tool VBoxClient must be running as a client in the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync X session. For mouse integration to work correctly, the guest kernel
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync drivers must be loaded and in addition, in X servers from X.Org X11R6.8
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to X11R7.1 and in XFree86 version 4.3 the right vboxmouse driver must
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync be loaded and associated with /dev/mouse or /dev/psaux; in X.Org server
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync 1.3 or later a driver for a PS/2 mouse must be loaded and the right
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync vboxmouse driver must be associated with /dev/vboxguest.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The VirtualBox guest graphics driver can use any graphics
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync configuration for which the virtual resolution fits into the virtual
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync video memory allocated to the virtual machine (minus a small amount
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync used by the guest driver) as described in
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <xref linkend="settings-display" />. The driver will offer a range of
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync standard modes at least up to the default guest resolution for all
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync active guest monitors. In X.Org Server 1.3 and later the default mode
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync can be changed by setting the output property VBOX_MODE to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "<width>x<height>" for any guest monitor. When VBoxClient
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync and the kernel drivers are active this is done automatically when the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync host requests a mode change. The driver for older versions can only
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync receive new modes by querying the host for requests at regular
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync intervals.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>With pre-1.3 X Servers you can also add your own modes to the X
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync server configuration file. You simply need to add them to the "Modes"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync list in the "Display" subsection of the "Screen" section. For example,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the section shown here has a custom 2048x800 resolution mode added:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>Section "Screen"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Identifier "Default Screen"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Device "VirtualBox graphics card"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Monitor "Generic Monitor"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync DefaultDepth 24
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync SubSection "Display"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Modes "2048x800" "800x600" "640x480"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync EndSubSection
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncEndSection</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>With virtual machines running modern server operating systems,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox supports CPU hot-plugging.<footnote>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Support for CPU hot-plugging was introduced with VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 3.2.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </footnote> Whereas on a physical computer this would mean that a CPU
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can be added or removed while the machine is running, VirtualBox supports
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync adding and removing virtual CPUs while a virtual machine is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync running.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>CPU hot-plugging works only with guest operating systems that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync support it. So far this applies only to Linux and Windows Server 2008 x64
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Data Center Edition. Windows supports only hot-add while Linux supports
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hot-add and hot-remove but to use this feature with more than 8 CPUs a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 64bit Linux guest is required.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>At this time, CPU hot-plugging requires using the VBoxManage
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync command-line interface. First, hot-plugging needs to be enabled for a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual machine:<screen>VBoxManage modifyvm "VM name" --cpuhotplug on</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>After that, the --cpus option specifies the maximum number of CPUs
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync that the virtual machine can have:<screen>VBoxManage modifyvm "VM name" --cpus 8</screen>When
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the VM is off, you can then add and remove virtual CPUs with the modifyvm
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync --plugcpu and --unplugcpu subcommands, which take the number of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual CPU as a parameter, like this:<screen>VBoxManage modifyvm "VM name" --plugcpu 3
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage modifyvm "VM name" --unplugcpu 3</screen>Note that CPU 0 can never
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be removed.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>While the VM is running, CPUs can be added with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>controlvm plugcpu/unplugcpu</computeroutput> commands
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync instead:<screen>VBoxManage controlvm "VM name" plugcpu 3
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage controlvm "VM name" unplugcpu 3</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>See <xref linkend="vboxmanage-modifyvm" /> and <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="vboxmanage-controlvm" /> for details.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>With Linux guests, the following applies: To prevent ejection while
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the CPU is still used it has to be ejected from within the guest before.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync The Linux Guest Additions contain a service which receives hot-remove
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync events and ejects the CPU. Also, after a CPU is added to the VM it is not
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync automatically used by Linux. The Linux Guest Additions service will take
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync care of that if installed. If not a CPU can be started with the following
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync command:<screen>echo 1 > /sys/devices/system/cpu/cpu<id>/online</screen></para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>When running on Linux hosts, with a recent enough kernel (at least version
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>2.6.31</computeroutput>) experimental host PCI devices
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync passthrough is available.<footnote>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Experimental support for PCI passthrough was introduced with VirtualBox
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync 4.1.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <note><para>The PCI passthrough module is shipped as a VirtualBox extension
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync package, which must be installed separately. See <xref
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync linkend="intro-installing" /> for more information.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Essentially this feature allows to directly use physical PCI
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync devices on the host by the guest even if host doesn't have drivers for this
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync particular device. Both, regular PCI and some PCI Express cards, are
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync supported. AGP and certain PCI Express cards are not supported at the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync moment if they rely on GART (Graphics Address Remapping Table) unit
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync programming for texture management as it does rather nontrivial
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync operations with pages remapping interfering with IOMMU.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync This limitation may be lifted in future releases.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>To be fully functional, PCI passthrough support in VirtualBox depends upon
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync an IOMMU hardware unit which is not yet too widely available. If the device uses
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync bus mastering (i.e. it performs DMA to the OS memory on its
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync own), then an IOMMU is required, otherwise such DMA transactions may write to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the wrong physical memory address as the device DMA engine is programmed using
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync a device-specific protocol to perform memory transactions. The IOMMU functions
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync as translation unit mapping physical memory access requests from the device
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync using knowledge of the guest physical address to host physical addresses translation
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync rules.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Intel's solution for IOMMU is marketed as "Intel Virtualization Technology for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Directed I/O" (VT-d), and AMD's one is called AMD-Vi. So please check if your
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync motherboard datasheet has appropriate technology.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Even if your hardware doesn't have a IOMMU, certain PCI cards may work
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (such as serial PCI adapters), but the guest will show a warning on boot and
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the VM execution will terminate if the guest driver will attempt to enable card
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync bus mastering.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync It is very common that the BIOS or the host OS disables the IOMMU by default.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync So before any attempt to use it please make sure that
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <orderedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The VM must run with VT-x/AMD-V and nested paging enabled.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Your Linux kernel was compiled with IOMMU support (including DMA
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync remapping, see <computeroutput>CONFIG_DMAR</computeroutput> kernel
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync compilation option). The PCI stub driver
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (<computeroutput>CONFIG_PCI_STUB</computeroutput>) is required
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync as well.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Your Linux kernel recognizes and uses the IOMMU unit
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync boot option could be needed). Search for DMAR and PCI-DMA in kernel boot
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync log.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </orderedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Once you made sure that the host kernel supports the IOMMU, the next step is
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to select the PCI card and attach it to the guest. To figure out the list of
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync available PCI devices, use the <computeroutput>lspci</computeroutput> command.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync The output will look like this
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync 01:00.0 VGA compatible controller: ATI Technologies Inc Cedar PRO [Radeon HD 5450]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync 01:00.1 Audio device: ATI Technologies Inc Manhattan HDMI Audio [Mobility Radeon HD 5000 Series]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync 02:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168B PCI Express Gigabit Ethernet controller (rev 03)
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync 03:00.0 SATA controller: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync 03:00.1 IDE interface: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync 06:00.0 VGA compatible controller: nVidia Corporation G86 [GeForce 8500 GT] (rev a1)
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync The first column is a PCI address (in format <computeroutput>bus:device.function</computeroutput>).
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync This address could be used to identify the device for further operations.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync For example, to attach a PCI network controller on the system listed above
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to the second PCI bus in the guest, as device 5, function 0, use the following command:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage modifyvm "VM name" --pciattach 02:00.0@01:05.0</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync To detach same device, use
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage modifyvm "VM name" --pcidetach 02:00.0</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Please note that both host and guest could freely assign a different PCI address to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the card attached during runtime, so those addresses only apply to the address of
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the card at the moment of attachment (host), and during BIOS PCI init (guest).
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>If the virtual machine has a PCI device attached, certain limitations apply:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <orderedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Only PCI cards with non-shared interrupts (such as using MSI on host) are
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync supported at the moment.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync No guest state can be reliably saved/restored (as the internal state of the PCI
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync card could not be retrieved).
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Teleportation (live migration) doesn't work (for the same reason).
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync No lazy physical memory allocation. The host will preallocate the whole RAM
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync required for the VM on startup (as we cannot catch physical hardware accesses
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to the physical memory).
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Apart from the standard VESA resolutions, the VirtualBox VESA BIOS
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync allows you to add up to 16 custom video modes which will be reported to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the guest operating system. When using Windows guests with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox Guest Additions, a custom graphics driver will be used
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync instead of the fallback VESA solution so this information does not
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync apply.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Additional video modes can be configured for each VM using the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync extra data facility. The extra data key is called
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <literal>CustomVideoMode<x></literal> with <literal>x</literal>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync being a number from 1 to 16. Please note that modes will be read from 1
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync until either the following number is not defined or 16 is reached. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following example adds a video mode that corresponds to the native
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync display resolution of many notebook computers:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata "VM name" "CustomVideoMode1" "1400x1050x16"</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The VESA mode IDs for custom video modes start at
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <literal>0x160</literal>. In order to use the above defined custom video
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync mode, the following command line has be supplied to Linux:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>vga = 0x200 | 0x160
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncvga = 864</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For guest operating systems with VirtualBox Guest Additions, a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync custom video mode can be set using the video mode hint feature.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Configuring the maximum resolution of guests when using the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync graphical frontend</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>When guest systems with the Guest Additions installed are started
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync using the graphical frontend (the normal VirtualBox application), they
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync will not be allowed to use screen resolutions greater than the host's
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync screen size unless the user manually resizes them by dragging the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync window, switching to fullscreen or seamless mode or sending a video mode
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hint using VBoxManage. This behavior is what most users will want, but
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync if you have different needs, it is possible to change it by issuing one
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of the following commands from the command line:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata global GUI/MaxGuestResolution any</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>will remove all limits on guest resolutions.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata global GUI/MaxGuestResolution >width,height<</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>manually specifies a maximum resolution.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata global GUI/MaxGuestResolution auto</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>restores the default settings. Note that these settings apply
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync globally to all guest systems, not just to a single machine.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Using a raw host hard disk from a guest</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Starting with version 1.4, as an alternative to using virtual disk
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync images (as described in detail in <xref linkend="storage" />),
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox can also present either entire physical hard disks or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync selected partitions thereof as virtual disks to virtual machines.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>With VirtualBox, this type of access is called "raw hard disk
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync access"; it allows a guest operating system to access its virtual hard
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync disk without going through the host OS file system. The actual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync performance difference for image files vs. raw disk varies greatly
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync depending on the overhead of the host file system, whether dynamically
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync growing images are used and on host OS caching strategies. The caching
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync indirectly also affects other aspects such as failure behavior, i.e.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync whether the virtual disk contains all data written before a host OS
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync crash. Consult your host OS documentation for details on this.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Raw hard disk access is for expert users only. Incorrect use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync or use of an outdated configuration can lead to <emphasis
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync role="bold">total loss of data </emphasis>on the physical disk. Most
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync importantly, <emphasis>do not</emphasis> attempt to boot the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync partition with the currently running host operating system in a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guest. This will lead to severe data corruption.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Raw hard disk access -- both for entire disks and individual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync partitions -- is implemented as part of the VMDK image format support.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync As a result, you will need to create a special VMDK image file which
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync defines where the data will be stored. After creating such a special
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VMDK image, you can use it like a regular virtual disk image. For
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync example, you can use the Virtual Media Manager (<xref linkend="vdis" />)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync or <computeroutput>VBoxManage</computeroutput> to assign the image to a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual machine.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>While this variant is the simplest to set up, you must be aware
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync that this will give a guest operating system direct and full access to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync an <emphasis>entire physical disk</emphasis>. If your
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <emphasis>host</emphasis> operating system is also booted from this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync disk, please take special care to not access the partition from the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guest at all. On the positive side, the physical disk can be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync repartitioned in arbitrary ways without having to recreate the image
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync file that gives access to the raw disk.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To create an image that represents an entire physical hard disk
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (which will not contain any actual data, as this will all be stored on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the physical disk), on a Linux host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <code>/path/to/file.vmdk</code> (must be absolute), and all data will
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be read and written from <code>/dev/sda</code>.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>On a Windows host, instead of the above device specification,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host, instead
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of the above device specification use e.g. <code>/dev/disk1</code>.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Note that on OS X you can only get access to an entire disk if no
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync volume is mounted from it.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Creating the image requires read/write access for the given
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync device. Read/write access is also later needed when using the image
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync from a virtual machine.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Just like with regular disk images, this does not automatically
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync attach the newly created image to a virtual machine. This can be done
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync with e.g. <screen>VBoxManage storageattach WindowsXP --storagectl "IDE Controller"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync --port 0 --device 0 --type hdd --medium /path/to/file.vmdk</screen>When
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this is done the selected virtual machine will boot from the specified
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync physical disk.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Access to individual physical hard disk partitions</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This "raw partition support" is quite similar to the "full hard
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync disk" access described above. However, in this case, any partitioning
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync information will be stored inside the VMDK image, so you can e.g.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync install a different boot loader in the virtual hard disk without
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync affecting the host's partitioning information. While the guest will be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync able to <emphasis>see</emphasis> all partitions that exist on the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync physical disk, access will be filtered in that reading from partitions
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for which no access is allowed the partitions will only yield zeroes,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and all writes to them are ignored.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To create a special image for raw partition support (which will
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync contain a small amount of data, as already mentioned), on a Linux
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As you can see, the command is identical to the one for "full
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hard disk" access, except for the additional
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>-partitions</computeroutput> parameter. This example
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync would create the image <code>/path/to/file.vmdk</code> (which, again,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync must be absolute), and partitions 1 and 5 of <code>/dev/sda</code>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync would be made accessible to the guest.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox uses the same partition numbering as your Linux host.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync As a result, the numbers given in the above example would refer to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync first primary partition and the first logical drive in the extended
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync partition, respectively.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>On a Windows host, instead of the above device specification,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host, instead
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of the above device specification use e.g. <code>/dev/disk1</code>.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Note that on OS X you can only use partitions which are not mounted
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (eject the respective volume first). Partition numbers are the same on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Linux, Windows and Mac OS X hosts.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The numbers for the list of partitions can be taken from the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync output of<screen>VBoxManage internalcommands listpartitions -rawdisk /dev/sda</screen>The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync output lists the partition types and sizes to give the user enough
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync information to identify the partitions necessary for the guest.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Images which give access to individual partitions are specific
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to a particular host disk setup. You cannot transfer these images to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync another host; also, whenever the host partitioning changes, the image
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Creating the image requires read/write access for the given
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync device. Read/write access is also later needed when using the image
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync from a virtual machine. If this is not feasible, there is a special
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync variant for raw partition access (currently only available on Linux
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hosts) that avoids having to give the current user access to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync entire disk. To set up such an image, use<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync -rawdisk /dev/sda -partitions 1,5 -relative</screen>When used from a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual machine, the image will then refer not to the entire disk, but
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync only to the individual partitions (in the example
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <code>/dev/sda1</code> and <code>/dev/sda5</code>). As a consequence,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync read/write access is only required for the affected partitions, not
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for the entire disk. During creation however, read-only access to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync entire disk is required to obtain the partitioning information.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In some configurations it may be necessary to change the MBR
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync code of the created image, e.g. to replace the Linux boot loader that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is used on the host by another boot loader. This allows e.g. the guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to boot directly to Windows, while the host boots Linux from the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "same" disk. For this purpose the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>-mbr</computeroutput> parameter is provided. It
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync specifies a file name from which to take the MBR code. The partition
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync table is not modified at all, so a MBR file from a system with totally
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync different partitioning can be used. An example of this is<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr</screen>The modified
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync MBR will be stored inside the image, not on the host disk.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The created image can be attached to a storage controller in
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync a VM configuration as usual.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Configuring the hard disk vendor product data (VPD)</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox reports vendor product data for its virtual hard disks
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync which consist of hard disk serial number, firmware revision and model
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync number. These can be changed using the following commands:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model"</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The serial number is a 20 byte alphanumeric string, the firmware
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync revision an 8 byte alphanumeric string and the model number a 40 byte
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync alphanumeric string. Instead of "Port0" (referring to the first port),
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync specify the desired SATA hard disk port.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The above commands apply to virtual machines with an AHCI (SATA)
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync controller. The commands for virtual machines with an IDE controller
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync are:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage setextradata "VM name"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncVBoxManage setextradata "VM name"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncVBoxManage setextradata "VM name"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model"</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>For hard disks it's also possible (experimental!) to mark the drive
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync as having a non-rotational medium with:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage setextradata "VM name"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1"</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Additional three parameters are needed for CD/DVD drives to report
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the vendor product data:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIRevision" "revision"</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The vendor id is an 8 byte alphanumeric string, the product id an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 16 byte alphanumeric string and the revision a 4 byte alphanumeric
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync string. Instead of "Port0" (referring to the first port), specify the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync desired SATA hard disk port.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <title id="iscsi-intnet">Accès à des cibles iSCSI à travers le réseau interne</title>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>En tant que fonctionnalité expérimentale, VirtualBox permet l'accès
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync à une cible iSCSI en exécutant dans une machine virtuelle ce qui est
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync configuré pour utiliser le mode Réseau interne (comme décrit au <xref
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync linkend="network_internal" />). Le paramétrage de la machine virtuelle qui
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync utilise une telle cible iSCSI se fait comme décrit ci-dessous. La seule
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync différence est que l'adresse IP de la cible doit être spécifiée comme
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync adresse IP numérique.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>La pile IP qui accède au réseau interne doit être configurée dans la
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync machine virtuelle qui accède à la cible iSCSI. Vous devez choisir une
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync adresse IP statique libre et une adresse MAC non utilisée par d'autres
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync machines virtuelles. Dans l'exemple ci-dessous, adaptez le nom de la
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync machine virtuelle, l'adresse MAC et la configuration IP et le nom du
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync réseau interne (« MyIntNet ») selon vos besoins. Vous devez exécuter les
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync sept commandes suivantes :<screen>VBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/Trusted 1
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncVBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncVBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncVBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncVBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncVBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncVBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen></para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Enfin, le disque iSCSI doit être enregistré avec l'option
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <code>--intnet</code> pour dire à l'initiateur iSCSI d'utiliser le réseau
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync interne :<screen>VBoxManage addiscsidisk --server 10.0.9.30 --target iqn.2008-12.com.sun:sampletarget --intnet</screen></para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>L'adresse cible doit être spécifiée en tant qu'adresse IP numérique
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync vu qu'il n'y a pas de résolution DNS pour le réseau interne.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>La machine virtuelle avec la cible iSCSI devrait être démarrée avant
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync que la machine qui l'utilise ne soit allumée. Si une machine virtuelle
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync utilisant un disque iSCSI est démarrée sans que la cible iSCSI ne soit
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync allumée, cela peut prendre jusqu'à 200 secondes pour détecter cette
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync situation. La VM échouera pour s'allumer.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Launching more than 120 VMs on Solaris hosts</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Solaris hosts have a fixed number of IPC semaphores IDs per process
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync preventing users from starting more than 120 VMs. While trying to launch
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync more VMs you would be shown a "Cannot create IPC semaphore" error.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In order to run more VMs, you will need to bump the semaphore ID
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync limit of the VBoxSVC process. Execute as root the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>prctl</computeroutput> command as shown below. The process
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ID of VBoxSVC can be obtained using the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>ps</computeroutput> list command.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><screen>prctl -r -n project.max-sem-ids -v 2048 <pid-of-VBoxSVC></screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Legacy commands for using serial ports</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Starting with version 1.4, VirtualBox provided support for virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync serial ports, which, at the time, was rather complicated to set up with a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync sequence of <computeroutput>VBoxManage setextradata</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync statements. Since version 1.5, that way of setting up serial ports is no
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync longer necessary and <emphasis>deprecated.</emphasis> To set up virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync serial ports, use the methods now described in <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For backwards compatibility, the old
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>setextradata</computeroutput> statements, whose
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync description is retained below from the old version of the manual, take
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <emphasis>precedence</emphasis> over the new way of configuring serial
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ports. As a result, if configuring serial ports the new way doesn't
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync work, make sure the VM in question does not have old configuration
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data such as below still active.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The old sequence of configuring a serial port used the following 6
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync commands:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/serial/0/Config/IOBase" 0x3f8
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Driver" NamedPipe
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/Location" "\\.\pipe\vboxCOM1"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/IsServer" 1</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This sets up a serial port in the guest with the default settings
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync for COM1 (IRQ 4, I/O address 0x3f8) and the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>Location</computeroutput> setting assumes that this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync configuration is used on a Windows host, because the Windows named pipe
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync syntax is used. Keep in mind that on Windows hosts a named pipe must
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync always start with <computeroutput>\\.\pipe\</computeroutput>. On Linux the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync same config settings apply, except that the path name for the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>Location</computeroutput> can be chosen more freely. Local
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync domain sockets can be placed anywhere, provided the user running
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox has the permission to create a new file in the directory. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync final command above defines that VirtualBox acts as a server, i.e. it
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync creates the named pipe itself instead of connecting to an already existing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync one.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Fine-tuning the VirtualBox NAT engine</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Configuring the address of a NAT network interface</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In NAT mode, the guest network interface is assigned to the IPv4
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync range <computeroutput>10.0.x.0/24</computeroutput> by default where
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>x</computeroutput> corresponds to the instance of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync NAT interface +2. So <computeroutput>x</computeroutput> is 2 when there
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is only one NAT instance active. In that case the guest is assigned to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the address <computeroutput>10.0.2.15</computeroutput>, the gateway is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync set to <computeroutput>10.0.2.2</computeroutput> and the name server can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be found at <computeroutput>10.0.2.3</computeroutput>.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If, for any reason, the NAT network needs to be changed, this can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be achieved with the following command:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage modifyvm "VM name" --natnet1 "192.168/16"</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This command would reserve the network addresses from
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>192.168.254.254</computeroutput> for the first NAT
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync network instance of "VM name". The guest IP would be assigned to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>192.168.0.15</computeroutput> and the default gateway
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync could be found at <computeroutput>192.168.0.2</computeroutput>.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Configuring the boot server (next server) of a NAT network
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For network booting in NAT mode, by default VirtualBox uses a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync built-in TFTP server at the IP address 10.0.2.3. This default behavior
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync should work fine for typical remote-booting scenarios. However, it is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync possible to change the boot server IP and the location of the boot image
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with the following commands: <screen>VBoxManage modifyvm "VM name" --nattftpserver1 10.0.2.2
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage modifyvm "VM name" --nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The VirtualBox NAT stack performance is often determined by its
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interaction with the host's TCP/IP stack and the size of several buffers
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>SO_SNDBUF</computeroutput>). For certain setups users
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync might want to adjust the buffer size for a better performance. This can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync by achieved using the following commands (values are in kilobytes and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can range from 8 to 1024): <screen>VBoxManage modifyvm "VM name" --natsettings1 16000,128,128,0,0</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This example illustrates tuning the NAT settings. The first parameter is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the MTU, then the size of the socket's send buffer and the size of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync socket's receive buffer, the initial size of the TCP send window, and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync lastly the initial size of the TCP receive window. Note that specifying
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync zero means fallback to the default value.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Each of these buffers has a default size of 64KB and default MTU
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is 1500.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Binding NAT sockets to a specific interface</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>By default, VirtualBox's NAT engine will route TCP/IP packets
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync through the default interface assigned by the host's TCP/IP stack. (The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync technical reason for this is that the NAT engine uses sockets for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync communication.) If, for some reason, you want to change this behavior,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you can tell the NAT engine to bind to a particular IP address instead.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Use the following command: <screen>VBoxManage modifyvm "VM name" --natbindip1 "10.45.0.2"</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>After this, all outgoing traffic will be sent through the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface with the IP address 10.45.0.2. Please make sure that this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface is up and running prior to this assignment.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The NAT engine by default offers the same DNS servers to the guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync that are configured on the host. In some scenarios, it can be desirable
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to hide the DNS server IPs from the guest, for example when this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync information can change on the host due to expiring DHCP leases. In this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync case, you can tell the NAT engine to act as DNS proxy using the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following command: <screen>VBoxManage modifyvm "VM name" --natdnsproxy1 on</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Using the host's resolver as a DNS proxy in NAT mode</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For resolving network names, the DHCP server of the NAT engine
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync offers a list of registered DNS servers of the host. If for some reason
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you need to hide this DNS server list and use the host's resolver
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync settings, thereby forcing the VirtualBox NAT engine to intercept DNS
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync requests and forward them to host's resolver, use the following command:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage modifyvm "VM name" --natdnshostresolver1 on</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Note that this setting is similar to the DNS proxy mode, however whereas
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the proxy mode just forwards DNS requests to the appropriate servers,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the resolver mode will interpret the DNS requests and use the host's DNS
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync API to query the information and return it to the guest.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Configuring aliasing of the NAT engine</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>By default, the NAT core uses aliasing and uses random ports when
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync generating an alias for a connection. This works well for the most
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync protocols like SSH, FTP and so on. Though some protocols might need a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync more transparent behavior or may depend on the real port number the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync packet was sent from. It is possible to change the NAT mode via the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VBoxManage frontend with the following commands:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage modifyvm "VM name" --nataliasmode1 proxyonly</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync and <screen>VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync The first example disables aliasing and switches NAT into transparent
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync mode, the second example enforces preserving of port values. These modes
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can be combined if necessary.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Configuring the BIOS DMI information</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The DMI data VirtualBox provides to guests can be changed for a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync specific VM. Use the following commands to configure the DMI BIOS
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync information:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor" "BIOS Vendor"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion" "BIOS Version"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate" "BIOS Release Date"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor" 1
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor" 2
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor" "System Vendor"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct" "System Product"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion" "System Version"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "System Serial"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU" "System SKU"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily" "System Family"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "9852bf98-b83c-49db-a8de-182c42c7226b"</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If a DMI string is not set, the default value of VirtualBox is used.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync To set an empty string use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>"<EMPTY>"</computeroutput>.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Note that in the above list, all quoted parameters (DmiBIOSVendor,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync DmiBIOSVersion but not DmiBIOSReleaseMajor) are expected to be strings. If
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync such a string is a valid number, the parameter is treated as number and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the VM will most probably refuse to start with an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VERR_CFGM_NOT_STRING</computeroutput> error. In that case,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use <computeroutput>"string:<value>"</computeroutput>, for instance
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata "VM name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "string:1234"</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Changing this information can be necessary to provide the DMI
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync information of the host to the guest to prevent Windows from asking for a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync new product key. On Linux hosts the DMI BIOS information can be obtained
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with <screen>dmidecode -t0</screen>and the DMI system information can be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync obtained with <screen>dmidecode -t1</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Fine-tuning timers and time synchronization</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Configuring the guest time stamp counter (TSC) to reflect guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync execution</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>By default, VirtualBox keeps all sources of time visible to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guest synchronized to a single time source, the monotonic host time.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This reflects the assumptions of many guest operating systems, which
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync expect all time sources to reflect "wall clock" time. In special
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync circumstances it may be useful however to make the TSC (time stamp
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync counter) in the guest reflect the time actually spent executing the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guest.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This special TSC handling mode can be enabled on a per-VM basis,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and for best results must be used only in combination with hardware
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtualization. To enable this mode use the following command:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution" 1</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To revert to the default TSC handling mode use:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution"</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Note that if you use the special TSC handling mode with a guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync operating system which is very strict about the consistency of time
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync sources you may get a warning or error message about the timing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync inconsistency. It may also cause clocks to become unreliable with some
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guest operating systems depending on they use the TSC.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Accelerate or slow down the guest clock</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For certain purposes it can be useful to accelerate or to slow
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync down the (virtual) guest clock. This can be achieved as follows:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 200</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The above example will double the speed of the guest clock
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync while</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 50</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>will halve the speed of the guest clock. Note that changing the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync rate of the virtual clock can confuse the guest and can even lead to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync abnormal guest behavior. For instance, a higher clock rate means shorter
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync timeouts for virtual devices with the result that a slightly increased
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync response time of a virtual device due to an increased host load can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync cause guest failures. Note further that any time synchronization
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync mechanism will frequently try to resynchronize the guest clock with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync reference clock (which is the host clock if the VirtualBox Guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Additions are active). Therefore any time synchronization should be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync disabled if the rate of the guest clock is changed as described above
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Tuning the Guest Additions time synchronization
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync parameters</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The VirtualBox Guest Additions ensure that the guest's system time
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is synchronized with the host time. There are several parameters which
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can be tuned. The parameters can be set for a specific VM using the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following command:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage guestproperty set VM_NAME "/VirtualBox/GuestAdd/VBoxService/PARAMETER" VALUE</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>where <computeroutput>PARAMETER</computeroutput> is one of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>--timesync-interval</computeroutput></glossterm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Specifies the interval at which to synchronize the time
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with the host. The default is 10000 ms (10 seconds).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>--timesync-min-adjust</computeroutput></glossterm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The minimum absolute drift value measured in milliseconds
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to make adjustments for. The default is 1000 ms on OS/2 and 100
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ms elsewhere.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>--timesync-latency-factor</computeroutput></glossterm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The factor to multiply the time query latency with to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync calculate the dynamic minimum adjust time. The default is 8
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync times, that means in detail: Measure the time it takes to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync determine the host time (the guest has to contact the VM host
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service which may take some time), multiply this value by 8 and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync do an adjustment only if the time difference between host and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guest is bigger than this value. Don't do any time adjustment
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync otherwise.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>--timesync-max-latency</computeroutput></glossterm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The max host timer query latency to accept. The default is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 250 ms.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>--timesync-set-threshold</computeroutput></glossterm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The absolute drift threshold, given as milliseconds where
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to start setting the time instead of trying to smoothly adjust
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync it. The default is 20 minutes.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>--timesync-set-start</computeroutput></glossterm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Set the time when starting the time sync service.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossterm><computeroutput>--timesync-set-on-restore
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Set the time after the VM was restored from a saved state
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync when passing 1 as parameter (default). Disable by passing 0. In
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the latter case, the time will be adjusted smoothly which can
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync take a long time.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>All these parameters can be specified as command line parameters
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to VBoxService as well.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <title>Installing the alternate bridged networking driver on Solaris 11
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync hosts</title>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Starting with VirtualBox 4.1, VirtualBox ships a new network filter
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync driver that utilizes Solaris 11's Crossbow functionality. By default, this
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync new driver is installed for Solaris 11 hosts (builds 159 and above) that
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync has support for it.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>To force installation of the older STREAMS based network filter
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync driver, execute as root execute the below command before installing the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VirtualBox package:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>To force installation of the Crossbow based network filter
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync driver, execute as root the below command before installing the VirtualBox
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync package:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>To check which driver is currently being used by VirtualBox,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync execute:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>If the output contains "vboxbow", it indicates VirtualBox is using
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the Crossbow network filter driver, while the name "vboxflt" indicates
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync usage of the older STREAMS network filter.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <title>VirtualBox VNIC templates for VLANs on Solaris 11 hosts</title>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>VirtualBox supports VNIC (Virtual Network Interface) templates for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync configuring VMs over VLANs.<footnote>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Support for Crossbow based bridged networking was introduced
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync with VirtualBox 4.1 and requires Solaris 11 build 159 or above.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </footnote> A VirtualBox VNIC template is a VNIC whose name starts with
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "vboxvnic_template".</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Here is an example of how to use a VNIC template to configure a VLAN
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync for VMs. Create a VirtualBox VNIC template, by executing as root:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This will create a temporary VNIC over interface "nge0" with the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VLAN ID 23. To create VNIC templates that are persistent across host
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync reboots, skip the <computeroutput>-t</computeroutput> parameter in the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync above command. You may check the current state of links using:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncLINK CLASS MTU STATE BRIDGE OVER
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncnge0 phys 1500 up -- --
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncnge1 phys 1500 down -- --
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncvboxvnic_template0 vnic 1500 up -- nge0
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync$ dladm show-vnic
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncLINK OVER SPEED MACADDRESS MACADDRTYPE VID
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncvboxvnic_template0 nge0 1000 2:8:20:25:12:75 random 23
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Once the VNIC template is created, all VMs that need to be part of
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VLAN 23 over the physical interface "nge0" can use the same VNIC template.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync This makes managing VMs on VLANs simpler and efficient, as the VLAN
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync details are not stored as part of every VM's configuration but rather
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync picked up via the VNIC template which can be modified anytime using
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>dladm</computeroutput>. Apart from the VLAN ID, VNIC
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync templates can be created with additional properties such as bandwidth
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync limits, CPU fanout etc. Refer to your Solaris network documentation on how
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to accomplish this. These additional properties, if any, are also applied
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to VMs which use the VNIC template.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Configuring multiple host-only network interfaces on Solaris
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hosts</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>By default VirtualBox provides you with one host-only network
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface. Adding more host-only network interfaces on Solaris hosts
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync requires manual configuration. Here's how to add two more host-only
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync network interfaces.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>You first need to stop all running VMs and unplumb all existing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "vboxnet" interfaces. Execute the following commands as root:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Once you make sure all vboxnet interfaces are unplumbed, remove the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync driver using:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><screen>rem_drv vboxnet</screen>then edit the file
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/platform/i86pc/kernel/drv/vboxnet.conf</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and add a line for the new interfaces:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><screen>name="vboxnet" parent="pseudo" instance=1;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncname="vboxnet" parent="pseudo" instance=2;</screen>Add as many of these lines
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync as required and make sure "instance" number is uniquely incremented. Next
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync reload the vboxnet driver using:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><screen>add_drv vboxnet</screen>Now plumb all the interfaces using
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>ifconfig vboxnetX plumb</computeroutput> (where X can be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 0, 1 or 2 in this case) and once plumbed you can then configure the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface like any other network interface.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To make your newly added interfaces' settings persistent across
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync reboots you will need to edit the files
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/etc/netmasks</computeroutput>, and if you are using NWAM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/etc/nwam/llp</computeroutput> and add the appropriate
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync entries to set the netmask and static IP for each of those interfaces. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox installer only updates these configuration files for the one
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "vboxnet0" interface it creates by default.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <title>Configuring the VirtualBox CoreDumper on Solaris hosts</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox is capable of producing its own core files when things go
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync wrong and for more extensive debugging. Currently this is only available
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on Solaris hosts.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The VirtualBox CoreDumper can be enabled using the following
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync command:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpEnabled 1</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>You can specify which directory to use for core dumps with this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync command:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir <path-to-directory></screen>Make
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync sure the directory you specify is on a volume with sufficient free space
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and that the VirtualBox process has sufficient permissions to write files
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to this directory. If you skip this command and don't specify any core
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync dump directory, the current directory of the VirtualBox executable will be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync used (which would most likely fail when writing cores as they are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync protected with root permissions). It is recommended you explicity set a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync core dump directory.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>You must specify when the VirtualBox CoreDumper should be triggered.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This is done using the following commands:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpReplaceSystemDump 1
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata "VM name" VBoxInternal2/CoreDumpLive 1</screen>At
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync least one of the above two commands will have to be provided if you have
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync enabled the VirtualBox CoreDumper.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Setting <computeroutput>CoreDumpReplaceSystemDump</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync sets up the VM to override the host's core dumping mechanism and in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync event of any crash only the VirtualBox CoreDumper would produce the core
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync file.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Setting <computeroutput>CoreDumpLive</computeroutput> sets up the VM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to produce cores whenever the VM receives a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>SIGUSR2</computeroutput> signal. After producing the core
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync file, the VM will not be terminated and will continue to run. You can then
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync take cores of the VM process using:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><screen>kill -s SIGUSR2 <VM-process-id></screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Core files produced by the VirtualBox CoreDumper are of the form
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>core.vb.<ProcessName>.<ProcessID></computeroutput>,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync e.g.<computeroutput>core.vb.VBoxHeadless.11321</computeroutput>.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <title>Locking down the VirtualBox manager GUI</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>There are several advanced customization settings for locking down
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the VirtualBox manager, that is, removing some features that the user
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync should not see.<screen>VBoxManage setextradata global GUI/Customizations OPTION[,OPTION...]</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>where <computeroutput>OPTION</computeroutput> is one of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following keywords:<glosslist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>noSelector</computeroutput></glossterm>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Don't allow to start the VirtualBox manager. Trying to do so
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync will show a window containing a proper error message.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>noMenuBar</computeroutput></glossterm>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>VM windows will not contain a menu bar.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>noStatusBar</computeroutput></glossterm>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>VM windows will not contain a status bar.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To disable any GUI customization do <screen>VBoxManage setextradata global GUI/Customizations</screen></para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>To disable all host key combinations, open the preferences and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync change the host key to <emphasis>None</emphasis>. This might be useful
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync when using VirtualBox in a kiosk mode.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Furthermore, you can disallow certain actions when terminating a VM.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync To disallow specific actions, type:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><screen>VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...]</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>where <computeroutput>OPTION</computeroutput> is one of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following keywords:<glosslist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>SaveState</computeroutput></glossterm>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Don't allow the user to save the VM state when terminating
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the VM.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>Shutdown</computeroutput></glossterm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Don't allow the user to shutdown the VM by sending the ACPI
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync power-off event to the guest.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Don't allow the user to power off the VM.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossterm><computeroutput>Restore</computeroutput></glossterm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Don't allow the user to return to the last snapshot when
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync powering off the VM.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Any combination of the above is allowed. If all options are
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync specified, the VM cannot be shut down at all.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <title>Starting the VirtualBox web service automatically</title>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The VirtualBox web service
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (<computeroutput>vboxwebsrv</computeroutput>) is used for controlling
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VirtualBox remotely. It is documented in detail in the VirtualBox Software
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Development Kit (SDK); please see <xref linkend="VirtualBoxAPI" />. As the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync client base using this interface is growing, we added start scripts for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the various operation systems we support. The following describes how to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync use them. <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>On Mac OS X, launchd is used. An example configuration file
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can be found in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync It can be enabled by changing the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>false</computeroutput>. To manually start the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync service use the following command:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync For additional information on how launchd services could be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 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>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Starting with VirtualBox 4.0.8 a new host executable called
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>VBoxBalloonCtrl</computeroutput> is available to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync automatically take care of a VM's configured memory balloon
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (see <xref linkend="guestadd-balloon" /> for an introduction to memory
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync ballooning). This is especially useful for server environments where
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VMs may dynamically require more or less memory during runtime.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>VBoxBalloonCtrl periodically checks a VM's current memory balloon
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync and its free guest RAM and automatically adjusts the current memory
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync balloon by inflating or deflating it accordingly. This handling only
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync applies to running VMs having recent Guest Additions installed.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>To set up VBoxBalloonCtrl and adjust the maximum ballooning size a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VM can reach the following parameters will be checked in the following
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem>specified via VBoxBalloonCtrl command line parameter
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--balloon-max</computeroutput></listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem>per-VM parameter using
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage setextradata "VM-Name" VBoxInternal/Guest/BalloonSizeMax <Size in MB></screen></listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem>global parameter for all VMs using
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage setextradata global VBoxInternal/Guest/BalloonSizeMax <Size in MB></screen></listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>If no maximum ballooning size is specified by at least one of the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync parameters above, no ballooning will be performed at all.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>For more options and parameters check the built-in command line help
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync accessible with <computeroutput>--help</computeroutput>.</para>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <title>Starting virtual machines during system boot</title>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <para>Starting with VirtualBox 4.2.0 it is possible to start VMs automatically during
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync system boot on Linux and Mac OS X for all users. </para>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <title>Linux: starting the autostart service via <computeroutput>init</computeroutput></title>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <para>On Linux, the autostart service is activated by setting two variables in
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <computeroutput>/etc/default/virtualbox</computeroutput>.
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync The first one is <computeroutput>VBOXAUTOSTART_DB</computeroutput> which
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync contains an absolute path to the autostart database directory.
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync The directory should have write access for every user who should be able to
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync start virtual machines automatically. Furthermore the directory should have the
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync sticky bit set.
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync The second variable is <computeroutput>VBOXAUTOSTART_CONFIG</computeroutput>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync which points the service to the autostart configuration file which is used
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync during boot to determine whether to allow individual users to start a VM
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync automatically and configure startup delays.
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync The config file can be placed in <computeroutput>/etc/vbox</computeroutput>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync and contains several options. One is <computeroutput>default_policy</computeroutput>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync which controls whether the autostart service allows or denies to start a VM
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync for users which are not in the exception list.
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync The exception list starts with <computeroutput>exception_list</computeroutput>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync and contains a comma seperated list with usernames. Furthermore a separate
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync startup delay can be configured for every user to avoid overloading the host.
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync A sample configuration is given below:</para>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync# Default policy is to deny starting a VM, the other option is "allow".
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsyncdefault_policy = deny
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync# Users which are allowed are given below.
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync# If the default policy is to allow starting a VM is not allowed for the users below.
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsyncexception_list = bob, alice, joe
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsyncbob = 30 # Bobs machines will be started 30 seconds after the autostart service started
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsyncalice = 180 # Alice machines will be started 180 seconds after the autostart service started
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsyncjoe = 240 # Joes machines will be started 240 seconds after the autostart service started
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <para>Every user who wants to enable autostart for individual machines
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync has to set the path to the autostart database directory with
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <screen>VBoxManage setproperty autostartdbpath <Autostart directory></screen>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <title>Solaris: starting the autostart service via SMF</title>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <para>On Solaris hosts, the VirtualBox autostart daemon is
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync integrated into the SMF framework. To enable it you have to point the service
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync to an existing configuration file which has the same format as on Linux (see <xref linkend="autostart-linux" />):
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <screen>svccfg -s svc:/application/virtualbox/autostart:default setprop config/config=/etc/vbox/autostart.cfg</screen>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <para>When everything is configured correctly you can start the
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync VirtualBox autostart service with the following command:<screen>svcadm enable svc:/application/virtualbox/autostart:default</screen></para>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <para>For more information about SMF, please refer to the Solaris
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync documentation.</para>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <title>Mac OS X: starting the autostart service via launchd</title>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <para>On Mac OS X, launchd is used to start the VirtualBox autostart service. An
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync example configuration file can be found in
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <computeroutput>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</computeroutput>.
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync To enable the service copy the file to <computeroutput>/Library/LaunchDaemons</computeroutput> and change the
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <computeroutput>false</computeroutput>. Furthermore replace the second parameter
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync to an existing configuration file which has the same format as on Linux (see <xref linkend="autostart-linux" />).
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync To manually start the service use the following command:
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync <screen>launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist</screen>
b0ba64ce3f992684d01d57af5e1dac52799e0757vboxsync For additional information on how launchd services could be