user_AdvancedTopics.xml revision d365a9a356e68215d7111b8f676fa04db1b88c1f
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>VBoxSDL, the simplified VM displayer</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>VBoxSDL is a simple graphical user interface (GUI) that lacks the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync nice point-and-click support which VirtualBox, our main GUI, provides.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VBoxSDL is currently primarily used internally for debugging VirtualBox
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync and therefore not officially supported. Still, you may find it useful
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync for environments where the virtual machines are not necessarily
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync controlled by the same person that uses the virtual machine.<note>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>VBoxSDL is not available on the Mac OS X host platform.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>As you can see in the following screenshot, VBoxSDL does indeed
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync only provide a simple window that contains only the "pure" virtual
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync machine, without menus or other controls to click upon and no additional
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync indicators of virtual machine activity:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <imageobject>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <imagedata align="center" fileref="images/vbox-sdl.png"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync width="10cm" />
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </imageobject>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To start a virtual machine with VBoxSDL instead of the VirtualBox
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync GUI, enter the following on a command line:<screen>VBoxSDL --startvm <vm></screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>where <computeroutput><vm></computeroutput> is, as usual
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with VirtualBox command line parameters, the name or UUID of an existing
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync virtual machine.</para>
6160306df39548f807965d1b3e6953ca2ce92847vboxsync <para>When running guest operating systems in full screen mode, the guest
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync operating system usually has control over the whole screen. This could
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync present a security risk as the guest operating system might fool the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync user into thinking that it is either a different system (which might
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync have a higher security level) or it might present messages on the screen
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync that appear to stem from the host operating system.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>In order to protect the user against the above mentioned security
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync risks, the secure labeling feature has been developed. Secure labeling
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is currently available only for VBoxSDL. When enabled, a portion of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync display area is reserved for a label in which a user defined message is
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync displayed. The label height in set to 20 pixels in VBoxSDL. The label
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync font color and background color can be optionally set as hexadecimal RGB
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync color values. The following syntax is used to enable secure
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync labeling:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>VBoxSDL --startvm "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync --seclabelsiz 14 --seclabelfgcol 00FF00 --seclabelbgcol 00FFFF</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>In addition to enabling secure labeling, a TrueType font has to be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync supplied. To use another font size than 12 point use the parameter
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>--seclabelsiz</computeroutput>.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The label text can be set with <screen>VBoxManage setextradata "VM name" "VBoxSDL/SecureLabel" "The Label"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Changing this label will take effect immediately.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Typically, full screen resolutions are limited to certain
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "standard" geometries such as 1024 x 768. Increasing this by twenty
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync lines is not usually feasible, so in most cases, VBoxSDL will chose the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync next higher resolution, e.g. 1280 x 1024 and the guest's screen will not
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync cover the whole display surface. If VBoxSDL is unable to choose a higher
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync resolution, the secure label will be painted on top of the guest's
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync screen surface. In order to address the problem of the bottom part of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the guest screen being hidden, VBoxSDL can provide custom video modes to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the guest that are reduced by the height of the label. For Windows
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync guests and recent Solaris and Linux guests, the VirtualBox Guest
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Additions automatically provide the reduced video modes. Additionally,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the VESA BIOS has been adjusted to duplicate its standard mode table
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with adjusted resolutions. The adjusted mode IDs can be calculated using
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the following formula:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For example, in order to start Linux with 1024 x 748 x 16, the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync standard mode 0x117 (1024 x 768 x 16) is used as a base. The Linux video
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync mode kernel parameter can then be calculated using:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>vga = 0x200 | 0x117 + 0x30
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvga = 839</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The reason for duplicating the standard modes instead of only
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync supplying the adjusted modes is that most guest operating systems
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync require the standard VESA modes to be fixed and refuse to start with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync different modes.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>When using the X.org VESA driver, custom modelines have to be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync calculated and added to the configuration (usually in
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <literal>/etc/X11/xorg.conf</literal>. A handy tool to determine
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync url="http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html">http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html</ulink></literal>.)</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Releasing modifiers with VBoxSDL on Linux</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>When switching from a X virtual terminal (VT) to another VT using
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Ctrl-Alt-Fx while the VBoxSDL window has the input focus, the guest will
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync receive Ctrl and Alt keypress events without receiving the corresponding
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync key release events. This is an architectural limitation of Linux. In
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync order to reset the modifier keys, it is possible to send
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>SIGUSR1</computeroutput> to the VBoxSDL main thread
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync (first entry in the <computeroutput>ps</computeroutput> list). For
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync example, when switching away to another VT and saving the virtual
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync machine from this terminal, the following sequence can be used to make
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync sure the VM is not saved with stuck modifiers:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncVBoxManage controlvm "Windows 2000" savestate</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title id="autologon">Automated guest logons</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>VirtualBox provides Guest Addition modules for Windows, Linux and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Solaris to enable automated logons on the guest.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>When a guest operating system is running in a virtual machine, it
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync might be desirable to perform coordinated and automated logons using
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync credentials from a master logon system. (With "credentials", we are
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync referring to logon information consisting of user name, password and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync domain name, where each value might be empty.)</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Since Windows NT, Windows has provided a modular system logon
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync subsystem ("Winlogon") which can be customized and extended by means of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync so-called GINA modules (Graphical Identification and Authentication).
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync With Windows Vista and Windows 7, the GINA modules were replaced with a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync new mechanism called "credential providers". The VirtualBox Guest
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Additions for Windows come with both, a GINA and a credential provider
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync module, and therefore enable any Windows guest to perform automated
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync logons.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To activate the VirtualBox GINA or credential provider module,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync install the Guest Additions with using the command line switch
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>/with_autologon</computeroutput>. All the following
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync manual steps required for installing these modules will be then done by
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the installer.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To manually install the VirtualBox GINA module, extract the Guest
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Additions (see <xref linkend="windows-guest-file-extraction" />) and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync copy the file <computeroutput>VBoxGINA.dll</computeroutput> to the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Windows <computeroutput>SYSTEM32</computeroutput> directory. Then, in
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync the registry, create the following key: <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with a value of <computeroutput>VBoxGINA.dll</computeroutput>.</para>
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync <para>The VirtualBox GINA module is implemented as a wrapper around
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync the standard Windows GINA module
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync (<computeroutput>MSGINA.DLL</computeroutput>). As a result, it will
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync most likely not work correctly with 3rd party GINA modules.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>To manually install the VirtualBox credential provider module,
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync extract the Guest Additions (see <xref
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync linkend="windows-guest-file-extraction" />) and copy the file
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <computeroutput>VBoxCredProv.dll</computeroutput> to the Windows
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <computeroutput>SYSTEM32</computeroutput> directory. Then, in the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync registry, create the following keys:<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Authentication\Credential Providers\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
304f31a2a37f5d690086bff2fb4a59228b4dbd40vboxsyncHKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
304f31a2a37f5d690086bff2fb4a59228b4dbd40vboxsyncHKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>with all default values (the key named
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>(Default)</computeroutput> in each key) set to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxCredProv</computeroutput>. After that a new string
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync named <screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with a value of <computeroutput>Apartment</computeroutput> has to be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync created.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To set credentials, use the following command on a
dbabcd810984fc0731edff08eb281f0907dc867avboxsync <screen>VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>While the VM is running, the credentials can be queried by the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox logon modules (GINA or credential provider) using the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox Guest Additions device driver. When Windows is in "logged
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync out" mode, the logon modules will constantly poll for credentials and if
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync they are present, a logon will be attempted. After retrieving the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync credentials, the logon modules will erase them so that the above command
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync will have to be repeated for subsequent logons.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For security reasons, credentials are not stored in any persistent
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync manner and will be lost when the VM is reset. Also, the credentials are
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "write-only", i.e. there is no way to retrieve the credentials from the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync host side. Credentials can be reset from the host side by setting empty
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync values.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Depending on the particular variant of the Windows guest, the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync following restrictions apply: <orderedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For <emphasis role="bold">Windows XP guests,</emphasis> the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync logon subsystem needs to be configured to use the classic logon
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync dialog as the VirtualBox GINA module does not support the XP-style
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync welcome dialog.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
bf721ef38b15c00c9bbfcedb11dbc61f8bd71816vboxsync <para>For <emphasis role="bold">Windows Vista, Windows 7
bf721ef38b15c00c9bbfcedb11dbc61f8bd71816vboxsync and Windows 8 guests,</emphasis> the logon subsystem does not support
bf721ef38b15c00c9bbfcedb11dbc61f8bd71816vboxsync the so-called Secure Attention Sequence
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync (<computeroutput>CTRL+ALT+DEL</computeroutput>). As a result, the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync guest's group policy settings need to be changed to not use the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Secure Attention Sequence. Also, the user name given is only
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync compared to the true user name, not the user friendly name. This
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync means that when you rename a user, you still have to supply the
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync original user name (internally, Windows never renames user
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync accounts).</para>
f2cb8c82257cb6af3622059e397d46af7c774b63vboxsync </listitem>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>Auto-logon handling of the built-in Windows Remote Desktop
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync Service (formerly known as Terminal Services) is disabled by
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync default. To enable it, create the registry key <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync with a <computeroutput>DWORD</computeroutput> value of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The following command forces VirtualBox to keep the credentials
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync 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
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync that this is a potential security risk as a malicious application
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync running on the guest could request this information using the proper
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync interface.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Starting with version 3.2, VirtualBox provides a custom PAM module
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync (Pluggable Authentication Module) which can be used to perform automated
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync guest logons on platforms which support this framework. Virtually all
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync modern Linux/Unix distributions rely on PAM.</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para>For automated logons on Ubuntu (or Ubuntu-derived) distributions
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync using LightDM as the display manager, please see
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The <computeroutput>pam_vbox.so</computeroutput> module itself
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <emphasis role="bold">does not</emphasis> do an actual verification of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the credentials passed to the guest OS; instead it relies on other
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync modules such as <computeroutput>pam_unix.so</computeroutput> or
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>pam_unix2.so</computeroutput> down in the PAM stack to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync do the actual validation using the credentials retrieved by
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>pam_vbox.so</computeroutput>. Therefore
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>pam_vbox.so</computeroutput> has to be on top of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync authentication PAM service list.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The <computeroutput>pam_vbox.so</computeroutput> only supports
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the <computeroutput>auth</computeroutput> primitive. Other primitives
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>password</computeroutput> are not supported.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The <computeroutput>pam_vbox.so</computeroutput> module is shipped
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync as part of the Guest Additions but it is not installed and/or activated
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync on the guest OS by default. In order to install it, it has to be copied
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>/opt/VBoxGuestAdditions-<version>/lib/VBoxGuestAdditions/</computeroutput>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to the security modules directory, usually
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <computeroutput>/lib/security/</computeroutput> on 32-bit guest Linuxes
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync or <computeroutput>/lib64/security/</computeroutput> on 64-bit ones.
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync Please refer to your guest OS documentation for the correct PAM module
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync directory.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For example, to use <computeroutput>pam_vbox.so</computeroutput>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with a Ubuntu Linux guest OS and GDM (the GNOME Desktop Manager) to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync logon users automatically with the credentials passed by the host, the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync guest OS has to be configured like the following:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <orderedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The <computeroutput>pam_vbox.so</computeroutput> module has to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync be copied to the security modules directory, in this case it is
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>/lib/security</computeroutput>.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Edit the PAM configuration file for GDM found at
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>/etc/pam.d/gdm</computeroutput>, adding the line
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>auth requisite pam_vbox.so</computeroutput> at the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync top. Additionaly, in most Linux distributions there is a file called
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>/etc/pam.d/common-auth</computeroutput>. This file
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is included in many other services (like the GDM file mentioned
2c38b10f3657b32c27c489ef9aede24003a64fa5vboxsync above). There you also have to add the line <computeroutput>auth
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>If authentication against the shadow database using
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>pam_unix2.so</computeroutput> is desired, the
e72d867f5d519d040e3e8a7f842e42bdc5120c5bvboxsync argument <computeroutput>try_first_pass</computeroutput> for
e72d867f5d519d040e3e8a7f842e42bdc5120c5bvboxsync <computeroutput>use_first_pass</computeroutput> for
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <computeroutput>pam_unix2.so</computeroutput> is needed in order to
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync pass the credentials from the VirtualBox module to the shadow
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync database authentication module. For Ubuntu, this needs to be added
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync to <computeroutput>/etc/pam.d/common-auth</computeroutput>, to the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync end of the line referencing
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>pam_unix.so</computeroutput>. This argument tells
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the PAM module to use credentials already present in the stack, i.e.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the ones provided by the VirtualBox PAM module.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </orderedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>An incorrectly configured PAM stack can effectively prevent
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync you from logging into your guest system!</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To make deployment easier, you can pass the argument
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>debug</computeroutput> right after the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>pam_vbox.so</computeroutput> statement. Debug log output
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync will then be recorded using syslog.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>By default, pam_vbox will not wait for credentials to arrive
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync from the host, in other words: When a login prompt is shown (for
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync example by GDM/KDM or the text console) and pam_vbox does not yet
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync have credentials it does not wait until they arrive. Instead the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync next module in the PAM stack (depending on the PAM configuration)
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync will have the chance for authentication.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>Starting with VirtualBox 4.1.4 pam_vbox supports various guest
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync property parameters which all reside in
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <computeroutput>/VirtualBox/GuestAdd/PAM/</computeroutput>. These
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync parameters allow pam_vbox to wait for credentials to be provided by the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync host and optionally can show a message while waiting for those. The
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync following guest properties can be set:</para>
e579762795d321fd9390ae09c881e35c8107506fvboxsync <orderedlist>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para><computeroutput>CredsWait</computeroutput>: Set to "1" if
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync pam_vbox should start waiting until credentials arrive from the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync host. Until then no other authentication methods such as manually
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync logging in will be available. If this property is empty or get
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync deleted no waiting for credentials will be performed and pam_vbox
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync will act like before (see paragraph above). This property must be
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync set read-only for the guest
e579762795d321fd9390ae09c881e35c8107506fvboxsync (<computeroutput>RDONLYGUEST</computeroutput>).</para>
e579762795d321fd9390ae09c881e35c8107506fvboxsync </listitem>
75d67a5757951aa64bf3887a70db379e1feb84aavboxsync <para><computeroutput>CredsWaitAbort</computeroutput>: Aborts waiting
75d67a5757951aa64bf3887a70db379e1feb84aavboxsync for credentials when set to any value. Can be set from host and the
75d67a5757951aa64bf3887a70db379e1feb84aavboxsync guest.</para>
e579762795d321fd9390ae09c881e35c8107506fvboxsync </listitem>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para><computeroutput>CredsWaitTimeout</computeroutput>: Timeout (in
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync seconds) to let pam_vbox wait for credentials to arrive. When no
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync credentials arrive within this timeout, authentication of pam_vbox
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync will be set to failed and the next PAM module in chain will be
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync asked. If this property is not specified, set to "0" or an invalid
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync value, an infinite timeout will be used. This property must be set
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync read-only for the guest
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync (<computeroutput>RDONLYGUEST</computeroutput>).</para>
e579762795d321fd9390ae09c881e35c8107506fvboxsync </listitem>
e579762795d321fd9390ae09c881e35c8107506fvboxsync </orderedlist>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>To customize pam_vbox further there are the following guest
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync properties:</para>
e579762795d321fd9390ae09c881e35c8107506fvboxsync <orderedlist>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para><computeroutput>CredsMsgWaiting</computeroutput>: Custom
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync message showed while pam_vbox is waiting for credentials from the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync host. This property must be set read-only for the guest
e579762795d321fd9390ae09c881e35c8107506fvboxsync (<computeroutput>RDONLYGUEST</computeroutput>).</para>
e579762795d321fd9390ae09c881e35c8107506fvboxsync </listitem>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para><computeroutput>CredsMsgWaitTimeout</computeroutput>: Custom
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync message showed when waiting for credentials by pam_vbox timed out,
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync e.g. did not arrive within time. This property must be set read-only
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync for the guest (<computeroutput>RDONLYGUEST</computeroutput>).</para>
e579762795d321fd9390ae09c881e35c8107506fvboxsync </listitem>
e579762795d321fd9390ae09c881e35c8107506fvboxsync </orderedlist>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>If a pam_vbox guest property does not have set the right flags
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync (<computeroutput>RDONLYGUEST</computeroutput>) this property will be
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync ignored then and - depending on the property - a default value will
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync be set. This can result in pam_vbox not waiting for credentials.
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync Consult the appropriate syslog file for more information and use the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <computeroutput>debug</computeroutput> option.</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <title>VirtualBox Greeter for Ubuntu / LightDM</title>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para>Starting with version 4.2.6, VirtualBox comes with an own greeter
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync module named vbox-greeter which can be used with LightDM 1.0.1 or later.
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync LightDM is the default display manager since Ubuntu 10.11 and therefore
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync also can be used for automated guest logons.</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para>vbox-greeter does not need the pam_vbox module described above
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync in order to function -- it comes with its own authentication mechanism
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync provided by LightDM. However, to provide maximum of flexibility both
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync modules can be used together on the same guest.</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para>As for the pam_vbox module, vbox-greeter is shipped as part of
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync the Guest Additions but it is not installed and/or activated on the
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync guest OS by default For installing vbox-greeter automatically upon
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync Guest Additions installation, use the
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <computeroutput>--with-autologon</computeroutput> switch when starting
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync # /VBoxLinuxAdditions.run -- --with-autologon</screen></para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para>For manual or postponed installation, the
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <computeroutput>vbox-greeter.desktop</computeroutput>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync file has to be copied from
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <computeroutput>/opt/VBoxGuestAdditions-<version>/shared/VBoxGuestAdditions/</computeroutput>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync to the <computeroutput>xgreeters</computeroutput> directory, usually
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <computeroutput>/usr/share/xgreeters/</computeroutput>.
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync Please refer to your guest OS documentation for the correct LightDM
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync greeter directory.</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para>The vbox-greeter module itself already was installed by the
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync VirtualBox Guest Additions installer and resides in
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <computeroutput>/usr/sbin/</computeroutput>. To enable vbox-greeter as
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync the standard greeter module, the file
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <computeroutput>/etc/lightdm/lightdm.conf</computeroutput> needs to be
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync edited:</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync [SeatDefaults]
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <note><para>The LightDM server needs to be fully restarted in order to
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync get vbox-greeter used as the default greeter. As root, do a
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <computeroutput>service lightdm --full-restart</computeroutput> on
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <note><para>vbox-greeter is independent of the graphical session chosen
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync by the user (like Gnome, KDE, Unity etc). However it requires FLTK 1.3
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para>In addition to the guest property values of the
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync pam_vbox module listed above, vbox-greeter has the following guest
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync properties for further customizing its user interface, residing all in
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <computeroutput>/VirtualBox/GuestAdd/Greeter/</computeroutput>:</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <orderedlist>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para><computeroutput>HideRestart</computeroutput>: Set to "1" if
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync vbox-greeter should hide the button to restart the guest. This
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync property must be set read-only for the guest
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync (<computeroutput>RDONLYGUEST</computeroutput>).</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync </listitem>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para><computeroutput>HideShutdown</computeroutput>: Set to "1" if
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync vbox-greeter should hide the button to shutdown the guest. This
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync property must be set read-only for the guest
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync (<computeroutput>RDONLYGUEST</computeroutput>).</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync </listitem>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para><computeroutput>BannerPath</computeroutput>: Path to a .PNG
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync file for using it as a banner on the top. The image size must be
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync 460 x 90 pixels, any bit depth. This property must be
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync set read-only for the guest
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync (<computeroutput>RDONLYGUEST</computeroutput>).</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync </listitem>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para><computeroutput>UseTheming</computeroutput>: Set to "1" for
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync turning on the following theming options. This property must be
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync set read-only for the guest
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync (<computeroutput>RDONLYGUEST</computeroutput>).</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync </listitem>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para><computeroutput>Theme/BackgroundColor</computeroutput>:
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync Hexadecimal RRGGBB color for the background. This property must be
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync set read-only for the guest
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync (<computeroutput>RDONLYGUEST</computeroutput>).</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync </listitem>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para><computeroutput>Theme/LogonDialog/HeaderColor</computeroutput>:
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync Hexadecimal RRGGBB foreground color for the header text. This
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync property must be set read-only for the guest
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync (<computeroutput>RDONLYGUEST</computeroutput>).</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync </listitem>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para><computeroutput>Theme/LogonDialog/BackgroundColor</computeroutput>:
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync Hexadecimal RRGGBB color for the logon dialog background. This
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync property must be set read-only for the guest
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync (<computeroutput>RDONLYGUEST</computeroutput>).</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync </listitem>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <para><computeroutput>Theme/LogonDialog/ButtonColor</computeroutput>:
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync Hexadecimal RRGGBB background color for the logon dialog button. This
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync property must be set read-only for the guest
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync (<computeroutput>RDONLYGUEST</computeroutput>).</para>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync </listitem>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync </orderedlist>
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync <note><para>The same restrictions for the guest properties above apply
d365a9a356e68215d7111b8f676fa04db1b88c1fvboxsync as for the ones specified in the pam_vbox section.</para></note>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Advanced configuration for Windows guests</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Automated Windows system preparation</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Beginning with Windows NT 4.0, Microsoft offers a "system
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync preparation" tool (in short: Sysprep) to prepare a Windows system for
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync deployment or redistribution. Whereas Windows 2000 and XP ship with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Sysprep on the installation medium, the tool also is available for
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync download on the Microsoft web site. In a standard installation of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Windows Vista and 7, Sysprep is already included. Sysprep mainly
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync consists of an executable called
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync <computeroutput>sysprep.exe</computeroutput> which is invoked by the
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync user to put the Windows installation into preparation mode.</para>
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync <para>Starting with VirtualBox 3.2.2, the Guest Additions offer a way to
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync launch a system preparation on the guest operating system in an
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync automated way, controlled from the host system. To achieve that, see
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync <xref linkend="guestadd-guestcontrol" /> for using the feature with the
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync special identifier <computeroutput>sysprep</computeroutput> as the
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync program to execute, along with the user name
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync <computeroutput>sysprep</computeroutput> and password
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync <computeroutput>sysprep</computeroutput> for the credentials. Sysprep
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync then gets launched with the required system rights.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Specifying the location of "sysprep.exe" is <emphasis
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync role="bold">not possible</emphasis> -- instead the following paths are
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync used (based on the operating system): <itemizedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para><computeroutput>C:\sysprep\sysprep.exe</computeroutput>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync for Windows NT 4.0, 2000 and XP</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para><computeroutput>%WINDIR%\System32\Sysprep\sysprep.exe</computeroutput>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync for Windows Vista, 2008 Server and 7</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync </itemizedlist> The Guest Additions will automatically use the
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync appropriate path to execute the system preparation tool.</para>
4c303299e657f3cfd3c6db618e443b93e5b814a2vboxsync <title>Advanced configuration for Linux and Solaris guests</title>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <title>Manual setup of selected guest services on Linux</title>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>The VirtualBox Guest Additions contain several different drivers.
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync If for any reason you do not wish to set them all up, you can install
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync the Guest Additions using the following command:</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <screen> sh /VBoxLinuxAdditions.run no_setup</screen>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>After this, you will need to at least compile the kernel modules
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync by running the command <screen> /usr/lib/VBoxGuestAdditions/vboxadd setup</screen>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync as root (you will need to replace <emphasis>lib</emphasis> by
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <emphasis>lib64</emphasis> on some 64bit guests), and on older guests
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync without the udev service you will need to add the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <emphasis>vboxadd</emphasis> service to the default runlevel to ensure
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync that the modules get loaded.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>To setup the time synchronization service, run the command
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <screen> /usr/lib/VBoxGuestAdditions/vboxadd-service setup</screen> and
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync add the service vboxadd-service to the default runlevel. To set up the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync X11 and OpenGL part of the Guest Additions, run the command <screen> /usr/lib/VBoxGuestAdditions/vboxadd-x11 setup</screen>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync (you do not need to enable any services for this).</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>To recompile the guest kernel modules, use this command: <screen> /usr/lib/VBoxGuestAdditions/vboxadd setup</screen>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync After compilation you should reboot your guest to ensure that the new
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync modules are actually used.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <title>Guest graphics and mouse driver setup in depth</title>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>This section assumes that you are familiar with configuring the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync X.Org server using xorg.conf and optionally the newer mechanisms using
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync hal or udev and xorg.conf.d. If not you can learn about them by studying
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>The VirtualBox Guest Additions come with drivers for X.Org
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync versions <itemizedlist>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync X11R6.8/X11R6.9 and XFree86 version 4.3 (vboxvideo_drv_68.o and vboxmouse_drv_68.o)
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync </listitem>
75d67a5757951aa64bf3887a70db379e1feb84aavboxsync X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so)
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync </listitem>
75d67a5757951aa64bf3887a70db379e1feb84aavboxsync X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so)
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync </listitem>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync X.Org Server versions 1.3 and later (vboxvideo_drv_13.so and vboxmouse_drv_13.so and so on).
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync </listitem>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync </itemizedlist> By default these drivers can be found in the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync directory</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para><computeroutput>/opt/VBoxGuestAdditions-<version>/lib/VBoxGuestAdditions</computeroutput></para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>and the correct versions for the X server are symbolically linked
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>For graphics integration to work correctly, the X server must load
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync the vboxvideo driver (many recent X server versions look for it
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync automatically if they see that they are running in VirtualBox) and for
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync an optimal user experience the guest kernel drivers must be loaded and
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync the Guest Additions tool VBoxClient must be running as a client in the X
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync session. For mouse integration to work correctly, the guest kernel
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync drivers must be loaded and in addition, in X servers from X.Org X11R6.8
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync to X11R7.1 and in XFree86 version 4.3 the right vboxmouse driver must be
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync loaded and associated with /dev/mouse or /dev/psaux; in X.Org server 1.3
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync or later a driver for a PS/2 mouse must be loaded and the right
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync vboxmouse driver must be associated with /dev/vboxguest.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>The VirtualBox guest graphics driver can use any graphics
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync configuration for which the virtual resolution fits into the virtual
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync video memory allocated to the virtual machine (minus a small amount used
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync by the guest driver) as described in <xref
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync linkend="settings-display" />. The driver will offer a range of standard
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync modes at least up to the default guest resolution for all active guest
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync monitors. In X.Org Server 1.3 and later the default mode can be changed
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync by setting the output property VBOX_MODE to
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync "<width>x<height>" for any guest monitor. When VBoxClient
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync and the kernel drivers are active this is done automatically when the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync host requests a mode change. The driver for older versions can only
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync receive new modes by querying the host for requests at regular
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync intervals.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>With pre-1.3 X Servers you can also add your own modes to the X
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync server configuration file. You simply need to add them to the "Modes"
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync list in the "Display" subsection of the "Screen" section. For example,
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync the section shown here has a custom 2048x800 resolution mode
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync added:</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <screen>Section "Screen"
4c303299e657f3cfd3c6db618e443b93e5b814a2vboxsync Identifier "Default Screen"
4c303299e657f3cfd3c6db618e443b93e5b814a2vboxsync Device "VirtualBox graphics card"
4c303299e657f3cfd3c6db618e443b93e5b814a2vboxsync Monitor "Generic Monitor"
4c303299e657f3cfd3c6db618e443b93e5b814a2vboxsync DefaultDepth 24
4c303299e657f3cfd3c6db618e443b93e5b814a2vboxsync SubSection "Display"
4c303299e657f3cfd3c6db618e443b93e5b814a2vboxsync Modes "2048x800" "800x600" "640x480"
4c303299e657f3cfd3c6db618e443b93e5b814a2vboxsync EndSubSection
4c303299e657f3cfd3c6db618e443b93e5b814a2vboxsyncEndSection</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>With virtual machines running modern server operating systems,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox supports CPU hot-plugging.<footnote>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Support for CPU hot-plugging was introduced with VirtualBox
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 3.2.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </footnote> Whereas on a physical computer this would mean that a CPU
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync can be added or removed while the machine is running, VirtualBox supports
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync adding and removing virtual CPUs while a virtual machine is
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync running.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>CPU hot-plugging works only with guest operating systems that
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync support it. So far this applies only to Linux and Windows Server 2008 x64
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Data Center Edition. Windows supports only hot-add while Linux supports
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync hot-add and hot-remove but to use this feature with more than 8 CPUs a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 64bit Linux guest is required.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>At this time, CPU hot-plugging requires using the VBoxManage
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync command-line interface. First, hot-plugging needs to be enabled for a
dbabcd810984fc0731edff08eb281f0907dc867avboxsync virtual machine:<screen>VBoxManage modifyvm "VM name" --cpuhotplug on</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>After that, the --cpus option specifies the maximum number of CPUs
dbabcd810984fc0731edff08eb281f0907dc867avboxsync that the virtual machine can have:<screen>VBoxManage modifyvm "VM name" --cpus 8</screen>When
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the VM is off, you can then add and remove virtual CPUs with the modifyvm
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync --plugcpu and --unplugcpu subcommands, which take the number of the
dbabcd810984fc0731edff08eb281f0907dc867avboxsync virtual CPU as a parameter, like this:<screen>VBoxManage modifyvm "VM name" --plugcpu 3
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsyncVBoxManage modifyvm "VM name" --unplugcpu 3</screen>Note that CPU 0 can never
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync be removed.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>While the VM is running, CPUs can be added with the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>controlvm plugcpu/unplugcpu</computeroutput> commands
dbabcd810984fc0731edff08eb281f0907dc867avboxsync instead:<screen>VBoxManage controlvm "VM name" plugcpu 3
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage controlvm "VM name" unplugcpu 3</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>See <xref linkend="vboxmanage-modifyvm" /> and <xref
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync linkend="vboxmanage-controlvm" /> for details.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>With Linux guests, the following applies: To prevent ejection while
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the CPU is still used it has to be ejected from within the guest before.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync The Linux Guest Additions contain a service which receives hot-remove
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync events and ejects the CPU. Also, after a CPU is added to the VM it is not
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync automatically used by Linux. The Linux Guest Additions service will take
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync care of that if installed. If not a CPU can be started with the following
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync command:<screen>echo 1 > /sys/devices/system/cpu/cpu<id>/online</screen></para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>When running on Linux hosts, with a recent enough kernel (at least
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync version <computeroutput>2.6.31</computeroutput>) experimental host PCI
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync devices passthrough is available.<footnote>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>Experimental support for PCI passthrough was introduced with
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync VirtualBox 4.1.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>The PCI passthrough module is shipped as a VirtualBox extension
d6a533c77fa274df5ee0e592c6abfa73549f2b34vboxsync package, which must be installed separately. See <xref
d6a533c77fa274df5ee0e592c6abfa73549f2b34vboxsync linkend="intro-installing" /> for more information.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>Essentially this feature allows to directly use physical PCI devices
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync on the host by the guest even if host doesn't have drivers for this
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync particular device. Both, regular PCI and some PCI Express cards, are
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync supported. AGP and certain PCI Express cards are not supported at the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync moment if they rely on GART (Graphics Address Remapping Table) unit
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync programming for texture management as it does rather nontrivial operations
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync with pages remapping interfering with IOMMU. This limitation may be lifted
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync in future releases.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>To be fully functional, PCI passthrough support in VirtualBox
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync depends upon an IOMMU hardware unit which is not yet too widely available.
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync If the device uses bus mastering (i.e. it performs DMA to the OS memory on
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync its own), then an IOMMU is required, otherwise such DMA transactions may
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync write to the wrong physical memory address as the device DMA engine is
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync programmed using a device-specific protocol to perform memory
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync transactions. The IOMMU functions as translation unit mapping physical
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync memory access requests from the device using knowledge of the guest
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync physical address to host physical addresses translation rules.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>Intel's solution for IOMMU is marketed as "Intel Virtualization
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync Technology for Directed I/O" (VT-d), and AMD's one is called AMD-Vi. So
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync please check if your motherboard datasheet has appropriate technology.
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync Even if your hardware doesn't have a IOMMU, certain PCI cards may work
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync (such as serial PCI adapters), but the guest will show a warning on boot
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync and the VM execution will terminate if the guest driver will attempt to
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync enable card bus mastering.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>It is very common that the BIOS or the host OS disables the IOMMU by
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync default. So before any attempt to use it please make sure that
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <orderedlist>
4c7080424765b6ab6900953b3736e857318a6126vboxsync </listitem>
4c7080424765b6ab6900953b3736e857318a6126vboxsync </listitem>
4c7080424765b6ab6900953b3736e857318a6126vboxsync </listitem>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>The VM must run with VT-x/AMD-V and nested paging
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync enabled.</para>
4c7080424765b6ab6900953b3736e857318a6126vboxsync </listitem>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>Your Linux kernel was compiled with IOMMU support (including
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync DMA remapping, see <computeroutput>CONFIG_DMAR</computeroutput>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync kernel compilation option). The PCI stub driver
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync (<computeroutput>CONFIG_PCI_STUB</computeroutput>) is required as
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync well.</para>
d6a533c77fa274df5ee0e592c6abfa73549f2b34vboxsync </listitem>
d6a533c77fa274df5ee0e592c6abfa73549f2b34vboxsync <para>Your Linux kernel recognizes and uses the IOMMU unit
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync (<computeroutput>intel_iommu=on</computeroutput> boot option could
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync be needed). Search for DMAR and PCI-DMA in kernel boot log.</para>
4c7080424765b6ab6900953b3736e857318a6126vboxsync </listitem>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>Once you made sure that the host kernel supports the IOMMU, the next
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync step is to select the PCI card and attach it to the guest. To figure out
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync the list of available PCI devices, use the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <computeroutput>lspci</computeroutput> command. The output will look like
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync this <screen>
4c7080424765b6ab6900953b3736e857318a6126vboxsync 01:00.0 VGA compatible controller: ATI Technologies Inc Cedar PRO [Radeon HD 5450]
4c7080424765b6ab6900953b3736e857318a6126vboxsync 01:00.1 Audio device: ATI Technologies Inc Manhattan HDMI Audio [Mobility Radeon HD 5000 Series]
4c7080424765b6ab6900953b3736e857318a6126vboxsync 02:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168B PCI Express Gigabit Ethernet controller (rev 03)
4c7080424765b6ab6900953b3736e857318a6126vboxsync 03:00.0 SATA controller: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
4c7080424765b6ab6900953b3736e857318a6126vboxsync 03:00.1 IDE interface: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
4c7080424765b6ab6900953b3736e857318a6126vboxsync 06:00.0 VGA compatible controller: nVidia Corporation G86 [GeForce 8500 GT] (rev a1)
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync </screen> The first column is a PCI address (in format
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <computeroutput>bus:device.function</computeroutput>). This address could
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync be used to identify the device for further operations. For example, to
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync attach a PCI network controller on the system listed above to the second
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync PCI bus in the guest, as device 5, function 0, use the following command:
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <screen>VBoxManage modifyvm "VM name" --pciattach 02:00.0@01:05.0</screen>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync To detach same device, use <screen>VBoxManage modifyvm "VM name" --pcidetach 02:00.0</screen>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync Please note that both host and guest could freely assign a different PCI
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync address to the card attached during runtime, so those addresses only apply
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync to the address of the card at the moment of attachment (host), and during
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync BIOS PCI init (guest).</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>If the virtual machine has a PCI device attached, certain
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync limitations apply: <orderedlist>
75d67a5757951aa64bf3887a70db379e1feb84aavboxsync Only PCI cards with non-shared interrupts (such as using MSI on host) are supported at the moment.
4c7080424765b6ab6900953b3736e857318a6126vboxsync </listitem>
75d67a5757951aa64bf3887a70db379e1feb84aavboxsync No guest state can be reliably saved/restored (as the internal state of the PCI card could not be retrieved).
4c7080424765b6ab6900953b3736e857318a6126vboxsync </listitem>
75d67a5757951aa64bf3887a70db379e1feb84aavboxsync Teleportation (live migration) doesn't work (for the same reason).
2087cc1f185f94ea367e4bba400e039159e7ec3cvboxsync </listitem>
75d67a5757951aa64bf3887a70db379e1feb84aavboxsync No lazy physical memory allocation. The host will preallocate the whole RAM required for the VM on startup (as we cannot catch physical hardware accesses to the physical memory).
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Apart from the standard VESA resolutions, the VirtualBox VESA BIOS
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync allows you to add up to 16 custom video modes which will be reported to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the guest operating system. When using Windows guests with the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox Guest Additions, a custom graphics driver will be used
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync instead of the fallback VESA solution so this information does not
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync apply.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Additional video modes can be configured for each VM using the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync extra data facility. The extra data key is called
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <literal>CustomVideoMode<x></literal> with <literal>x</literal>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync being a number from 1 to 16. Please note that modes will be read from 1
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync until either the following number is not defined or 16 is reached. The
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync following example adds a video mode that corresponds to the native
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync display resolution of many notebook computers:</para>
dbabcd810984fc0731edff08eb281f0907dc867avboxsync <screen>VBoxManage setextradata "VM name" "CustomVideoMode1" "1400x1050x16"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The VESA mode IDs for custom video modes start at
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <literal>0x160</literal>. In order to use the above defined custom video
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync mode, the following command line has be supplied to Linux:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>vga = 0x200 | 0x160
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvga = 864</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For guest operating systems with VirtualBox Guest Additions, a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync custom video mode can be set using the video mode hint feature.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Configuring the maximum resolution of guests when using the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync graphical frontend</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>When guest systems with the Guest Additions installed are started
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync using the graphical frontend (the normal VirtualBox application), they
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync will not be allowed to use screen resolutions greater than the host's
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync screen size unless the user manually resizes them by dragging the
6160306df39548f807965d1b3e6953ca2ce92847vboxsync window, switching to full screen or seamless mode or sending a video mode
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync hint using VBoxManage. This behavior is what most users will want, but
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync if you have different needs, it is possible to change it by issuing one
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync of the following commands from the command line:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>VBoxManage setextradata global GUI/MaxGuestResolution any</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>will remove all limits on guest resolutions.</para>
dbabcd810984fc0731edff08eb281f0907dc867avboxsync <screen>VBoxManage setextradata global GUI/MaxGuestResolution >width,height<</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>manually specifies a maximum resolution.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>VBoxManage setextradata global GUI/MaxGuestResolution auto</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>restores the default settings. Note that these settings apply
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync globally to all guest systems, not just to a single machine.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Using a raw host hard disk from a guest</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Starting with version 1.4, as an alternative to using virtual disk
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync images (as described in detail in <xref linkend="storage" />),
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox can also present either entire physical hard disks or
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync selected partitions thereof as virtual disks to virtual machines.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>With VirtualBox, this type of access is called "raw hard disk
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync access"; it allows a guest operating system to access its virtual hard
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync disk without going through the host OS file system. The actual
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync performance difference for image files vs. raw disk varies greatly
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync depending on the overhead of the host file system, whether dynamically
531197d0c66f247938034384b933cc002ed6441evboxsync growing images are used, and on host OS caching strategies. The caching
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync indirectly also affects other aspects such as failure behavior, i.e.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync whether the virtual disk contains all data written before a host OS
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync crash. Consult your host OS documentation for details on this.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Raw hard disk access is for expert users only. Incorrect use
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync or use of an outdated configuration can lead to <emphasis
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync role="bold">total loss of data </emphasis>on the physical disk. Most
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync importantly, <emphasis>do not</emphasis> attempt to boot the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync partition with the currently running host operating system in a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync guest. This will lead to severe data corruption.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Raw hard disk access -- both for entire disks and individual
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync partitions -- is implemented as part of the VMDK image format support.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync As a result, you will need to create a special VMDK image file which
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync defines where the data will be stored. After creating such a special
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VMDK image, you can use it like a regular virtual disk image. For
531197d0c66f247938034384b933cc002ed6441evboxsync example, you can use the VirtualBox Manager (<xref linkend="vdis" />)
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync or <computeroutput>VBoxManage</computeroutput> to assign the image to a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync virtual machine.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>While this variant is the simplest to set up, you must be aware
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync that this will give a guest operating system direct and full access to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync an <emphasis>entire physical disk</emphasis>. If your
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <emphasis>host</emphasis> operating system is also booted from this
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync disk, please take special care to not access the partition from the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync guest at all. On the positive side, the physical disk can be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync repartitioned in arbitrary ways without having to recreate the image
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync file that gives access to the raw disk.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To create an image that represents an entire physical hard disk
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync (which will not contain any actual data, as this will all be stored on
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the physical disk), on a Linux host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <code>/path/to/file.vmdk</code> (must be absolute), and all data will
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync be read and written from <code>/dev/sda</code>.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>On a Windows host, instead of the above device specification,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host, instead
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync of the above device specification use e.g. <code>/dev/disk1</code>.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Note that on OS X you can only get access to an entire disk if no
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync volume is mounted from it.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Creating the image requires read/write access for the given
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync device. Read/write access is also later needed when using the image
531197d0c66f247938034384b933cc002ed6441evboxsync from a virtual machine. On some host platforms (e.g. Windows Vista
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync and later), raw disk access may be restricted and not permitted by
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync the host OS in some situations.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Just like with regular disk images, this does not automatically
c551f0f256f0a10f4fde1610cc0e200bd01e3663vboxsync attach the newly created image to a virtual machine. This can be done
2efd74fc9286676f97464d908ad84285b06c0946vboxsync with e.g. <screen>VBoxManage storageattach WindowsXP --storagectl "IDE Controller"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync --port 0 --device 0 --type hdd --medium /path/to/file.vmdk</screen>When
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync this is done the selected virtual machine will boot from the specified
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync physical disk.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Access to individual physical hard disk partitions</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>This "raw partition support" is quite similar to the "full hard
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync disk" access described above. However, in this case, any partitioning
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync information will be stored inside the VMDK image, so you can e.g.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync install a different boot loader in the virtual hard disk without
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync affecting the host's partitioning information. While the guest will be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync able to <emphasis>see</emphasis> all partitions that exist on the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync physical disk, access will be filtered in that reading from partitions
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync for which no access is allowed the partitions will only yield zeroes,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync and all writes to them are ignored.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To create a special image for raw partition support (which will
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync contain a small amount of data, as already mentioned), on a Linux
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>As you can see, the command is identical to the one for "full
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync hard disk" access, except for the additional
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>-partitions</computeroutput> parameter. This example
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync would create the image <code>/path/to/file.vmdk</code> (which, again,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync must be absolute), and partitions 1 and 5 of <code>/dev/sda</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync would be made accessible to the guest.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>VirtualBox uses the same partition numbering as your Linux host.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync As a result, the numbers given in the above example would refer to the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync first primary partition and the first logical drive in the extended
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync partition, respectively.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>On a Windows host, instead of the above device specification,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host, instead
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync of the above device specification use e.g. <code>/dev/disk1</code>.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Note that on OS X you can only use partitions which are not mounted
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync (eject the respective volume first). Partition numbers are the same on
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Linux, Windows and Mac OS X hosts.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The numbers for the list of partitions can be taken from the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync output of<screen>VBoxManage internalcommands listpartitions -rawdisk /dev/sda</screen>The
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync output lists the partition types and sizes to give the user enough
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync information to identify the partitions necessary for the guest.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Images which give access to individual partitions are specific
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to a particular host disk setup. You cannot transfer these images to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync another host; also, whenever the host partitioning changes, the image
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Creating the image requires read/write access for the given
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync device. Read/write access is also later needed when using the image
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync from a virtual machine. If this is not feasible, there is a special
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync variant for raw partition access (currently only available on Linux
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync hosts) that avoids having to give the current user access to the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync entire disk. To set up such an image, use<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync -rawdisk /dev/sda -partitions 1,5 -relative</screen>When used from a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync virtual machine, the image will then refer not to the entire disk, but
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync only to the individual partitions (in the example
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <code>/dev/sda1</code> and <code>/dev/sda5</code>). As a consequence,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync read/write access is only required for the affected partitions, not
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync for the entire disk. During creation however, read-only access to the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync entire disk is required to obtain the partitioning information.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>In some configurations it may be necessary to change the MBR
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync code of the created image, e.g. to replace the Linux boot loader that
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is used on the host by another boot loader. This allows e.g. the guest
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to boot directly to Windows, while the host boots Linux from the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "same" disk. For this purpose the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>-mbr</computeroutput> parameter is provided. It
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync specifies a file name from which to take the MBR code. The partition
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync table is not modified at all, so a MBR file from a system with totally
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync different partitioning can be used. An example of this is<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr</screen>The modified
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync MBR will be stored inside the image, not on the host disk.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>The created image can be attached to a storage controller in a
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync VM configuration as usual.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Configuring the hard disk vendor product data (VPD)</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>VirtualBox reports vendor product data for its virtual hard disks
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync which consist of hard disk serial number, firmware revision and model
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync number. These can be changed using the following commands:</para>
dbabcd810984fc0731edff08eb281f0907dc867avboxsync <screen>VBoxManage setextradata "VM name"
304f31a2a37f5d690086bff2fb4a59228b4dbd40vboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
304f31a2a37f5d690086bff2fb4a59228b4dbd40vboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
304f31a2a37f5d690086bff2fb4a59228b4dbd40vboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The serial number is a 20 byte alphanumeric string, the firmware
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync revision an 8 byte alphanumeric string and the model number a 40 byte
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync alphanumeric string. Instead of "Port0" (referring to the first port),
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync specify the desired SATA hard disk port.</para>
4ae37290cb50a39ea45112540ac89f0b12b172b8vboxsync <para>The above commands apply to virtual machines with an AHCI (SATA)
4ae37290cb50a39ea45112540ac89f0b12b172b8vboxsync controller. The commands for virtual machines with an IDE controller
4ae37290cb50a39ea45112540ac89f0b12b172b8vboxsync are:</para>
4ae37290cb50a39ea45112540ac89f0b12b172b8vboxsync <screen>VBoxManage setextradata "VM name"
4ae37290cb50a39ea45112540ac89f0b12b172b8vboxsync "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial"
4ae37290cb50a39ea45112540ac89f0b12b172b8vboxsyncVBoxManage setextradata "VM name"
4ae37290cb50a39ea45112540ac89f0b12b172b8vboxsync "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware"
4ae37290cb50a39ea45112540ac89f0b12b172b8vboxsyncVBoxManage setextradata "VM name"
4ae37290cb50a39ea45112540ac89f0b12b172b8vboxsync "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model"</screen>
531197d0c66f247938034384b933cc002ed6441evboxsync <para>For hard disks it's also possible to mark the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync drive as having a non-rotational medium with:</para>
4ae37290cb50a39ea45112540ac89f0b12b172b8vboxsync <screen>VBoxManage setextradata "VM name"
4ae37290cb50a39ea45112540ac89f0b12b172b8vboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Additional three parameters are needed for CD/DVD drives to report
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the vendor product data:</para>
dbabcd810984fc0731edff08eb281f0907dc867avboxsync <screen>VBoxManage setextradata "VM name"
304f31a2a37f5d690086bff2fb4a59228b4dbd40vboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
304f31a2a37f5d690086bff2fb4a59228b4dbd40vboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
304f31a2a37f5d690086bff2fb4a59228b4dbd40vboxsync "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIRevision" "revision"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The vendor id is an 8 byte alphanumeric string, the product id an
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 16 byte alphanumeric string and the revision a 4 byte alphanumeric
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync string. Instead of "Port0" (referring to the first port), specify the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync desired SATA hard disk port.</para>
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync <title id="iscsi-intnet">Access iSCSI targets via Internal
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync Networking</title>
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync <para>As an experimental feature, VirtualBox allows for accessing an
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync iSCSI target running in a virtual machine which is configured for using
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync Internal Networking mode. Please see <xref linkend="storage-iscsi" />;
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync linkend="vboxmanage-storageattach" /> for additional information.</para>
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync <para>The IP stack accessing Internal Networking must be configured in
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync the virtual machine which accesses the iSCSI target. A free static IP
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync and a MAC address not used by other virtual machines must be chosen. In
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync the example below, adapt the name of the virtual machine, the MAC
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync address, the IP configuration and the Internal Networking name
c86c393454032ef132726cb301a802f7f799e44dvboxsync ("MyIntNet") according to your needs. The following eigth commands must
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync first be issued:<screen>VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Trusted 1
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsyncVBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsyncVBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsyncVBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsyncVBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsyncVBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet
c86c393454032ef132726cb301a802f7f799e44dvboxsyncVBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/TrunkType 2
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsyncVBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen></para>
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync <para>Finally the iSCSI disk must be attached with the
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync <computeroutput>--intnet</computeroutput> option to tell the iSCSI
e72d867f5d519d040e3e8a7f842e42bdc5120c5bvboxsync initiator to use internal networking:<screen>VBoxManage storageattach ... --medium iscsi
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync --server 10.0.9.30 --target iqn.2008-12.com.sun:sampletarget --intnet</screen></para>
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync <para>Compared to a "regular" iSCSI setup, IP address of the target
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync <emphasis>must</emphasis> be specified as a numeric IP address, as there
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync is no DNS resolver for internal networking.</para>
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync <para>The virtual machine with the iSCSI target should be started before
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync the VM using it is powered on. If a virtual machine using an iSCSI disk
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync is started without having the iSCSI target powered up, it can take up to
cf289c84a0ecd24e5808b46b70d545cdc2c8805cvboxsync 200 seconds to detect this situation. The VM will fail to power
005b3353c3104334065023c2dea73a28f18cd464vboxsync <title>Launching more than 128 VMs on Linux hosts</title>
005b3353c3104334065023c2dea73a28f18cd464vboxsync <para>Linux hosts have a fixed number of IPC semaphores IDs per process
005b3353c3104334065023c2dea73a28f18cd464vboxsync preventing users from starting substantially many VMs. The exact number
005b3353c3104334065023c2dea73a28f18cd464vboxsync may vary with each Linux distribution. While trying to launch more VMs you
005b3353c3104334065023c2dea73a28f18cd464vboxsync would be shown a "Cannot create IPC semaphore" error. In order to run more
005b3353c3104334065023c2dea73a28f18cd464vboxsync VMs, you will need to increase the semaphore ID limit of the VBoxSVC
005b3353c3104334065023c2dea73a28f18cd464vboxsync process. Find the current semaphore limits imposed by the kernel by
005b3353c3104334065023c2dea73a28f18cd464vboxsync <para>The "kernel.sem" parameter bundles together 4 values, the one we are
005b3353c3104334065023c2dea73a28f18cd464vboxsync interested in is called "SEMMNI", the maximum number of semaphore IDs
005b3353c3104334065023c2dea73a28f18cd464vboxsync which is 128 in the above example. Increase this semaphore ID limit by
005b3353c3104334065023c2dea73a28f18cd464vboxsync executing as root:<screen>echo "kernel.sem = 250 32000 32 2048" >> /etc/sysctl.conf
a5082574e0ae7ff5d13ba4d68cc4900a1d376900vboxsync <para>The above commands will add the new limits to the configuration file, thus
005b3353c3104334065023c2dea73a28f18cd464vboxsync making the effect persistent across reboots, and will activate the new
005b3353c3104334065023c2dea73a28f18cd464vboxsync limits into the currently running kernel.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Launching more than 120 VMs on Solaris hosts</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Solaris hosts have a fixed number of IPC semaphores IDs per process
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync preventing users from starting more than 120 VMs. While trying to launch
add6241c8d18850b4720b43dd4c38f990881b400vboxsync more VMs you would be shown a "Cannot create IPC semaphore" error. In
add6241c8d18850b4720b43dd4c38f990881b400vboxsync order to run more VMs, you will need to increase the semaphore ID limit of
add6241c8d18850b4720b43dd4c38f990881b400vboxsync the VBoxSVC process.</para>
add6241c8d18850b4720b43dd4c38f990881b400vboxsync <title>Temporary solution while VirtualBox is running</title>
add6241c8d18850b4720b43dd4c38f990881b400vboxsync <para>Execute as root the <computeroutput>prctl</computeroutput> command
add6241c8d18850b4720b43dd4c38f990881b400vboxsync as shown below for the currently running VBoxSVC process. The process ID
add6241c8d18850b4720b43dd4c38f990881b400vboxsync of VBoxSVC can be obtained using the <computeroutput>ps</computeroutput>
add6241c8d18850b4720b43dd4c38f990881b400vboxsync command.</para>
add6241c8d18850b4720b43dd4c38f990881b400vboxsync <screen>prctl -r -n project.max-sem-ids -v 2048 <pid-of-VBoxSVC></screen>
add6241c8d18850b4720b43dd4c38f990881b400vboxsync <para>This will immediately increase the semaphore limit of the
add6241c8d18850b4720b43dd4c38f990881b400vboxsync currently running VBoxSVC process and allow you to launch more VMs.
add6241c8d18850b4720b43dd4c38f990881b400vboxsync However, this change is not persistent and will be lost when VBoxSVC
add6241c8d18850b4720b43dd4c38f990881b400vboxsync terminates.</para>
add6241c8d18850b4720b43dd4c38f990881b400vboxsync <title>Persistent solution, requires user to re-login</title>
0bc02ad6f4c5b17b200ac5c9cb01fb2e0140c488vboxsync <para>If the user running VirtualBox is root, execute the following
add6241c8d18850b4720b43dd4c38f990881b400vboxsync command:</para>
add6241c8d18850b4720b43dd4c38f990881b400vboxsync <screen>prctl -n project.max-sem-ids -v 2048 -r -i project user.root</screen>
add6241c8d18850b4720b43dd4c38f990881b400vboxsync <para>From this point, starting new processes will have the increased
add6241c8d18850b4720b43dd4c38f990881b400vboxsync limit of 2048. You may then re-login or close all VMs and restart
add6241c8d18850b4720b43dd4c38f990881b400vboxsync VBoxSVC. You can check the current VBoxSVC semaphore ID limit using the
add6241c8d18850b4720b43dd4c38f990881b400vboxsync following command:</para>
add6241c8d18850b4720b43dd4c38f990881b400vboxsync <screen>prctl -n project.max-sem-ids -i process <pid-of-VBoxSVC></screen>
add6241c8d18850b4720b43dd4c38f990881b400vboxsync <para>If the user running VirtualBox is not root, you must add the
add6241c8d18850b4720b43dd4c38f990881b400vboxsync property to the user's default project. Create the default project and
add6241c8d18850b4720b43dd4c38f990881b400vboxsync set the limit by executing as root:</para>
add6241c8d18850b4720b43dd4c38f990881b400vboxsync <screen>projadd -U <username> user.<username>
add6241c8d18850b4720b43dd4c38f990881b400vboxsyncprojmod -s -K "project.max-sem-ids=(priv,2048,deny)" user.<username></screen>
add6241c8d18850b4720b43dd4c38f990881b400vboxsync <para>Substitute "<username>" with the name of the user running
add6241c8d18850b4720b43dd4c38f990881b400vboxsync VirtualBox. Then re-login as this user to be able to run more than 120
add6241c8d18850b4720b43dd4c38f990881b400vboxsync VMs.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Legacy commands for using serial ports</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Starting with version 1.4, VirtualBox provided support for virtual
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync serial ports, which, at the time, was rather complicated to set up with a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync sequence of <computeroutput>VBoxManage setextradata</computeroutput>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync statements. Since version 1.5, that way of setting up serial ports is no
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync longer necessary and <emphasis>deprecated.</emphasis> To set up virtual
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync serial ports, use the methods now described in <xref
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For backwards compatibility, the old
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>setextradata</computeroutput> statements, whose
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync description is retained below from the old version of the manual, take
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <emphasis>precedence</emphasis> over the new way of configuring serial
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync ports. As a result, if configuring serial ports the new way doesn't
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync work, make sure the VM in question does not have old configuration
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync data such as below still active.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The old sequence of configuring a serial port used the following 6
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync commands:</para>
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync <screen>VBoxManage setextradata "VM name"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/serial/0/Config/IOBase" 0x3f8
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Driver" NamedPipe
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
304f31a2a37f5d690086bff2fb4a59228b4dbd40vboxsync "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/Location" "\\.\pipe\vboxCOM1"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
304f31a2a37f5d690086bff2fb4a59228b4dbd40vboxsync "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/IsServer" 1</screen>
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync <para>This sets up a serial port in the guest with the default settings
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync for COM1 (IRQ 4, I/O address 0x3f8) and the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>Location</computeroutput> setting assumes that this
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync configuration is used on a Windows host, because the Windows named pipe
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync syntax is used. Keep in mind that on Windows hosts a named pipe must
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync always start with <computeroutput>\\.\pipe\</computeroutput>. On Linux the
a5082574e0ae7ff5d13ba4d68cc4900a1d376900vboxsync same configuration settings apply, except that the path name for the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>Location</computeroutput> can be chosen more freely. Local
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync domain sockets can be placed anywhere, provided the user running
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox has the permission to create a new file in the directory. The
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync final command above defines that VirtualBox acts as a server, i.e. it
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync creates the named pipe itself instead of connecting to an already existing
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync one.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Fine-tuning the VirtualBox NAT engine</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Configuring the address of a NAT network interface</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>In NAT mode, the guest network interface is assigned to the IPv4
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync range <computeroutput>10.0.x.0/24</computeroutput> by default where
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>x</computeroutput> corresponds to the instance of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync NAT interface +2. So <computeroutput>x</computeroutput> is 2 when there
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is only one NAT instance active. In that case the guest is assigned to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the address <computeroutput>10.0.2.15</computeroutput>, the gateway is
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync set to <computeroutput>10.0.2.2</computeroutput> and the name server can
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync be found at <computeroutput>10.0.2.3</computeroutput>.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>If, for any reason, the NAT network needs to be changed, this can
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync be achieved with the following command:</para>
dbabcd810984fc0731edff08eb281f0907dc867avboxsync <screen>VBoxManage modifyvm "VM name" --natnet1 "192.168/16"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>This command would reserve the network addresses from
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>192.168.254.254</computeroutput> for the first NAT
dbabcd810984fc0731edff08eb281f0907dc867avboxsync network instance of "VM name". The guest IP would be assigned to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>192.168.0.15</computeroutput> and the default gateway
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync could be found at <computeroutput>192.168.0.2</computeroutput>.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Configuring the boot server (next server) of a NAT network
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync interface</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For network booting in NAT mode, by default VirtualBox uses a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync built-in TFTP server at the IP address 10.0.2.3. This default behavior
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync should work fine for typical remote-booting scenarios. However, it is
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync possible to change the boot server IP and the location of the boot image
dbabcd810984fc0731edff08eb281f0907dc867avboxsync with the following commands: <screen>VBoxManage modifyvm "VM name" --nattftpserver1 10.0.2.2
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage modifyvm "VM name" --nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The VirtualBox NAT stack performance is often determined by its
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync interaction with the host's TCP/IP stack and the size of several buffers
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>SO_SNDBUF</computeroutput>). For certain setups users
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync might want to adjust the buffer size for a better performance. This can
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync by achieved using the following commands (values are in kilobytes and
dbabcd810984fc0731edff08eb281f0907dc867avboxsync can range from 8 to 1024): <screen>VBoxManage modifyvm "VM name" --natsettings1 16000,128,128,0,0</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync This example illustrates tuning the NAT settings. The first parameter is
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the MTU, then the size of the socket's send buffer and the size of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync socket's receive buffer, the initial size of the TCP send window, and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync lastly the initial size of the TCP receive window. Note that specifying
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync zero means fallback to the default value.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Each of these buffers has a default size of 64KB and default MTU
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is 1500.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Binding NAT sockets to a specific interface</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>By default, VirtualBox's NAT engine will route TCP/IP packets
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync through the default interface assigned by the host's TCP/IP stack. (The
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync technical reason for this is that the NAT engine uses sockets for
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync communication.) If, for some reason, you want to change this behavior,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync you can tell the NAT engine to bind to a particular IP address instead.
dbabcd810984fc0731edff08eb281f0907dc867avboxsync Use the following command: <screen>VBoxManage modifyvm "VM name" --natbindip1 "10.45.0.2"</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>After this, all outgoing traffic will be sent through the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync interface with the IP address 10.45.0.2. Please make sure that this
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync interface is up and running prior to this assignment.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The NAT engine by default offers the same DNS servers to the guest
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync that are configured on the host. In some scenarios, it can be desirable
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to hide the DNS server IPs from the guest, for example when this
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync information can change on the host due to expiring DHCP leases. In this
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync case, you can tell the NAT engine to act as DNS proxy using the
dbabcd810984fc0731edff08eb281f0907dc867avboxsync following command: <screen>VBoxManage modifyvm "VM name" --natdnsproxy1 on</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Using the host's resolver as a DNS proxy in NAT mode</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For resolving network names, the DHCP server of the NAT engine
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync offers a list of registered DNS servers of the host. If for some reason
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync you need to hide this DNS server list and use the host's resolver
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync settings, thereby forcing the VirtualBox NAT engine to intercept DNS
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync requests and forward them to host's resolver, use the following command:
dbabcd810984fc0731edff08eb281f0907dc867avboxsync <screen>VBoxManage modifyvm "VM name" --natdnshostresolver1 on</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Note that this setting is similar to the DNS proxy mode, however whereas
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the proxy mode just forwards DNS requests to the appropriate servers,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the resolver mode will interpret the DNS requests and use the host's DNS
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync API to query the information and return it to the guest.</para>
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <para>In some cases it might be useful to intercept the name resolving mechanism,
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync providing a user-defined IP address on a particular DNS request. The intercepting
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync mechanism allows the user to map not only a single host but domains and even more
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync complex namings conventions if required.</para>
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync The following command sets a rule for mapping a name to a specified IP:</para>
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <screen>VBoxManage setextradata "VM name" \
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <uniq name of interception rule>/HostIP" <IPv4>
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsyncVBoxManage setextradata "VM name" \
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <uniq name of interception rule>/HostName" <name of host></screen>
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <para>The following command sets a rule for mapping a pattern name to a specified IP:</para>
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <screen>VBoxManage setextradata "VM name" \
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <uniq name of interception rule>/HostIP" <IPv4>
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsyncVBoxManage setextradata "VM name" \
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <uniq name of interception rule>/HostNamePattern" <hostpattern></screen>
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <para>The host pattern may include <computeroutput>"|", "?" and "*"</computeroutput>.</para>
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <para>This example demonstrates how to instruct the host-resolver mechanism to resolve
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync all domain and probably some mirrors of www.blocked-site.info site with IP 127.0.0.1:</para>
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <screen>VBoxManage setextradata "VM name" \
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync "VBoxInternal/Devices/e1000/0/LUN#0/Config/HostResolverMappings/ \
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsyncVBoxManage setextradata "VM name" \
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync "VBoxInternal/Devices/e1000/0/LUN#0/Config/HostResolverMappings/ \
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync all_blocked_site/HostNamePattern" "*.blocked-site.*|*.fb.org"</screen>
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <note><para>The host resolver mechanism should be enabled to use user-defined
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync mapping rules (please see
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <xref linkend="nat_host_resolver_proxy" /> for more details).</para></note>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Configuring aliasing of the NAT engine</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>By default, the NAT core uses aliasing and uses random ports when
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync generating an alias for a connection. This works well for the most
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync protocols like SSH, FTP and so on. Though some protocols might need a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync more transparent behavior or may depend on the real port number the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync packet was sent from. It is possible to change the NAT mode via the
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync VBoxManage frontend with the following commands: <screen>VBoxManage modifyvm "VM name" --nataliasmode1 proxyonly</screen>
ae8425b895d2e881de7f542f8d20bea13f205f51vboxsync and <screen>VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync The first example disables aliasing and switches NAT into transparent
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync mode, the second example enforces preserving of port values. These modes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync can be combined if necessary.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Configuring the BIOS DMI information</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The DMI data VirtualBox provides to guests can be changed for a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync specific VM. Use the following commands to configure the DMI BIOS
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync information:</para>
1fcabda547f526deb351f39b455062dc165387d9vboxsync <screen>VBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor" "BIOS Vendor"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion" "BIOS Version"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate" "BIOS Release Date"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor" 1
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor" 2
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4</screen>
1fcabda547f526deb351f39b455062dc165387d9vboxsync <screen>VBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor" "System Vendor"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct" "System Product"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion" "System Version"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "System Serial"
434521f20688750b48498b6cabbc7d109d053942vboxsyncVBoxManage setextradata "VM name"
434521f20688750b48498b6cabbc7d109d053942vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU" "System SKU"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily" "System Family"
dbabcd810984fc0731edff08eb281f0907dc867avboxsyncVBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "9852bf98-b83c-49db-a8de-182c42c7226b"</screen>
1fcabda547f526deb351f39b455062dc165387d9vboxsync <screen>VBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVendor" "Board Vendor"
1fcabda547f526deb351f39b455062dc165387d9vboxsyncVBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBoardProduct" "Board Product"
1fcabda547f526deb351f39b455062dc165387d9vboxsyncVBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVersion" "Board Version"
1fcabda547f526deb351f39b455062dc165387d9vboxsyncVBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBoardSerial" "Board Serial"
1fcabda547f526deb351f39b455062dc165387d9vboxsyncVBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBoardAssetTag" "Board Tag"
1fcabda547f526deb351f39b455062dc165387d9vboxsyncVBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBoardLocInChass" "Board Location"
1fcabda547f526deb351f39b455062dc165387d9vboxsyncVBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiBoardType" 10</screen>
1fcabda547f526deb351f39b455062dc165387d9vboxsync <title>DMI system enclosure or chassis (type 3)</title>
1fcabda547f526deb351f39b455062dc165387d9vboxsync <screen>VBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVendor" "Chassis Vendor"
1fcabda547f526deb351f39b455062dc165387d9vboxsyncVBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVersion" "Chassis Version"
1fcabda547f526deb351f39b455062dc165387d9vboxsyncVBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiChassisSerial" "Chassis Serial"
1fcabda547f526deb351f39b455062dc165387d9vboxsyncVBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiChassisAssetTag" "Chassis Tag"</screen>
1fcabda547f526deb351f39b455062dc165387d9vboxsync <screen>VBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiProcManufacturer" "GenuineIntel"
1fcabda547f526deb351f39b455062dc165387d9vboxsyncVBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiProcVersion" "Pentium(R) III"</screen>
1fcabda547f526deb351f39b455062dc165387d9vboxsync <screen>VBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxVer" "vboxVer_1.2.3"
1fcabda547f526deb351f39b455062dc165387d9vboxsyncVBoxManage setextradata "VM name"
1fcabda547f526deb351f39b455062dc165387d9vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxRev" "vboxRev_12345"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>If a DMI string is not set, the default value of VirtualBox is used.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync To set an empty string use
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>"<EMPTY>"</computeroutput>.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Note that in the above list, all quoted parameters (DmiBIOSVendor,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync DmiBIOSVersion but not DmiBIOSReleaseMajor) are expected to be strings. If
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync such a string is a valid number, the parameter is treated as number and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the VM will most probably refuse to start with an
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VERR_CFGM_NOT_STRING</computeroutput> error. In that case,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync use <computeroutput>"string:<value>"</computeroutput>, for instance
dbabcd810984fc0731edff08eb281f0907dc867avboxsync <screen>VBoxManage setextradata "VM name"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "string:1234"</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Changing this information can be necessary to provide the DMI
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync information of the host to the guest to prevent Windows from asking for a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync new product key. On Linux hosts the DMI BIOS information can be obtained
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with <screen>dmidecode -t0</screen>and the DMI system information can be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync obtained with <screen>dmidecode -t1</screen></para>
2eb85afb963be602d58f63aa6d70884fb5bf6717vboxsync <para>VirtualBox can be configured to present an custom ACPI table to
2eb85afb963be602d58f63aa6d70884fb5bf6717vboxsync the guest. Use the following command to configure this:</para>
2eb85afb963be602d58f63aa6d70884fb5bf6717vboxsync <screen>VBoxManage setextradata "VM name"
2eb85afb963be602d58f63aa6d70884fb5bf6717vboxsync "VBoxInternal/Devices/acpi/0/Config/CustomTable" "/path/to/table.bin"</screen>
2eb85afb963be602d58f63aa6d70884fb5bf6717vboxsync <para>Configuring a custom ACPI table can prevent Windows
2eb85afb963be602d58f63aa6d70884fb5bf6717vboxsync Vista and Windows 7 from asking for a new product key. On Linux hosts,
2eb85afb963be602d58f63aa6d70884fb5bf6717vboxsync one of the host tables can be read from
2eb85afb963be602d58f63aa6d70884fb5bf6717vboxsync <filename>/sys/firmware/acpi/tables/</filename>.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Fine-tuning timers and time synchronization</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Configuring the guest time stamp counter (TSC) to reflect guest
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync execution</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>By default, VirtualBox keeps all sources of time visible to the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync guest synchronized to a single time source, the monotonic host time.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync This reflects the assumptions of many guest operating systems, which
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync expect all time sources to reflect "wall clock" time. In special
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync circumstances it may be useful however to make the TSC (time stamp
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync counter) in the guest reflect the time actually spent executing the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync guest.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>This special TSC handling mode can be enabled on a per-VM basis,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync and for best results must be used only in combination with hardware
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync virtualization. To enable this mode use the following command:</para>
dbabcd810984fc0731edff08eb281f0907dc867avboxsync <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution" 1</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To revert to the default TSC handling mode use:</para>
dbabcd810984fc0731edff08eb281f0907dc867avboxsync <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Note that if you use the special TSC handling mode with a guest
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync operating system which is very strict about the consistency of time
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync sources you may get a warning or error message about the timing
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync inconsistency. It may also cause clocks to become unreliable with some
6785d00904fafda14b1501bac0d15cadfb3a52f7vboxsync guest operating systems depending on how they use the TSC.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Accelerate or slow down the guest clock</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For certain purposes it can be useful to accelerate or to slow
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync down the (virtual) guest clock. This can be achieved as follows:</para>
dbabcd810984fc0731edff08eb281f0907dc867avboxsync <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 200</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The above example will double the speed of the guest clock
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync while</para>
dbabcd810984fc0731edff08eb281f0907dc867avboxsync <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 50</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>will halve the speed of the guest clock. Note that changing the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync rate of the virtual clock can confuse the guest and can even lead to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync abnormal guest behavior. For instance, a higher clock rate means shorter
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync timeouts for virtual devices with the result that a slightly increased
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync response time of a virtual device due to an increased host load can
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync cause guest failures. Note further that any time synchronization
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync mechanism will frequently try to resynchronize the guest clock with the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync reference clock (which is the host clock if the VirtualBox Guest
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Additions are active). Therefore any time synchronization should be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync disabled if the rate of the guest clock is changed as described above
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Tuning the Guest Additions time synchronization
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync parameters</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The VirtualBox Guest Additions ensure that the guest's system time
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is synchronized with the host time. There are several parameters which
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync can be tuned. The parameters can be set for a specific VM using the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync following command:</para>
c9523ad08e2f9ea1e29d94dc7e7ff83a99f6e232vboxsync <screen>VBoxManage guestproperty set "VM name" "/VirtualBox/GuestAdd/VBoxService/PARAMETER" VALUE</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>where <computeroutput>PARAMETER</computeroutput> is one of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync following:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <glossentry>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <glossterm><computeroutput>--timesync-interval</computeroutput></glossterm>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Specifies the interval at which to synchronize the time
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with the host. The default is 10000 ms (10 seconds).</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </glossdef>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </glossentry>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <glossentry>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <glossterm><computeroutput>--timesync-min-adjust</computeroutput></glossterm>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The minimum absolute drift value measured in milliseconds
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to make adjustments for. The default is 1000 ms on OS/2 and 100
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync ms elsewhere.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </glossdef>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </glossentry>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <glossentry>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <glossterm><computeroutput>--timesync-latency-factor</computeroutput></glossterm>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The factor to multiply the time query latency with to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync calculate the dynamic minimum adjust time. The default is 8
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync times, that means in detail: Measure the time it takes to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync determine the host time (the guest has to contact the VM host
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync service which may take some time), multiply this value by 8 and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync do an adjustment only if the time difference between host and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync guest is bigger than this value. Don't do any time adjustment
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync otherwise.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </glossdef>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </glossentry>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <glossentry>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <glossterm><computeroutput>--timesync-max-latency</computeroutput></glossterm>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The max host timer query latency to accept. The default is
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 250 ms.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </glossdef>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </glossentry>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <glossentry>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <glossterm><computeroutput>--timesync-set-threshold</computeroutput></glossterm>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The absolute drift threshold, given as milliseconds where
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to start setting the time instead of trying to smoothly adjust
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync it. The default is 20 minutes.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </glossdef>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </glossentry>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <glossentry>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <glossterm><computeroutput>--timesync-set-start</computeroutput></glossterm>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Set the time when starting the time sync service.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </glossdef>
82ec021964a07a8f01bb7d741ce1d8150171bc8avboxsync </glossentry>
82ec021964a07a8f01bb7d741ce1d8150171bc8avboxsync <glossentry>
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync <glossterm><computeroutput>--timesync-set-on-restore
82ec021964a07a8f01bb7d741ce1d8150171bc8avboxsync <para>Set the time after the VM was restored from a saved state
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync when passing 1 as parameter (default). Disable by passing 0. In
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync the latter case, the time will be adjusted smoothly which can
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync take a long time.</para>
82ec021964a07a8f01bb7d741ce1d8150171bc8avboxsync </glossdef>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </glossentry>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>All these parameters can be specified as command line parameters
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to VBoxService as well.</para>
ae1ed5f418cc952541dc91da2e61b557535c61bfvboxsync <title>Disabling the Guest Additions time synchronization</title>
ae1ed5f418cc952541dc91da2e61b557535c61bfvboxsync <para>Once installed and started, the VirtualBox Guest Additions will
ae1ed5f418cc952541dc91da2e61b557535c61bfvboxsync try to synchronize the guest time with the host time. This can be
d513b77a25a975921896e8ff2b719757603197fcvboxsync prevented by forbidding the guest service from reading the host
ae1ed5f418cc952541dc91da2e61b557535c61bfvboxsync clock:</para>
ae1ed5f418cc952541dc91da2e61b557535c61bfvboxsync <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</screen>
386db787081ab13628e0123bd65eb2f272f073a5vboxsync <title>Installing the alternate bridged networking driver on Solaris 11
d59c16b6a080bcdce09dfd882341c1b2ed96a393vboxsync hosts</title>
d59c16b6a080bcdce09dfd882341c1b2ed96a393vboxsync <para>Starting with VirtualBox 4.1, VirtualBox ships a new network filter
d59c16b6a080bcdce09dfd882341c1b2ed96a393vboxsync driver that utilizes Solaris 11's Crossbow functionality. By default, this
386db787081ab13628e0123bd65eb2f272f073a5vboxsync new driver is installed for Solaris 11 hosts (builds 159 and above) that
386db787081ab13628e0123bd65eb2f272f073a5vboxsync has support for it.</para>
386db787081ab13628e0123bd65eb2f272f073a5vboxsync <para>To force installation of the older STREAMS based network filter
b666a60a65a283baf4a2ae07a3fceede2c70e25dvboxsync driver, execute as root the following command before installing the
386db787081ab13628e0123bd65eb2f272f073a5vboxsync VirtualBox package:</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>To force installation of the Crossbow based network filter driver,
b666a60a65a283baf4a2ae07a3fceede2c70e25dvboxsync execute as root the following command before installing the VirtualBox
386db787081ab13628e0123bd65eb2f272f073a5vboxsync package:</para>
386db787081ab13628e0123bd65eb2f272f073a5vboxsync <para>To check which driver is currently being used by VirtualBox,
386db787081ab13628e0123bd65eb2f272f073a5vboxsync execute:</para>
386db787081ab13628e0123bd65eb2f272f073a5vboxsync <para>If the output contains "vboxbow", it indicates VirtualBox is using
649076983a27a61a0f8289d4631975051f4b829evboxsync the Crossbow network filter driver, while the name "vboxflt" indicates
649076983a27a61a0f8289d4631975051f4b829evboxsync usage of the older STREAMS network filter.</para>
386db787081ab13628e0123bd65eb2f272f073a5vboxsync <title>VirtualBox VNIC templates for VLANs on Solaris 11 hosts</title>
386db787081ab13628e0123bd65eb2f272f073a5vboxsync <para>VirtualBox supports VNIC (Virtual Network Interface) templates for
649076983a27a61a0f8289d4631975051f4b829evboxsync configuring VMs over VLANs.<footnote>
386db787081ab13628e0123bd65eb2f272f073a5vboxsync <para>Support for Crossbow based bridged networking was introduced
386db787081ab13628e0123bd65eb2f272f073a5vboxsync with VirtualBox 4.1 and requires Solaris 11 build 159 or above.</para>
386db787081ab13628e0123bd65eb2f272f073a5vboxsync </footnote> A VirtualBox VNIC template is a VNIC whose name starts with
386db787081ab13628e0123bd65eb2f272f073a5vboxsync "vboxvnic_template".</para>
386db787081ab13628e0123bd65eb2f272f073a5vboxsync <para>Here is an example of how to use a VNIC template to configure a VLAN
386db787081ab13628e0123bd65eb2f272f073a5vboxsync for VMs. Create a VirtualBox VNIC template, by executing as root:</para>
386db787081ab13628e0123bd65eb2f272f073a5vboxsync <screen>dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0
386db787081ab13628e0123bd65eb2f272f073a5vboxsync <para>This will create a temporary VNIC over interface "nge0" with the
386db787081ab13628e0123bd65eb2f272f073a5vboxsync VLAN ID 23. To create VNIC templates that are persistent across host
386db787081ab13628e0123bd65eb2f272f073a5vboxsync reboots, skip the <computeroutput>-t</computeroutput> parameter in the
386db787081ab13628e0123bd65eb2f272f073a5vboxsync above command. You may check the current state of links using:</para>
386db787081ab13628e0123bd65eb2f272f073a5vboxsyncLINK CLASS MTU STATE BRIDGE OVER
386db787081ab13628e0123bd65eb2f272f073a5vboxsyncnge0 phys 1500 up -- --
386db787081ab13628e0123bd65eb2f272f073a5vboxsyncnge1 phys 1500 down -- --
386db787081ab13628e0123bd65eb2f272f073a5vboxsyncvboxvnic_template0 vnic 1500 up -- nge0
386db787081ab13628e0123bd65eb2f272f073a5vboxsync$ dladm show-vnic
386db787081ab13628e0123bd65eb2f272f073a5vboxsyncLINK OVER SPEED MACADDRESS MACADDRTYPE VID
386db787081ab13628e0123bd65eb2f272f073a5vboxsyncvboxvnic_template0 nge0 1000 2:8:20:25:12:75 random 23
386db787081ab13628e0123bd65eb2f272f073a5vboxsync <para>Once the VNIC template is created, all VMs that need to be part of
386db787081ab13628e0123bd65eb2f272f073a5vboxsync VLAN 23 over the physical interface "nge0" can use the same VNIC template.
386db787081ab13628e0123bd65eb2f272f073a5vboxsync This makes managing VMs on VLANs simpler and efficient, as the VLAN
386db787081ab13628e0123bd65eb2f272f073a5vboxsync details are not stored as part of every VM's configuration but rather
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync picked from the VNIC template which can be modified anytime using
386db787081ab13628e0123bd65eb2f272f073a5vboxsync <computeroutput>dladm</computeroutput>. Apart from the VLAN ID, VNIC
386db787081ab13628e0123bd65eb2f272f073a5vboxsync templates can be created with additional properties such as bandwidth
386db787081ab13628e0123bd65eb2f272f073a5vboxsync limits, CPU fanout etc. Refer to your Solaris network documentation on how
386db787081ab13628e0123bd65eb2f272f073a5vboxsync to accomplish this. These additional properties, if any, are also applied
386db787081ab13628e0123bd65eb2f272f073a5vboxsync to VMs which use the VNIC template.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Configuring multiple host-only network interfaces on Solaris
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync hosts</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>By default VirtualBox provides you with one host-only network
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync interface. Adding more host-only network interfaces on Solaris hosts
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync requires manual configuration. Here's how to add two more host-only
f18058e02cae9f7c273861c00bfb3793659ffafevboxsync network interfaces.</para>
f18058e02cae9f7c273861c00bfb3793659ffafevboxsync <para>You first need to stop all running VMs and unplumb all existing
f18058e02cae9f7c273861c00bfb3793659ffafevboxsync "vboxnet" interfaces. Execute the following commands as root:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Once you make sure all vboxnet interfaces are unplumbed, remove the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync driver using:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para><screen>rem_drv vboxnet</screen>then edit the file
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>/platform/i86pc/kernel/drv/vboxnet.conf</computeroutput>
f18058e02cae9f7c273861c00bfb3793659ffafevboxsync and add a line for the new interfaces:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para><screen>name="vboxnet" parent="pseudo" instance=1;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncname="vboxnet" parent="pseudo" instance=2;</screen>Add as many of these lines
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync as required and make sure "instance" number is uniquely incremented. Next
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync reload the vboxnet driver using:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para><screen>add_drv vboxnet</screen>Now plumb all the interfaces using
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>ifconfig vboxnetX plumb</computeroutput> (where X can be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 0, 1 or 2 in this case) and once plumbed you can then configure the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync interface like any other network interface.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To make your newly added interfaces' settings persistent across
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync reboots you will need to edit the files
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>/etc/netmasks</computeroutput>, and if you are using NWAM
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>/etc/nwam/llp</computeroutput> and add the appropriate
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync entries to set the netmask and static IP for each of those interfaces. The
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox installer only updates these configuration files for the one
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "vboxnet0" interface it creates by default.</para>
5a4c0239fb40e75ff03c2842bfc549705ea55335vboxsync <title>Configuring the VirtualBox CoreDumper on Solaris hosts</title>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync <para>VirtualBox is capable of producing its own core files for extensive
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync debugging when things go wrong. Currently this is only available on
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync Solaris hosts.</para>
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync <para>The VirtualBox CoreDumper can be enabled using the following
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync command:</para>
fbac0da11344b078c8df6e338e0493dccc279198vboxsync <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpEnabled 1</screen></para>
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync <para>You can specify which directory to use for core dumps with this
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync command:</para>
fbac0da11344b078c8df6e338e0493dccc279198vboxsync <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir <path-to-directory></screen>Make
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync sure the directory you specify is on a volume with sufficient free space
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync and that the VirtualBox process has sufficient permissions to write files
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync to this directory. If you skip this command and don't specify any core
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync dump directory, the current directory of the VirtualBox executable will be
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync used (which would most likely fail when writing cores as they are
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync protected with root permissions). It is recommended you explicitly set a
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync core dump directory.</para>
a2e827cf7080bb70bfa39f5fdf85b04145b53204vboxsync <para>You must specify when the VirtualBox CoreDumper should be triggered.
a2e827cf7080bb70bfa39f5fdf85b04145b53204vboxsync This is done using the following commands:</para>
fbac0da11344b078c8df6e338e0493dccc279198vboxsync <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpReplaceSystemDump 1
fbac0da11344b078c8df6e338e0493dccc279198vboxsyncVBoxManage setextradata "VM name" VBoxInternal2/CoreDumpLive 1</screen>At
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync least one of the above two commands will have to be provided if you have
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync enabled the VirtualBox CoreDumper.</para>
fbac0da11344b078c8df6e338e0493dccc279198vboxsync <para>Setting <computeroutput>CoreDumpReplaceSystemDump</computeroutput>
a2e827cf7080bb70bfa39f5fdf85b04145b53204vboxsync sets up the VM to override the host's core dumping mechanism and in the
a2e827cf7080bb70bfa39f5fdf85b04145b53204vboxsync event of any crash only the VirtualBox CoreDumper would produce the core
a2e827cf7080bb70bfa39f5fdf85b04145b53204vboxsync file.</para>
fbac0da11344b078c8df6e338e0493dccc279198vboxsync <para>Setting <computeroutput>CoreDumpLive</computeroutput> sets up the VM
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync to produce cores whenever the VM process receives a
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync <computeroutput>SIGUSR2</computeroutput> signal. After producing the core
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync file, the VM will not be terminated and will continue to run. You can thus
a2e827cf7080bb70bfa39f5fdf85b04145b53204vboxsync take cores of the VM process using:</para>
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync <para><screen>kill -s SIGUSR2 <VM-process-id></screen></para>
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync <para>Core files produced by the VirtualBox CoreDumper are of the form
9864317785d3ad19e5f4fd6d328858d71c9d474cvboxsync <computeroutput>core.vb.<ProcessName>.<ProcessID></computeroutput>,
188f53eda6c7dd6221a2b9c9f3341bac724b107evboxsync for example <computeroutput>core.vb.VBoxHeadless.11321</computeroutput>.</para>
5a4c0239fb40e75ff03c2842bfc549705ea55335vboxsync <title>Locking down the VirtualBox manager GUI</title>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>There are several advanced customization settings for locking down
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync the VirtualBox manager, that is, removing some features that the user
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync should not see.</para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para><screen>VBoxManage setextradata global GUI/Customizations OPTION[,OPTION...]</screen></para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>where <computeroutput>OPTION</computeroutput> is one of the
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync following keywords:<glosslist>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossterm><computeroutput>noSelector</computeroutput></glossterm>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>Don't allow to start the VirtualBox manager. Trying to do so
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync will show a window containing a proper error message.</para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossdef>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossterm><computeroutput>noMenuBar</computeroutput></glossterm>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>VM windows will not contain a menu bar.</para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossdef>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossterm><computeroutput>noStatusBar</computeroutput></glossterm>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>VM windows will not contain a status bar.</para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossdef>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>To disable any GUI customization do <screen>VBoxManage setextradata global GUI/Customizations</screen></para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>To disable all host key combinations, open the preferences and
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync change the host key to <emphasis>None</emphasis>. This might be useful
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync when using VirtualBox in a kiosk mode.</para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>To redefine or disable certain host key actions, use the following command:</para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...."</screen>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>The following list shows the possible host key actions together with their default
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync host key shortcut. Setting an action to <emphasis>None</emphasis> will disable
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync that host key action.</para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <entry><emphasis role="bold">Action</emphasis></entry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <entry><emphasis role="bold">Default Host Key</emphasis></entry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <entry><emphasis role="bold">Action</emphasis></entry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <entry>show popup menu in fullscreen / seamless mode</entry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>To disable the fullscreen mode as well as the seamless mode, use the following command:
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</screen>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>You can disallow certain actions when terminating a VM. To disallow specific actions, type:</para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para><screen>VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...]</screen></para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>where <computeroutput>OPTION</computeroutput> is one of the
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync following keywords:<glosslist>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossterm><computeroutput>SaveState</computeroutput></glossterm>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>Don't allow the user to save the VM state when terminating
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync the VM.</para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossdef>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossterm><computeroutput>Shutdown</computeroutput></glossterm>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>Don't allow the user to shutdown the VM by sending the ACPI
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync power-off event to the guest.</para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossdef>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>Don't allow the user to power off the VM.</para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossdef>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <glossterm><computeroutput>Restore</computeroutput></glossterm>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>Don't allow the user to return to the last snapshot when
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync powering off the VM.</para>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossdef>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync </glossentry>
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync <para>Any combination of the above is allowed. If all options are
34e20f45494bfef87a3a03451616f013ecec80fbvboxsync specified, the VM cannot be shut down at all.</para>
5a4c0239fb40e75ff03c2842bfc549705ea55335vboxsync <title>Starting the VirtualBox web service automatically</title>
5a4c0239fb40e75ff03c2842bfc549705ea55335vboxsync <para>The VirtualBox web service
5a4c0239fb40e75ff03c2842bfc549705ea55335vboxsync (<computeroutput>vboxwebsrv</computeroutput>) is used for controlling
5a4c0239fb40e75ff03c2842bfc549705ea55335vboxsync VirtualBox remotely. It is documented in detail in the VirtualBox Software
5a4c0239fb40e75ff03c2842bfc549705ea55335vboxsync Development Kit (SDK); please see <xref linkend="VirtualBoxAPI" />. As the
5a4c0239fb40e75ff03c2842bfc549705ea55335vboxsync client base using this interface is growing, we added start scripts for
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync the various operation systems we support. The following sections describe
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync how to use them. The VirtualBox web service is never started automatically
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync as a result of a standard installation.</para>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <title>Linux: starting the webservice via <computeroutput>init</computeroutput></title>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <para>On Linux, the web service can be automatically started during
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync host boot by adding appropriate parameters to the file
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <computeroutput>/etc/default/virtualbox</computeroutput>.
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync There is one mandatory parameter, <computeroutput>VBOXWEB_USER</computeroutput>,
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync which must be set to the user which will later start the VMs. The
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync parameters in the table below all start with <computeroutput>VBOXWEB_</computeroutput>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <computeroutput>VBOXWEB_PORT</computeroutput> etc.):
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry><emphasis role="bold">Parameter</emphasis></entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry><emphasis role="bold">Description</emphasis></entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry><emphasis role="bold">Default</emphasis></entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry>The user as which the web service runs</entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry>Server key and certificate file, PEM format</entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry>File name for password to server key</entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry>DH file name or DH key length in bits</entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry>File containing seed for random number generator</entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry>Session timeout in seconds; 0 disables timeouts</entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry>Frequency of timeout checks in seconds</entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry>Maximum number of worker threads to run in parallel</entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry>Maximum number of requests before a socket will be closed</entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry>Number of log files; 0 disables log rotation</entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry>Maximum size of a log file in bytes to trigger rotation</entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <entry>Maximum time interval in seconds to trigger log rotation</entry>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <para>Setting the parameter <computeroutput>SSL_KEYFILE</computeroutput>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync enables the SSL/TLS support. Using encryption is strongly encouraged, as
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync otherwise everything (including passwords) is transferred in clear
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync text.</para>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <title>Solaris: starting the web service via SMF</title>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <para>On Solaris hosts, the VirtualBox web service daemon is
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync integrated into the SMF framework. You can change the parameters, but
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync don't have to if the defaults below already match your needs:<screen>svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsyncsvccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsyncsvccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root</screen></para>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <para>The table in the previous section showing the parameter names and
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync defaults also applies to Solaris. The parameter names must be changed
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync to lowercase and a prefix of <computeroutput>config/</computeroutput>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync has to be added, e.g. <computeroutput>config/user</computeroutput> or
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <computeroutput>config/ssl_keyfile</computeroutput>. If you made any
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync change, don't forget to run the following command to put the changes into
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync effect immediately:<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen></para>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <para>If you forget the above command then the previous settings will
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync be used when enabling the service. Check the current property settings
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync with:<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen></para>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <para>When everything is configured correctly you can start the
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync VirtualBox web service with the following command:<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen></para>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <para>For more information about SMF, please refer to the Solaris
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync documentation.</para>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <title>Mac OS X: starting the webservice via launchd</title>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <para>On Mac OS X, launchd is used to start the VirtualBox webservice. An
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync example configuration file can be found in
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>.
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync It can be enabled by changing the
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync <computeroutput>false</computeroutput>. To manually start the
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync service use the following command: <screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync For additional information on how launchd services could be
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync 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>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para>Starting with VirtualBox 4.2 the memory ballooning service formerly
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync known as <computeroutput>VBoxBalloonCtrl</computeroutput> was renamed to
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync VBoxWatchdog, which now incorporates several host services that are meant
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync to be run in a server environment.</para>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <para>Memory ballooning control, which automatically takes care of
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync a VM's configured memory balloon (see <xref linkend="guestadd-balloon" />
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync for an introduction to memory ballooning). This especially is useful
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync for server environments where VMs may dynamically require more or
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync less memory during runtime.</para>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para>The service periodically checks a VM's current memory balloon
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync and its free guest RAM and automatically adjusts the current memory
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync balloon by inflating or deflating it accordingly. This handling only
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync applies to running VMs having recent Guest Additions installed.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync </listitem>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para>Host isolation detection, which provides a way to detect whether
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync the host cannot reach the specific VirtualBox server instance anymore
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync and take appropriate actions, such as shutting down, saving the
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync current state or even powering down certain VMs.</para>
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync </listitem>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync All configuration values can be either specified via command line or global
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync extradata, whereas command line values always have a higher priority when set.
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync Some of the configuration values also be be specified on a per-VM basis. So
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync the overall lookup order is: command line, per-VM basis extradata (if available),
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync global extradata.
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para>The memory ballooning control inflates and deflates the memory balloon
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync of VMs based on the VMs free memory and the desired maximum balloon size.</para>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para>To set up the memory ballooning control the maximum ballooning size a
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync VM can reach needs to be set. This can be specified via command line with
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <screen>--balloon-max <Size in MB></screen>, on a per-VM basis extradata value with
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <screen>VBoxManage setextradata <VM-Name> VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></screen>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync or using a global extradata value with
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></screen>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <note><para>If no maximum ballooning size is specified by at least one of
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync the parameters above, no ballooning will be performed at all.</para></note>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <para>Setting the ballooning increment in MB can be either done via
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync command line with
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <screen>--balloon-inc <Size in MB></screen> or using a global
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync extradata value with
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB <Size in MB></screen>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync Default ballooning increment is 256 MB if not specified.</para>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para>Same goes with the ballooning decrement: Via command line with
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <screen>--balloon-dec <Size in MB></screen> or using a global
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync extradata value with
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB <Size in MB></screen>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync Default ballooning decrement is 128 MB if not specified.</para>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para>To define the lower limit in MB a balloon can be the command line with
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <screen>--balloon-lower-limit <Size in MB></screen> can be used or using a global
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync extradata value with
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB <Size in MB></screen>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync is available. Default lower limit is 128 if not specified.</para>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para>To detect whether a host is being isolated, that is, the host cannot
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync reach the VirtualBox server instance anymore, the host needs to set an
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync alternating value to a global extradata value within a time period. If
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync this value is not set within that time period a timeout occurred and the
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync so-called host isolation response will be performed to the VMs handled.
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync Which VMs are handled can be controlled by defining VM groups and assigning
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync VMs to those groups. By default no groups are set, meaning that all VMs
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync on the server will be handled when no host response is received within
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync 30 seconds.</para>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para>To set the groups handled by the host isolation detection via
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync command line:
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <screen>--apimon-groups=<string[,stringN]></screen> or using a global
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync extradata value with
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups <string[,stringN]></screen>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para>To set the host isolation timeout via command line:
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <screen>--apimon-isln-timeout=<ms></screen> or using a global
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync extradata value with
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS <ms></screen>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para>To set the actual host isolation response via command line:
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <screen>--apimon-isln-response=<cmd></screen> or using a global
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync extradata value with
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse <cmd></screen>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync The following response commands are available:
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <itemizedlist>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para><computeroutput>none</computeroutput>, which does nothing.</para>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync </listitem>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para><computeroutput>pause</computeroutput>, which pauses the
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync execution of a VM.</para>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync </listitem>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para><computeroutput>poweroff</computeroutput>, which shuts down
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync the VM by pressing the virtual power button. The VM will not have
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync the chance of saving any data or veto the shutdown process.</para>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync </listitem>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para><computeroutput>save</computeroutput>, which saves the current
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync machine state and powers off the VM afterwards. If saving the machine
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync state fails the VM will be paused.</para>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync </listitem>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync <para><computeroutput>shutdown</computeroutput>, which shuts down
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync the VM in a gentle way by sending an <computeroutput>ACPI</computeroutput>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync shutdown event to the VM's operating system. The OS then has the
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync chance of doing a clean shutdown.</para>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync </listitem>
d8b24a89ae3359610c2a7811858c7e39e15dee13vboxsync </itemizedlist>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <para>For more advanced options and parameters like verbose logging check
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync the built-in command line help accessible with
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <title>Linux: starting the watchdog service via <computeroutput>init</computeroutput></title>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <para>On Linux, the watchdog service can be automatically started during
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync host boot by adding appropriate parameters to the file
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <computeroutput>/etc/default/virtualbox</computeroutput>.
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync There is one mandatory parameter, <computeroutput>VBOXWATCHDOG_USER</computeroutput>,
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync which must be set to the user which will later start the VMs. For backward
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync compatibility you can also specify <computeroutput>VBOXBALLOONCTRL_USER</computeroutput>The
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync parameters in the table below all start with <computeroutput>VBOXWATCHDOG_</computeroutput>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync (<computeroutput>VBOXWATCHDOG_BALLOON_INTERVAL</computeroutput>,
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <computeroutput>VBOXWATCHDOG_LOGSIZE</computeroutput> etc., and for
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync previously existing parameters the
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <computeroutput>VBOXBALLOONCTRL_INTERVAL</computeroutput> etc. parameters
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync can still be used):
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <entry><emphasis role="bold">Parameter</emphasis></entry>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <entry><emphasis role="bold">Description</emphasis></entry>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <entry><emphasis role="bold">Default</emphasis></entry>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <entry>The user as which the watchdog service runs</entry>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <entry>Number of log files; 0 disables log rotation</entry>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <entry>Maximum size of a log file in bytes to trigger rotation</entry>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <entry>Maximum time interval in seconds to trigger log rotation</entry>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <entry>Interval for checking the balloon size (msec)</entry>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <entry>Free memory required for decreasing the balloon size (MByte)</entry>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <title>Solaris: starting the watchdog service via SMF</title>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <para>On Solaris hosts, the VirtualBox watchdog service daemon is
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync integrated into the SMF framework. You can change the parameters, but
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync don't have to if the defaults already match your needs:<screen>svccfg -s svc:/application/virtualbox/balloonctrl:default setprop config/balloon_interval=10000
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsyncsvccfg -s svc:/application/virtualbox/balloonctrl:default setprop config/balloon_safetymargin=134217728</screen></para>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <para>The table in the previous section showing the parameter names and
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync defaults also applies to Solaris. The parameter names must be changed
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync to lowercase and a prefix of <computeroutput>config/</computeroutput>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync has to be added, e.g. <computeroutput>config/user</computeroutput> or
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <computeroutput>config/balloon_safetymargin</computeroutput>. If you made any
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync change, don't forget to run the following command to put the changes into
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync effect immediately:<screen>svcadm refresh svc:/application/virtualbox/balloonctrl:default</screen></para>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <para>If you forget the above command then the previous settings will
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync be used when enabling the service. Check the current property settings
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync with:<screen>svcprop -p config svc:/application/virtualbox/balloonctrl:default</screen></para>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <para>When everything is configured correctly you can start the
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync VirtualBox watchdog service with the following command:<screen>svcadm enable svc:/application/virtualbox/balloonctrl:default</screen></para>
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync <para>For more information about SMF, please refer to the Solaris
8a0e16a59a2c5ffeeac323e1842e65a4ddf3c5c1vboxsync documentation.</para>
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync <para>Starting with VirtualBox 4.2.0 there is another extension pack,
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync <code>VNC</code>, which is open source and replaces the previous
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync integration of the VNC remote access protocol. This is experimental code,
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync and will be initially available in the VirtualBox source code package only.
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync It is to a large portion code contributed by users, and is not supported
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync in any way by Oracle.</para>
e5744f6df1c6a56f461e975f261f3ccb3c0ef886vboxsync <para>The keyboard handling is severely limited, and only the US keyboard
e5744f6df1c6a56f461e975f261f3ccb3c0ef886vboxsync layout works. Other keyboard layouts will have at least some keys which
e5744f6df1c6a56f461e975f261f3ccb3c0ef886vboxsync produce the wrong results (often quite surprising effects), and for layouts
e5744f6df1c6a56f461e975f261f3ccb3c0ef886vboxsync which have significant differences to the US keyboard layout it is most
e5744f6df1c6a56f461e975f261f3ccb3c0ef886vboxsync likely unusable.</para>
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync <para>It is possible to install both the Oracle VM VirtualBox Extension
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync Pack and VNC, but only one VRDE module can be active at any time. The
7d7568ff57603038ac087fe88ab9d3fc157c98devboxsync following command switches to the VNC VRDE module in
7d7568ff57603038ac087fe88ab9d3fc157c98devboxsync VNC:<screen>VBoxManage setproperty vrdeextpack VNC</screen></para>
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync <para>Configuring the remote access works very similarly to VRDP (see
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync <xref linkend="vrde" />), with some limitations: VNC does not
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync support specifying several port numbers, and the authentication is done
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync differently. VNC can only deal with password authentication, and there
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync is no option to use password hashes. This leaves no other choice than
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync having a clear-text password in the VM configuration, which can be set with
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync the following command:<screen>VBoxManage modifyvm VMNAME --vrdeproperty VNCPassword=secret</screen></para>
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync <para>The user is responsible for keeping this password secret, and it
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync should be removed when a VM configuration is passed to another person,
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync for whatever purpose. Some VNC servers claim to have "encrypted" passwords
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync in the configuration. This is not true encryption, it is only concealing
a31538d939ee498bdcd18f8b967163d53dcefe0dvboxsync the passwords, which is exactly as secure as clear-text passwords.</para>
7d7568ff57603038ac087fe88ab9d3fc157c98devboxsync <para>The following command switches back to VRDP (if
7d7568ff57603038ac087fe88ab9d3fc157c98devboxsync installed):<screen>VBoxManage setproperty vrdeextpack "Oracle VM VirtualBox Extension Pack"</screen></para>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <title>Starting virtual machines during system boot</title>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <para>Starting with VirtualBox 4.2.0 it is possible to start VMs automatically during
0712f5299b395a8fcb2ec95a2b0bc16b8f0d9d58vboxsync system boot on Linux, Solaris and Mac OS X for all users. </para>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <title>Linux: starting the autostart service via <computeroutput>init</computeroutput></title>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <para>On Linux, the autostart service is activated by setting two variables in
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <computeroutput>/etc/default/virtualbox</computeroutput>.
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync The first one is <computeroutput>VBOXAUTOSTART_DB</computeroutput> which
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync contains an absolute path to the autostart database directory.
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync The directory should have write access for every user who should be able to
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync start virtual machines automatically. Furthermore the directory should have the
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync sticky bit set.
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync The second variable is <computeroutput>VBOXAUTOSTART_CONFIG</computeroutput>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync which points the service to the autostart configuration file which is used
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync during boot to determine whether to allow individual users to start a VM
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync automatically and configure startup delays.
a5082574e0ae7ff5d13ba4d68cc4900a1d376900vboxsync The configuration file can be placed in <computeroutput>/etc/vbox</computeroutput>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync and contains several options. One is <computeroutput>default_policy</computeroutput>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync which controls whether the autostart service allows or denies to start a VM
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync for users which are not in the exception list.
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync The exception list starts with <computeroutput>exception_list</computeroutput>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync and contains a comma seperated list with usernames. Furthermore a separate
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync startup delay can be configured for every user to avoid overloading the host.
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync A sample configuration is given below:</para>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync# Default policy is to deny starting a VM, the other option is "allow".
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsyncdefault_policy = deny
eec14e5e13bba628df2c85e643cbab5528f07b7fvboxsync# Bob is allowed to start virtual machines but starting them
eec14e5e13bba628df2c85e643cbab5528f07b7fvboxsync# will be delayed for 10 seconds
eec14e5e13bba628df2c85e643cbab5528f07b7fvboxsync allow = true
eec14e5e13bba628df2c85e643cbab5528f07b7fvboxsync startup_delay = 10
eec14e5e13bba628df2c85e643cbab5528f07b7fvboxsync# Alice is not allowed to start virtual machines, useful to exclude certain users
eec14e5e13bba628df2c85e643cbab5528f07b7fvboxsync# if the default policy is set to allow.
eec14e5e13bba628df2c85e643cbab5528f07b7fvboxsync allow = false
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <para>Every user who wants to enable autostart for individual machines
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync has to set the path to the autostart database directory with
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <screen>VBoxManage setproperty autostartdbpath <Autostart directory></screen>
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync <title>Solaris: starting the autostart service via SMF</title>
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync <para>On Solaris hosts, the VirtualBox autostart daemon is
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync integrated into the SMF framework. To enable it you have to point the service
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync to an existing configuration file which has the same format as on Linux (see <xref linkend="autostart-linux" />):
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync <screen>svccfg -s svc:/application/virtualbox/autostart:default setprop config/config=/etc/vbox/autostart.cfg</screen>
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync <para>When everything is configured correctly you can start the
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync VirtualBox autostart service with the following command:<screen>svcadm enable svc:/application/virtualbox/autostart:default</screen></para>
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync <para>For more information about SMF, please refer to the Solaris
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync documentation.</para>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <title>Mac OS X: starting the autostart service via launchd</title>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <para>On Mac OS X, launchd is used to start the VirtualBox autostart service. An
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync example configuration file can be found in
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <computeroutput>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</computeroutput>.
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync To enable the service copy the file to <computeroutput>/Library/LaunchDaemons</computeroutput> and change the
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <computeroutput>false</computeroutput>. Furthermore replace the second parameter
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync to an existing configuration file which has the same format as on Linux (see <xref linkend="autostart-linux" />).
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync To manually start the service use the following command:
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync <screen>launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist</screen>
2b55a3168b490c568b411befb5fb7d2e28813ee8vboxsync For additional information on how launchd services could be