source: vbox/trunk/doc/manual/en_US/user_AdvancedTopics.xml@ 64529

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="AdvancedTopics">
  <title>Advanced topics</title>

  <sect1 id="vboxsdl">
    <title>VBoxSDL, the simplified VM displayer</title>

    <sect2>
      <title>Introduction</title>

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

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

      <para><mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/vbox-sdl.png"
                       width="10cm" />
          </imageobject>
        </mediaobject></para>

      <para>To start a virtual machine with VBoxSDL instead of the VirtualBox
      GUI, enter the following on a command line:<screen>VBoxSDL --startvm &lt;vm&gt;</screen></para>

      <para>where <computeroutput>&lt;vm&gt;</computeroutput> is, as usual
      with VirtualBox command line parameters, the name or UUID of an existing
      virtual machine.</para>
    </sect2>

    <sect2>
      <title>Secure labeling with VBoxSDL</title>

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

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

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

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

      <para>The label text can be set with <screen>VBoxManage setextradata "VM name" "VBoxSDL/SecureLabel" "The Label"</screen>
      Changing this label will take effect immediately.</para>

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

      <screen>reduced_modeid = modeid + 0x30</screen>

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

      <screen>vga = 0x200 | 0x117 + 0x30
vga = 839</screen>

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

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

    <sect2>
      <title>Releasing modifiers with VBoxSDL on Linux</title>

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

      <para><screen>kill -usr1 &lt;pid&gt;
VBoxManage controlvm "Windows 2000" savestate</screen></para>
    </sect2>
  </sect1>

  <sect1 id="autologon">
    <title>Automated guest logons</title>

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

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

    <sect2 id="autologon_win">
      <title>Automated Windows guest logons</title>

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

      <para>To activate the VirtualBox GINA or credential provider module,
      install the Guest Additions with using the command line switch
      <computeroutput>/with_autologon</computeroutput>. All the following
      manual steps required for installing these modules will be then done by
      the installer.</para>

      <para>To manually install the VirtualBox GINA module, extract the Guest
      Additions (see <xref linkend="windows-guest-file-extraction" />) and
      copy the file <computeroutput>VBoxGINA.dll</computeroutput> to the
      Windows <computeroutput>SYSTEM32</computeroutput> directory. Then, in
      the registry, create the following key: <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen>
      with a value of <computeroutput>VBoxGINA.dll</computeroutput>.</para>

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

      <para>To manually install the VirtualBox credential provider module,
      extract the Guest Additions (see <xref
      linkend="windows-guest-file-extraction" />) and copy the file
      <computeroutput>VBoxCredProv.dll</computeroutput> to the Windows
      <computeroutput>SYSTEM32</computeroutput> directory. Then, in the
      registry, create the following keys:<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
           Authentication\Credential Providers\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}

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

HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32</screen></para>

      <para>with all default values (the key named
      <computeroutput>(Default)</computeroutput> in each key) set to
      <computeroutput>VBoxCredProv</computeroutput>. After that a new string
      named <screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen>
      with a value of <computeroutput>Apartment</computeroutput> has to be
      created.</para>

      <para>To set credentials, use the following command on a
      <emphasis>running</emphasis> VM:</para>

      <screen>VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</screen>

      <para>While the VM is running, the credentials can be queried by the
      VirtualBox logon modules (GINA or credential provider) using the
      VirtualBox Guest Additions device driver. When Windows is in "logged
      out" mode, the logon modules will constantly poll for credentials and if
      they are present, a logon will be attempted. After retrieving the
      credentials, the logon modules will erase them so that the above command
      will have to be repeated for subsequent logons.</para>

      <para>For security reasons, credentials are not stored in any persistent
      manner and will be lost when the VM is reset. Also, the credentials are
      "write-only", i.e. there is no way to retrieve the credentials from the
      host side. Credentials can be reset from the host side by setting empty
      values.</para>

      <para>Depending on the particular variant of the Windows guest, the
      following restrictions apply: <orderedlist>
          <listitem>
            <para>For <emphasis role="bold">Windows XP guests,</emphasis> the
            logon subsystem needs to be configured to use the classic logon
            dialog as the VirtualBox GINA module does not support the XP-style
            welcome dialog.</para>
          </listitem>

          <listitem>
            <para>For <emphasis role="bold">Windows Vista, Windows 7
            and Windows 8 guests,</emphasis> the logon subsystem does not support
            the so-called Secure Attention Sequence
            (<computeroutput>CTRL+ALT+DEL</computeroutput>). As a result, the
            guest's group policy settings need to be changed to not use the
            Secure Attention Sequence. Also, the user name given is only
            compared to the true user name, not the user friendly name. This
            means that when you rename a user, you still have to supply the
            original user name (internally, Windows never renames user
            accounts).</para>
          </listitem>

          <listitem>
            <para>Auto-logon handling of the built-in Windows Remote Desktop
            Service (formerly known as Terminal Services) is disabled by
            default. To enable it, create the registry key <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen>
            with a <computeroutput>DWORD</computeroutput> value of
            <computeroutput>1</computeroutput>.</para>
          </listitem>
        </orderedlist></para>

      <para>The following command forces VirtualBox to keep the credentials
      after they were read by the guest and on VM reset: <screen>VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</screen>Note
      that this is a potential security risk as a malicious application
      running on the guest could request this information using the proper
      interface.</para>
    </sect2>

    <sect2 id="autologon_unix">
      <title>Automated Linux/Unix guest logons</title>

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

      <para>For automated logons on Ubuntu (or Ubuntu-derived) distributions
      using LightDM as the display manager, please see
      <xref linkend="autologon_unix_lightdm" />.</para>

      <para>The <computeroutput>pam_vbox.so</computeroutput> module itself
      <emphasis role="bold">does not</emphasis> do an actual verification of
      the credentials passed to the guest OS; instead it relies on other
      modules such as <computeroutput>pam_unix.so</computeroutput> or
      <computeroutput>pam_unix2.so</computeroutput> down in the PAM stack to
      do the actual validation using the credentials retrieved by
      <computeroutput>pam_vbox.so</computeroutput>. Therefore
      <computeroutput>pam_vbox.so</computeroutput> has to be on top of the
      authentication PAM service list.</para>

      <note>
        <para>The <computeroutput>pam_vbox.so</computeroutput> only supports
        the <computeroutput>auth</computeroutput> primitive. Other primitives
        such as <computeroutput>account</computeroutput>,
        <computeroutput>session</computeroutput> or
        <computeroutput>password</computeroutput> are not supported.</para>
      </note>

      <para>The <computeroutput>pam_vbox.so</computeroutput> module is shipped
      as part of the Guest Additions but it is not installed and/or activated
      on the guest OS by default. In order to install it, it has to be copied
      from
      <computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/other/</computeroutput>
      to the security modules directory, usually
      <computeroutput>/lib/security/</computeroutput> on 32-bit guest Linuxes
      or <computeroutput>/lib64/security/</computeroutput> on 64-bit ones.
      Please refer to your guest OS documentation for the correct PAM module
      directory.</para>

      <para>For example, to use <computeroutput>pam_vbox.so</computeroutput>
      with a Ubuntu Linux guest OS and GDM (the GNOME Desktop Manager) to
      logon users automatically with the credentials passed by the host, the
      guest OS has to be configured like the following:</para>

      <orderedlist>
        <listitem>
          <para>The <computeroutput>pam_vbox.so</computeroutput> module has to
          be copied to the security modules directory, in this case it is
          <computeroutput>/lib/security</computeroutput>.</para>
        </listitem>

        <listitem>
          <para>Edit the PAM configuration file for GDM found at
          <computeroutput>/etc/pam.d/gdm</computeroutput>, adding the line
          <computeroutput>auth requisite pam_vbox.so</computeroutput> at the
          top. Additionally, in most Linux distributions there is a file called
          <computeroutput>/etc/pam.d/common-auth</computeroutput>. This file
          is included in many other services (like the GDM file mentioned
          above). There you also have to add the line <computeroutput>auth
          requisite pam_vbox.so</computeroutput>.</para>
        </listitem>

        <listitem>
          <para>If authentication against the shadow database using
          <computeroutput>pam_unix.so</computeroutput> or
          <computeroutput>pam_unix2.so</computeroutput> is desired, the
          argument <computeroutput>try_first_pass</computeroutput> for
          <computeroutput>pam_unix.so</computeroutput> or
          <computeroutput>use_first_pass</computeroutput> for
          <computeroutput>pam_unix2.so</computeroutput> is needed in order to
          pass the credentials from the VirtualBox module to the shadow
          database authentication module. For Ubuntu, this needs to be added
          to <computeroutput>/etc/pam.d/common-auth</computeroutput>, to the
          end of the line referencing
          <computeroutput>pam_unix.so</computeroutput>. This argument tells
          the PAM module to use credentials already present in the stack, i.e.
          the ones provided by the VirtualBox PAM module.</para>
        </listitem>
      </orderedlist>

      <para><warning>
          <para>An incorrectly configured PAM stack can effectively prevent
          you from logging into your guest system!</para>
        </warning></para>

      <para>To make deployment easier, you can pass the argument
      <computeroutput>debug</computeroutput> right after the
      <computeroutput>pam_vbox.so</computeroutput> statement. Debug log output
      will then be recorded using syslog.</para>

      <para><note>
          <para>By default, pam_vbox will not wait for credentials to arrive
          from the host, in other words: When a login prompt is shown (for
          example by GDM/KDM or the text console) and pam_vbox does not yet
          have credentials it does not wait until they arrive. Instead the
          next module in the PAM stack (depending on the PAM configuration)
          will have the chance for authentication.</para>
        </note></para>

      <para>Starting with VirtualBox 4.1.4 pam_vbox supports various guest
      property parameters which all reside in
      <computeroutput>/VirtualBox/GuestAdd/PAM/</computeroutput>. These
      parameters allow pam_vbox to wait for credentials to be provided by the
      host and optionally can show a message while waiting for those. The
      following guest properties can be set:</para>

      <orderedlist>
        <listitem>
          <para><computeroutput>CredsWait</computeroutput>: Set to "1" if
          pam_vbox should start waiting until credentials arrive from the
          host. Until then no other authentication methods such as manually
          logging in will be available. If this property is empty or get
          deleted no waiting for credentials will be performed and pam_vbox
          will act like before (see paragraph above). This property must be
          set read-only for the guest
          (<computeroutput>RDONLYGUEST</computeroutput>).</para>
        </listitem>

        <listitem>
          <para><computeroutput>CredsWaitAbort</computeroutput>: Aborts waiting
          for credentials when set to any value. Can be set from host and the
          guest.</para>
        </listitem>

        <listitem>
          <para><computeroutput>CredsWaitTimeout</computeroutput>: Timeout (in
          seconds) to let pam_vbox wait for credentials to arrive. When no
          credentials arrive within this timeout, authentication of pam_vbox
          will be set to failed and the next PAM module in chain will be
          asked. If this property is not specified, set to "0" or an invalid
          value, an infinite timeout will be used. This property must be set
          read-only for the guest
          (<computeroutput>RDONLYGUEST</computeroutput>).</para>
        </listitem>
      </orderedlist>

      <para>To customize pam_vbox further there are the following guest
      properties:</para>

      <orderedlist>
        <listitem>
          <para><computeroutput>CredsMsgWaiting</computeroutput>: Custom
          message showed while pam_vbox is waiting for credentials from the
          host. This property must be set read-only for the guest
          (<computeroutput>RDONLYGUEST</computeroutput>).</para>
        </listitem>

        <listitem>
          <para><computeroutput>CredsMsgWaitTimeout</computeroutput>: Custom
          message showed when waiting for credentials by pam_vbox timed out,
          e.g. did not arrive within time. This property must be set read-only
          for the guest (<computeroutput>RDONLYGUEST</computeroutput>).</para>
        </listitem>
      </orderedlist>

      <para><note>
          <para>If a pam_vbox guest property does not have set the right flags
          (<computeroutput>RDONLYGUEST</computeroutput>) this property will be
          ignored then and - depending on the property - a default value will
          be set. This can result in pam_vbox not waiting for credentials.
          Consult the appropriate syslog file for more information and use the
          <computeroutput>debug</computeroutput> option.</para>
        </note></para>

      <sect3 id="autologon_unix_lightdm">
        <title>VirtualBox Greeter for Ubuntu / LightDM</title>

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

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

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

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

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

        <para><screen>[SeatDefaults]
greeter-session=vbox-greeter</screen></para>

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

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

        <para>There are numerous guest properties which can be used to further
        customize the login experience. For automatically logging in users, the
        same guest properties apply as for pam_vbox, see
        <xref linkend="autologon_unix" />.</para>

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

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

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

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

          <listitem>
            <para><computeroutput>UseTheming</computeroutput>: Set to "1" for
            turning on the following theming options. This property must be
            set read-only for the guest
            (<computeroutput>RDONLYGUEST</computeroutput>).</para>
          </listitem>

          <listitem>
            <para><computeroutput>Theme/BackgroundColor</computeroutput>:
            Hexadecimal RRGGBB color for the background. This property must be
            set read-only for the guest
            (<computeroutput>RDONLYGUEST</computeroutput>).</para>
          </listitem>

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

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

          <listitem>
            <para><computeroutput>Theme/LogonDialog/ButtonColor</computeroutput>:
            Hexadecimal RRGGBB background color for the logon dialog button. This
            property must be set read-only for the guest
            (<computeroutput>RDONLYGUEST</computeroutput>).</para>
          </listitem>
        </orderedlist>

        <note><para>The same restrictions for the guest properties above apply
        as for the ones specified in the pam_vbox section.</para></note>
      </sect3>
    </sect2>
  </sect1>

  <sect1>
    <title>Advanced configuration for Windows guests</title>

    <sect2 id="sysprep">
      <title>Automated Windows system preparation</title>

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

      <para>Starting with VirtualBox 3.2.2, the Guest Additions offer a way to
      launch a system preparation on the guest operating system in an
      automated way, controlled from the host system. To achieve that, see
      <xref linkend="guestadd-guestcontrol" /> for using the feature with the
      special identifier <computeroutput>sysprep</computeroutput> as the
      program to execute, along with the user name
      <computeroutput>sysprep</computeroutput> and password
      <computeroutput>sysprep</computeroutput> for the credentials. Sysprep
      then gets launched with the required system rights.</para>

      <note>
        <para>Specifying the location of "sysprep.exe" is <emphasis
        role="bold">not possible</emphasis> -- instead the following paths are
        used (based on the operating system): <itemizedlist>
            <listitem>
              <para><computeroutput>C:\sysprep\sysprep.exe</computeroutput>
              for Windows NT 4.0, 2000 and XP</para>
            </listitem>

            <listitem>
              <para><computeroutput>%WINDIR%\System32\Sysprep\sysprep.exe</computeroutput>
              for Windows Vista, 2008 Server and 7</para>
            </listitem>
          </itemizedlist> The Guest Additions will automatically use the
        appropriate path to execute the system preparation tool.</para>
      </note>
    </sect2>
  </sect1>

  <sect1>
    <title>Advanced configuration for Linux and Solaris guests</title>

    <sect2>
      <title>Manual setup of selected guest services on Linux</title>

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

      <screen>  sh ./VBoxLinuxAdditions.run no_setup</screen>

      <para>After this, you will need to at least compile the kernel modules
      by running the command <screen>  rcvboxadd setup</screen>
      as root (you will need to replace <emphasis>lib</emphasis> by
      <emphasis>lib64</emphasis> on some 64bit guests), and on older guests
      without the udev service you will need to add the
      <emphasis>vboxadd</emphasis> service to the default runlevel to ensure
      that the modules get loaded.</para>

      <para>To setup the time synchronization service,
      add the service vboxadd-service to the default runlevel. To set up the
      X11 and OpenGL part of the Guest Additions, run the command
      <screen>  rcvboxadd-x11 setup</screen>
      (you do not need to enable any services for this).</para>

      <para>To recompile the guest kernel modules, use this command:
      <screen>  rcvboxadd setup</screen>
      After compilation you should reboot your guest to ensure that the new
      modules are actually used.</para>
    </sect2>

    <sect2 id="guestxorgsetup">
      <title>Guest graphics and mouse driver setup in depth</title>

      <para>This section assumes that you are familiar with configuring the
      X.Org server using xorg.conf and optionally the newer mechanisms using
      hal or udev and xorg.conf.d. If not you can learn about them by studying
      the documentation which comes with X.Org.</para>

      <para>The VirtualBox Guest Additions come with drivers for X.Org
      versions <itemizedlist>
          <listitem>
            <para>X11R6.8/X11R6.9 and XFree86 version 4.3 (vboxvideo_drv_68.o and vboxmouse_drv_68.o)</para>
          </listitem>

          <listitem>
            <para>X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so)</para>
          </listitem>

          <listitem>
            <para>X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so)</para>
          </listitem>

          <listitem>
            <para>X.Org Server versions 1.3 and later (vboxvideo_drv_13.so and vboxmouse_drv_13.so and so on).</para>
          </listitem>
        </itemizedlist> By default these drivers can be found in the
      directory</para>

      <para><computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/other/</computeroutput></para>

      <para>and the correct versions for the X server are symbolically linked
      into the X.Org driver directories.</para>

      <para>For graphics integration to work correctly, the X server must load
      the vboxvideo driver (many recent X server versions look for it
      automatically if they see that they are running in VirtualBox) and for
      an optimal user experience the guest kernel drivers must be loaded and
      the Guest Additions tool VBoxClient must be running as a client in the X
      session. For mouse integration to work correctly, the guest kernel
      drivers must be loaded and in addition, in X servers from X.Org X11R6.8
      to X11R7.1 and in XFree86 version 4.3 the right vboxmouse driver must be
      loaded and associated with /dev/mouse or /dev/psaux; in X.Org server 1.3
      or later a driver for a PS/2 mouse must be loaded and the right
      vboxmouse driver must be associated with /dev/vboxguest.</para>

      <para>The VirtualBox guest graphics driver can use any graphics
      configuration for which the virtual resolution fits into the virtual
      video memory allocated to the virtual machine (minus a small amount used
      by the guest driver) as described in <xref
      linkend="settings-display" />. The driver will offer a range of standard
      modes at least up to the default guest resolution for all active guest
      monitors. In X.Org Server 1.3 and later the default mode can be changed
      by setting the output property VBOX_MODE to
      "&lt;width&gt;x&lt;height&gt;" for any guest monitor. When VBoxClient
      and the kernel drivers are active this is done automatically when the
      host requests a mode change. The driver for older versions can only
      receive new modes by querying the host for requests at regular
      intervals.</para>

      <para>With pre-1.3 X Servers you can also add your own modes to the X
      server configuration file. You simply need to add them to the "Modes"
      list in the "Display" subsection of the "Screen" section. For example,
      the section shown here has a custom 2048x800 resolution mode
      added:</para>

      <screen>Section "Screen"
        Identifier    "Default Screen"
        Device        "VirtualBox graphics card"
        Monitor       "Generic Monitor"
        DefaultDepth  24
        SubSection "Display"
                Depth         24
                Modes         "2048x800" "800x600" "640x480"
        EndSubSection
EndSection</screen>
    </sect2>
  </sect1>

  <sect1 id="cpuhotplug">
    <title>CPU hot-plugging</title>

    <para>With virtual machines running modern server operating systems,
    VirtualBox supports CPU hot-plugging.<footnote>
        <para>Support for CPU hot-plugging was introduced with VirtualBox
        3.2.</para>
      </footnote> Whereas on a physical computer this would mean that a CPU
    can be added or removed while the machine is running, VirtualBox supports
    adding and removing virtual CPUs while a virtual machine is
    running.</para>

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

    <para>At this time, CPU hot-plugging requires using the VBoxManage
    command-line interface. First, hot-plugging needs to be enabled for a
    virtual machine:<screen>VBoxManage modifyvm "VM name" --cpuhotplug on</screen></para>

    <para>After that, the <computeroutput>--cpus</computeroutput> option specifies the maximum number of CPUs
    that the virtual machine can have:<screen>VBoxManage modifyvm "VM name" --cpus 8</screen>When
    the VM is off, you can then add and remove virtual CPUs with the
    <computeroutput>modifyvm --plugcpu</computeroutput> and
    <computeroutput>--unplugcpu</computeroutput> subcommands, which take the number of the
    virtual CPU as a parameter, like this:<screen>VBoxManage modifyvm "VM name" --plugcpu 3
VBoxManage modifyvm "VM name" --unplugcpu 3</screen>Note that CPU 0 can never
    be removed.</para>

    <para>While the VM is running, CPUs can be added and removed with the
    <computeroutput>controlvm plugcpu</computeroutput> and
    <computeroutput>unplugcpu</computeroutput> commands
    instead:<screen>VBoxManage controlvm "VM name" plugcpu 3
VBoxManage controlvm "VM name" unplugcpu 3</screen></para>

    <para>See <xref linkend="vboxmanage-modifyvm" /> and <xref
    linkend="vboxmanage-controlvm" /> for details.</para>

    <para>With Linux guests, the following applies: To prevent ejection while
    the CPU is still used it has to be ejected from within the guest before.
    The Linux Guest Additions contain a service which receives hot-remove
    events and ejects the CPU. Also, after a CPU is added to the VM it is not
    automatically used by Linux. The Linux Guest Additions service will take
    care of that if installed. If not a CPU can be started with the following
    command:<screen>echo 1 &gt; /sys/devices/system/cpu/cpu&lt;id&gt;/online</screen></para>
  </sect1>

  <sect1 id="pcipassthrough">
    <title>PCI passthrough</title>

    <para>When running on Linux hosts, with a recent enough kernel (at least
    version <computeroutput>2.6.31</computeroutput>) experimental host PCI
    devices passthrough is available.<footnote>
        <para>Experimental support for PCI passthrough was introduced with
        VirtualBox 4.1.</para>
      </footnote></para>

    <note>
      <para>The PCI passthrough module is shipped as a VirtualBox extension
      package, which must be installed separately. See <xref
      linkend="intro-installing" /> for more information.</para>
    </note>

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

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

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

    <para>It is very common that the BIOS or the host OS disables the IOMMU by
    default. So before any attempt to use it please make sure that
    <orderedlist>
        <listitem>
          <para>Your motherboard has an IOMMU unit.</para>
        </listitem>

        <listitem>
          <para>Your CPU supports the IOMMU.</para>
        </listitem>

        <listitem>
          <para>The IOMMU is enabled in the BIOS.</para>
        </listitem>

        <listitem>
          <para>The VM must run with VT-x/AMD-V and nested paging
          enabled.</para>
        </listitem>

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

        <listitem>
          <para>Your Linux kernel recognizes and uses the IOMMU unit
          (<computeroutput>intel_iommu=on</computeroutput> boot option could
          be needed). Search for DMAR and PCI-DMA in kernel boot log.</para>
        </listitem>
      </orderedlist></para>

    <para>Once you made sure that the host kernel supports the IOMMU, the next
    step is to select the PCI card and attach it to the guest. To figure out
    the list of available PCI devices, use the
    <computeroutput>lspci</computeroutput> command. The output will look like
    this:</para>
    <screen>01:00.0 VGA compatible controller: ATI Technologies Inc Cedar PRO [Radeon HD 5450]
01:00.1 Audio device: ATI Technologies Inc Manhattan HDMI Audio [Mobility Radeon HD 5000 Series]
02:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168B PCI Express Gigabit
        Ethernet controller (rev 03)
03:00.0 SATA controller: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
03:00.1 IDE interface: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
06:00.0 VGA compatible controller: nVidia Corporation G86 [GeForce 8500 GT] (rev a1)</screen>
    <para>The first column is a PCI address (in format
    <computeroutput>bus:device.function</computeroutput>). This address could
    be used to identify the device for further operations. For example, to
    attach a PCI network controller on the system listed above to the second
    PCI bus in the guest, as device 5, function 0, use the following command:
    <screen>VBoxManage modifyvm "VM name" --pciattach 02:00.0@01:05.0</screen>
    To detach same device, use <screen>VBoxManage modifyvm "VM name" --pcidetach 02:00.0</screen>
    Please note that both host and guest could freely assign a different PCI
    address to the card attached during runtime, so those addresses only apply
    to the address of the card at the moment of attachment (host), and during
    BIOS PCI init (guest).</para>

    <para>If the virtual machine has a PCI device attached, certain
    limitations apply: <orderedlist>
        <listitem>
           <para>Only PCI cards with non-shared interrupts (such as using MSI on host) are supported at the moment.</para>
        </listitem>

        <listitem>
           <para>No guest state can be reliably saved/restored (as the internal state of the PCI card could not be retrieved).</para>
        </listitem>

        <listitem>
           <para>Teleportation (live migration) doesn't work (for the same reason).</para>
        </listitem>

        <listitem>
           <para>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).</para>
        </listitem>
      </orderedlist></para>
  </sect1>

  <sect1>
    <title>Webcam passthrough</title>

    <sect2 id="webcam-passthrough">
      <title>Using a host webcam in the guest</title>

      <para>VirtualBox 4.3 includes an experimental feature which allows a guest to use
      a host webcam. This complements the general USB passthrough support which was the
      typical way of using host webcams in earlier versions. The webcam passthrough support
      can handle non-USB video sources in theory, but this is completely untested.</para>

      <note>
        <para>The webcam passthrough module is shipped as part of the Oracle VM VirtualBox
        extension pack, which must be installed separately. See <xref
        linkend="intro-installing" /> for more information.</para>
      </note>

      <para>The host webcam can be attached to the VM using "Devices" menu in the VM menu bar.
      The "Webcams" menu contains a list of available video input devices on the host.
      Clicking on a webcam name attaches or detaches the corresponding host device.</para>

      <para>The VBoxManage command line tool can be used to enable webcam passthrough.
      Please see the host-specific sections below for additional details.
      The following commands are available:
        <itemizedlist>
          <listitem><para>Get a list of host webcams (or other video input devices):
            <screen>VBoxManage list webcams</screen>
            The output format:
            <screen>alias "user friendly name"
host path or identifier</screen>
            The alias can be used as a shortcut in other commands. Alias '.0' means
            default video input device on the host, '.1', '.2', etc mean first, second, etc
            video input device. The device order is host-specific.
          </para></listitem>
          <listitem><para>Attach a webcam to a running VM:
            <screen>VBoxManage controlvm "VM name" webcam attach [host_path|alias [settings]]</screen>
            This will attach a USB webcam device to the guest.</para>

            <para>The <computeroutput>settings</computeroutput> parameter is a string
            <computeroutput>Setting1=Value1;Setting2=Value2</computeroutput>, which allows to
            configure the emulated webcam device. The following settings are supported:
            <itemizedlist>
              <listitem>
                <para><computeroutput>MaxFramerate</computeroutput> The highest rate at which video frames
                are sent to the guest. A higher frame rate requires more CPU power. Therefore sometimes
                it is useful to set a lower limit. Default is no limit and allow the guest to use all
                frame rates supported by the host webcam.</para>
              </listitem>
              <listitem>
                <para><computeroutput>MaxPayloadTransferSize</computeroutput> How many bytes the emulated
                webcam can send to the guest at a time. Default value is 3060 bytes, which is used by
                some webcams. Higher values can slightly reduce CPU load, if the guest is able to use
                larger buffers. However, a high <computeroutput>MaxPayloadTransferSize</computeroutput>
                might be not supported by some guests.</para>
              </listitem>
            </itemizedlist>
          </para></listitem>
          <listitem><para>Detach a webcam from a running VM:
            <screen>VBoxManage controlvm "VM name" webcam detach [host_path|alias]</screen>
          </para></listitem>
          <listitem><para>List webcams attached to a running VM:
            <screen>VBoxManage controlvm "VM name" webcam list</screen>
            The output contains path or alias which was used in 'webcam attach' command for
            each attached webcam.
          </para></listitem>
        </itemizedlist>
      </para>
    </sect2>

    <sect2>
      <title>Windows hosts</title>

      <para>When the webcam device is detached from the host, the emulated webcam device is
      automatically detached from the guest.</para>
    </sect2>

    <sect2>
      <title>Mac OS X hosts</title>

      <para>OS X version 10.9 or newer is required.</para>

      <para>When the webcam device is detached from the host, the emulated webcam device
      remains attached to the guest and must be manually detached using the
      <computeroutput>VBoxManage controlvm "VM name" webcam detach ...</computeroutput> command.</para>
    </sect2>

    <sect2>
      <title>Linux and Solaris hosts</title>

      <para>When the webcam is detached from the host the emulated webcam device is
      automatically detached from the guest only if the webcam is streaming video.
      If the emulated webcam is inactive it should be manually detached using the
      <computeroutput>VBoxManage controlvm "VM name" webcam detach ...</computeroutput> command.</para>

      <para>Aliases <computeroutput>.0</computeroutput> and <computeroutput>.1</computeroutput> are mapped
      to <computeroutput>/dev/video0</computeroutput>, alias <computeroutput>.2</computeroutput> is mapped
      to <computeroutput>/dev/video1</computeroutput> and so forth.</para>
    </sect2>
  </sect1>

  <sect1>
    <title>Advanced display configuration</title>

    <sect2>
      <title>Custom VESA resolutions</title>

      <para>Apart from the standard VESA resolutions, the VirtualBox VESA BIOS
      allows you to add up to 16 custom video modes which will be reported to
      the guest operating system. When using Windows guests with the
      VirtualBox Guest Additions, a custom graphics driver will be used
      instead of the fallback VESA solution so this information does not
      apply.</para>

      <para>Additional video modes can be configured for each VM using the
      extra data facility. The extra data key is called
      <literal>CustomVideoMode&lt;x&gt;</literal> with <literal>x</literal>
      being a number from 1 to 16. Please note that modes will be read from 1
      until either the following number is not defined or 16 is reached. The
      following example adds a video mode that corresponds to the native
      display resolution of many notebook computers:</para>

      <screen>VBoxManage setextradata "VM name" "CustomVideoMode1" "1400x1050x16"</screen>

      <para>The VESA mode IDs for custom video modes start at
      <literal>0x160</literal>. In order to use the above defined custom video
      mode, the following command line has be supplied to Linux:</para>

      <screen>vga = 0x200 | 0x160
vga = 864</screen>

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

    <sect2>
      <title>Configuring the maximum resolution of guests when using the
      graphical frontend</title>

      <para>When guest systems with the Guest Additions installed are started
      using the graphical frontend (the normal VirtualBox application), they
      will not be allowed to use screen resolutions greater than the host's
      screen size unless the user manually resizes them by dragging the
      window, switching to full screen or seamless mode or sending a video mode
      hint using VBoxManage. This behavior is what most users will want, but
      if you have different needs, it is possible to change it by issuing one
      of the following commands from the command line:</para>

      <screen>VBoxManage setextradata global GUI/MaxGuestResolution any</screen>

      <para>will remove all limits on guest resolutions.</para>

      <screen>VBoxManage setextradata global GUI/MaxGuestResolution &gt;width,height&lt;</screen>

      <para>manually specifies a maximum resolution.</para>

      <screen>VBoxManage setextradata global GUI/MaxGuestResolution auto</screen>

      <para>restores the default settings. Note that these settings apply
      globally to all guest systems, not just to a single machine.</para>
    </sect2>
  </sect1>

  <sect1>
    <title>Advanced storage configuration</title>

    <sect2 id="rawdisk">
      <title>Using a raw host hard disk from a guest</title>

      <para>Starting with version 1.4, as an alternative to using virtual disk
      images (as described in detail in <xref linkend="storage" />),
      VirtualBox can also present either entire physical hard disks or
      selected partitions thereof as virtual disks to virtual machines.</para>

      <para>With VirtualBox, this type of access is called "raw hard disk
      access"; it allows a guest operating system to access its virtual hard
      disk without going through the host OS file system. The actual
      performance difference for image files vs. raw disk varies greatly
      depending on the overhead of the host file system, whether dynamically
      growing images are used, and on host OS caching strategies. The caching
      indirectly also affects other aspects such as failure behavior, i.e.
      whether the virtual disk contains all data written before a host OS
      crash. Consult your host OS documentation for details on this.</para>

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

      <para>Raw hard disk access -- both for entire disks and individual
      partitions -- is implemented as part of the VMDK image format support.
      As a result, you will need to create a special VMDK image file which
      defines where the data will be stored. After creating such a special
      VMDK image, you can use it like a regular virtual disk image. For
      example, you can use the VirtualBox Manager (<xref linkend="vdis" />)
      or <computeroutput>VBoxManage</computeroutput> to assign the image to a
      virtual machine.</para>

      <sect3>
        <title>Access to entire physical hard disk</title>

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

        <para>To create an image that represents an entire physical hard disk
        (which will not contain any actual data, as this will all be stored on
        the physical disk), on a Linux host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
      -rawdisk /dev/sda</screen>This creates the image
        <code>/path/to/file.vmdk</code> (must be absolute), and all data will
        be read and written from <code>/dev/sda</code>.</para>

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

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

        <para>Just like with regular disk images, this does not automatically
        attach the newly created image to a virtual machine. This can be done
        with e.g. <screen>VBoxManage storageattach WindowsXP --storagectl "IDE Controller"
      --port 0 --device 0 --type hdd --medium /path/to/file.vmdk</screen>When
        this is done the selected virtual machine will boot from the specified
        physical disk.</para>
      </sect3>

      <sect3>
        <title>Access to individual physical hard disk partitions</title>

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

        <para>To create a special image for raw partition support (which will
        contain a small amount of data, as already mentioned), on a Linux
        host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
      -rawdisk /dev/sda -partitions 1,5</screen></para>

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

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

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

        <para>The numbers for the list of partitions can be taken from the
        output of<screen>VBoxManage internalcommands listpartitions -rawdisk /dev/sda</screen>The
        output lists the partition types and sizes to give the user enough
        information to identify the partitions necessary for the guest.</para>

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

        <para>Creating the image requires read/write access for the given
        device. Read/write access is also later needed when using the image
        from a virtual machine. If this is not feasible, there is a special
        variant for raw partition access (currently only available on Linux
        hosts) that avoids having to give the current user access to the
        entire disk. To set up such an image, use<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
      -rawdisk /dev/sda -partitions 1,5 -relative</screen>When used from a
        virtual machine, the image will then refer not to the entire disk, but
        only to the individual partitions (in the example
        <code>/dev/sda1</code> and <code>/dev/sda5</code>). As a consequence,
        read/write access is only required for the affected partitions, not
        for the entire disk. During creation however, read-only access to the
        entire disk is required to obtain the partitioning information.</para>

        <para>In some configurations it may be necessary to change the MBR
        code of the created image, e.g. to replace the Linux boot loader that
        is used on the host by another boot loader. This allows e.g. the guest
        to boot directly to Windows, while the host boots Linux from the
        "same" disk. For this purpose the
        <computeroutput>-mbr</computeroutput> parameter is provided. It
        specifies a file name from which to take the MBR code. The partition
        table is not modified at all, so a MBR file from a system with totally
        different partitioning can be used. An example of this is<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
      -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr</screen>The modified
        MBR will be stored inside the image, not on the host disk.</para>

        <para>The created image can be attached to a storage controller in a
        VM configuration as usual.</para>
      </sect3>
    </sect2>

    <sect2 id="changevpd">
      <title>Configuring the hard disk vendor product data (VPD)</title>

      <para>VirtualBox reports vendor product data for its virtual hard disks
      which consist of hard disk serial number, firmware revision and model
      number. These can be changed using the following commands:</para>

      <screen>VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model"</screen>

      <para>The serial number is a 20 byte alphanumeric string, the firmware
      revision an 8 byte alphanumeric string and the model number a 40 byte
      alphanumeric string. Instead of "Port0" (referring to the first port),
      specify the desired SATA hard disk port.</para>

      <para>The above commands apply to virtual machines with an AHCI (SATA)
      controller. The commands for virtual machines with an IDE controller
      are:</para>

      <screen>VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model"</screen>

      <para>For hard disks it's also possible to mark the
      drive as having a non-rotational medium with:</para>

      <screen>VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1"</screen>

      <para>Additional three parameters are needed for CD/DVD drives to report
      the vendor product data:</para>

      <screen>VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIRevision" "revision"</screen>

      <para>The vendor id is an 8 byte alphanumeric string, the product id an
      16 byte alphanumeric string and the revision a 4 byte alphanumeric
      string. Instead of "Port0" (referring to the first port), specify the
      desired SATA hard disk port.</para>
    </sect2>

    <sect2 id="iscsi-intnet">
      <title>Access iSCSI targets via Internal Networking</title>

      <para>As an experimental feature, VirtualBox allows for accessing an
      iSCSI target running in a virtual machine which is configured for using
      Internal Networking mode. Please see <xref linkend="storage-iscsi" />;
      <xref linkend="network_internal" />; and <xref
      linkend="vboxmanage-storageattach" /> for additional information.</para>

      <para>The IP stack accessing Internal Networking must be configured in
      the virtual machine which accesses the iSCSI target. A free static IP
      and a MAC address not used by other virtual machines must be chosen. In
      the example below, adapt the name of the virtual machine, the MAC
      address, the IP configuration and the Internal Networking name
      ("MyIntNet") according to your needs. The following eight commands must
      first be issued:<screen>VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Trusted 1
VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f
VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1
VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0
VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet
VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet
VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/TrunkType 2
VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen></para>

      <para>Finally the iSCSI disk must be attached with the
      <computeroutput>--intnet</computeroutput> option to tell the iSCSI
      initiator to use internal networking:<screen>VBoxManage storageattach ... --medium iscsi
         --server 10.0.9.30 --target iqn.2008-12.com.sun:sampletarget --intnet</screen></para>

      <para>Compared to a "regular" iSCSI setup, IP address of the target
      <emphasis>must</emphasis> be specified as a numeric IP address, as there
      is no DNS resolver for internal networking.</para>

      <para>The virtual machine with the iSCSI target should be started before
      the VM using it is powered on. If a virtual machine using an iSCSI disk
      is started without having the iSCSI target powered up, it can take up to
      200 seconds to detect this situation. The VM will fail to power
      up.</para>
    </sect2>
  </sect1>

  <sect1>
    <title>Legacy commands for using serial ports</title>

    <para>Starting with version 1.4, VirtualBox provided support for virtual
    serial ports, which, at the time, was rather complicated to set up with a
    sequence of <computeroutput>VBoxManage setextradata</computeroutput>
    statements. Since version 1.5, that way of setting up serial ports is no
    longer necessary and <emphasis>deprecated.</emphasis> To set up virtual
    serial ports, use the methods now described in <xref
    linkend="serialports" />.<note>
        <para>For backwards compatibility, the old
        <computeroutput>setextradata</computeroutput> statements, whose
        description is retained below from the old version of the manual, take
        <emphasis>precedence</emphasis> over the new way of configuring serial
        ports. As a result, if configuring serial ports the new way doesn't
        work, make sure the VM in question does not have old configuration
        data such as below still active.</para>
      </note></para>

    <para>The old sequence of configuring a serial port used the following 6
    commands:</para>

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

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

  <sect1 id="changenat">
    <title>Fine-tuning the VirtualBox NAT engine</title>

    <sect2>
      <title>Configuring the address of a NAT network interface</title>

      <para>In NAT mode, the guest network interface is assigned to the IPv4
      range <computeroutput>10.0.x.0/24</computeroutput> by default where
      <computeroutput>x</computeroutput> corresponds to the instance of the
      NAT interface +2. So <computeroutput>x</computeroutput> is 2 when there
      is only one NAT instance active. In that case the guest is assigned to
      the address <computeroutput>10.0.2.15</computeroutput>, the gateway is
      set to <computeroutput>10.0.2.2</computeroutput> and the name server can
      be found at <computeroutput>10.0.2.3</computeroutput>.</para>

      <para>If, for any reason, the NAT network needs to be changed, this can
      be achieved with the following command:</para>

      <screen>VBoxManage modifyvm "VM name" --natnet1 "192.168/16"</screen>

      <para>This command would reserve the network addresses from
      <computeroutput>192.168.0.0</computeroutput> to
      <computeroutput>192.168.254.254</computeroutput> for the first NAT
      network instance of "VM name". The guest IP would be assigned to
      <computeroutput>192.168.0.15</computeroutput> and the default gateway
      could be found at <computeroutput>192.168.0.2</computeroutput>.</para>
    </sect2>

    <sect2 id="nat-adv-tftp">
      <title>Configuring the boot server (next server) of a NAT network
      interface</title>

      <para>For network booting in NAT mode, by default VirtualBox uses a
      built-in TFTP server at the IP address 10.0.2.4. This default behavior
      should work fine for typical remote-booting scenarios. However, it is
      possible to change the boot server IP and the location of the boot image
      with the following commands: <screen>VBoxManage modifyvm "VM name" --nattftpserver1 10.0.2.2
VBoxManage modifyvm "VM name" --nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</screen></para>
    </sect2>

    <sect2 id="nat-adv-settings">
      <title>Tuning TCP/IP buffers for NAT</title>

      <para>The VirtualBox NAT stack performance is often determined by its
      interaction with the host's TCP/IP stack and the size of several buffers
      (<computeroutput>SO_RCVBUF</computeroutput> and
      <computeroutput>SO_SNDBUF</computeroutput>). For certain setups users
      might want to adjust the buffer size for a better performance. This can
      by achieved using the following commands (values are in kilobytes and
      can range from 8 to 1024): <screen>VBoxManage modifyvm "VM name" --natsettings1 16000,128,128,0,0</screen>
      This example illustrates tuning the NAT settings. The first parameter is
      the MTU, then the size of the socket's send buffer and the size of the
      socket's receive buffer, the initial size of the TCP send window, and
      lastly the initial size of the TCP receive window. Note that specifying
      zero means fallback to the default value.</para>

      <para>Each of these buffers has a default size of 64KB and default MTU
      is 1500.</para>
    </sect2>

    <sect2>
      <title>Binding NAT sockets to a specific interface</title>

      <para>By default, VirtualBox's NAT engine will route TCP/IP packets
      through the default interface assigned by the host's TCP/IP stack. (The
      technical reason for this is that the NAT engine uses sockets for
      communication.) If, for some reason, you want to change this behavior,
      you can tell the NAT engine to bind to a particular IP address instead.
      Use the following command: <screen>VBoxManage modifyvm "VM name" --natbindip1 "10.45.0.2"</screen></para>

      <para>After this, all outgoing traffic will be sent through the
      interface with the IP address 10.45.0.2. Please make sure that this
      interface is up and running prior to this assignment.</para>
    </sect2>

    <sect2 id="nat-adv-dns">
      <title>Enabling DNS proxy in NAT mode</title>

      <para>The NAT engine by default offers the same DNS servers to the guest
      that are configured on the host. In some scenarios, it can be desirable
      to hide the DNS server IPs from the guest, for example when this
      information can change on the host due to expiring DHCP leases. In this
      case, you can tell the NAT engine to act as DNS proxy using the
      following command: <screen>VBoxManage modifyvm "VM name" --natdnsproxy1 on</screen></para>
    </sect2>

    <sect2 id="nat_host_resolver_proxy">
      <title>Using the host's resolver as a DNS proxy in NAT mode</title>

      <para>For resolving network names, the DHCP server of the NAT engine
      offers a list of registered DNS servers of the host. If for some reason
      you need to hide this DNS server list and use the host's resolver
      settings, thereby forcing the VirtualBox NAT engine to intercept DNS
      requests and forward them to host's resolver, use the following command:
      <screen>VBoxManage modifyvm "VM name" --natdnshostresolver1 on</screen>
      Note that this setting is similar to the DNS proxy mode, however whereas
      the proxy mode just forwards DNS requests to the appropriate servers,
      the resolver mode will interpret the DNS requests and use the host's DNS
      API to query the information and return it to the guest.</para>

        <sect3 id="nat_host_resolver_name_intercepting">
          <title>User-defined host name resolving</title>
          <para>In some cases it might be useful to intercept the name resolving mechanism,
            providing a user-defined IP address on a particular DNS request. The intercepting
            mechanism allows the user to map not only a single host but domains and even more
            complex naming conventions if required.</para>
            <para>
              The following command sets a rule for mapping a name to a specified IP:</para>
            <screen>VBoxManage setextradata "VM name" \
      "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
      &lt;unique rule name of interception rule&gt;/HostIP" &lt;IPv4&gt;
VBoxManage setextradata "VM name" \
      "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
      &lt;unique rule name&gt;/HostName" &lt;name of host&gt;</screen>
    <para>The following command sets a rule for mapping a pattern name to a specified IP:</para>
            <screen>VBoxManage setextradata "VM name" \
      "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
      &lt;unique rule name&gt;/HostIP" &lt;IPv4&gt;
VBoxManage setextradata "VM name" \
      "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
      &lt;unique rule name&gt;/HostNamePattern" &lt;hostpattern&gt;</screen>
    <para>The host pattern may include <computeroutput>"|", "?" and "*"</computeroutput>.</para>
    <para>This example demonstrates how to instruct the host-resolver mechanism to resolve
      all domain and probably some mirrors of www.blocked-site.info site with IP 127.0.0.1:</para>
    <screen>VBoxManage setextradata "VM name" \
      "VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
      all_blocked_site/HostIP" 127.0.0.1
VBoxManage setextradata "VM name" \
      "VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
      all_blocked_site/HostNamePattern" "*.blocked-site.*|*.fb.org"</screen>

    <para>The host resolver mechanism should be enabled to use user-defined
      mapping rules, otherwise they don't have any effect.</para>
        </sect3>
    </sect2>

    <sect2 id="nat-adv-alias">
      <title>Configuring aliasing of the NAT engine</title>

      <para>By default, the NAT core uses aliasing and uses random ports when
      generating an alias for a connection. This works well for the most
      protocols like SSH, FTP and so on. Though some protocols might need a
      more transparent behavior or may depend on the real port number the
      packet was sent from. It is possible to change the NAT mode via the
      VBoxManage frontend with the following commands: <screen>VBoxManage modifyvm "VM name" --nataliasmode1 proxyonly</screen>
      and <screen>VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</screen>
      The first example disables aliasing and switches NAT into transparent
      mode, the second example enforces preserving of port values. These modes
      can be combined if necessary.</para>
    </sect2>
  </sect1>

  <sect1 id="changedmi">
    <title>Configuring the BIOS DMI information</title>

    <para>The DMI data VirtualBox provides to guests can be changed for a
    specific VM. Use the following commands to configure the DMI BIOS
    information. In case your VM is configured to use EFI firmware you need to
    replace <code>pcbios</code> by <code>efi</code> in the keys.</para>

    <glosslist>
      <glossentry>
        <glossterm>DMI BIOS information</glossterm>
        <glossdef>
          <para>(type 0)</para>
          <screen>VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor"        "BIOS Vendor"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion"       "BIOS Version"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate"   "BIOS Release Date"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor"  1
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor"  2
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4</screen>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>DMI system information</glossterm>
        <glossdef>
          <para>(type 1)</para>
          <screen>VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor"      "System Vendor"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct"     "System Product"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion"     "System Version"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial"      "System Serial"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU"         "System SKU"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily"      "System Family"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid"
                                               "9852bf98-b83c-49db-a8de-182c42c7226b"</screen>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>DMI board information</glossterm>
        <glossdef>
          <para>(type 2)</para>
          <screen>VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVendor"       "Board Vendor"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardProduct"      "Board Product"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVersion"      "Board Version"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardSerial"       "Board Serial"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardAssetTag"     "Board Tag"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardLocInChass"   "Board Location"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiBoardBoardType"    10</screen>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>DMI system enclosure or chassis</glossterm>
        <glossdef>
          <para>(type 3)</para>
          <screen>VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVendor"     "Chassis Vendor"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiChassisType"       3
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVersion"    "Chassis Version"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiChassisSerial"     "Chassis Serial"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiChassisAssetTag"   "Chassis Tag"</screen>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>DMI processor information</glossterm>
        <glossdef>
          <para>(type 4)</para>
          <screen>VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiProcManufacturer"  "GenuineIntel"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiProcVersion"       "Pentium(R) III"</screen>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>DMI OEM strings</glossterm>
        <glossdef>
          <para>(type 11)</para>
          <screen>VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxVer"        "vboxVer_1.2.3"
VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxRev"        "vboxRev_12345"</screen>
        </glossdef>
      </glossentry>
    </glosslist>

    <para>If a DMI string is not set, the default value of VirtualBox is used.
    To set an empty string use
    <computeroutput>"&lt;EMPTY&gt;"</computeroutput>.</para>

    <para>Note that in the above list, all quoted parameters (DmiBIOSVendor,
    DmiBIOSVersion but not DmiBIOSReleaseMajor) are expected to be strings. If
    such a string is a valid number, the parameter is treated as number and
    the VM will most probably refuse to start with an
    <computeroutput>VERR_CFGM_NOT_STRING</computeroutput> error. In that case,
    use <computeroutput>"string:&lt;value&gt;"</computeroutput>, for instance
    <screen>VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial"      "string:1234"</screen></para>

    <para>Changing this information can be necessary to provide the DMI
    information of the host to the guest to prevent Windows from asking for a
    new product key. On Linux hosts the DMI BIOS information can be obtained
    with <screen>dmidecode -t0</screen>and the DMI system information can be
    obtained with <screen>dmidecode -t1</screen></para>
  </sect1>

  <sect1 id="changeacpicust">
    <title>Configuring the custom ACPI table</title>

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

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

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

  <sect1>
    <title>Fine-tuning timers and time synchronization</title>

    <sect2 id="changetscmode">
      <title>Configuring the guest time stamp counter (TSC) to reflect guest
      execution</title>

      <para>By default, VirtualBox keeps all sources of time visible to the
      guest synchronized to a single time source, the monotonic host time.
      This reflects the assumptions of many guest operating systems, which
      expect all time sources to reflect "wall clock" time. In special
      circumstances it may be useful however to make the TSC (time stamp
      counter) in the guest reflect the time actually spent executing the
      guest.</para>

      <para>This special TSC handling mode can be enabled on a per-VM basis,
      and for best results must be used only in combination with hardware
      virtualization. To enable this mode use the following command:</para>

      <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution" 1</screen>

      <para>To revert to the default TSC handling mode use:</para>

      <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution"</screen>

      <para>Note that if you use the special TSC handling mode with a guest
      operating system which is very strict about the consistency of time
      sources you may get a warning or error message about the timing
      inconsistency. It may also cause clocks to become unreliable with some
      guest operating systems depending on how they use the TSC.</para>
    </sect2>

    <sect2 id="warpguest">
      <title>Accelerate or slow down the guest clock</title>

      <para>For certain purposes it can be useful to accelerate or to slow
      down the (virtual) guest clock. This can be achieved as follows:</para>

      <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 200</screen>

      <para>The above example will double the speed of the guest clock
      while</para>

      <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 50</screen>

      <para>will halve the speed of the guest clock. Note that changing the
      rate of the virtual clock can confuse the guest and can even lead to
      abnormal guest behavior. For instance, a higher clock rate means shorter
      timeouts for virtual devices with the result that a slightly increased
      response time of a virtual device due to an increased host load can
      cause guest failures. Note further that any time synchronization
      mechanism will frequently try to resynchronize the guest clock with the
      reference clock (which is the host clock if the VirtualBox Guest
      Additions are active). Therefore any time synchronization should be
      disabled if the rate of the guest clock is changed as described above
      (see <xref linkend="changetimesync" />).</para>
    </sect2>

    <sect2 id="changetimesync">
      <title>Tuning the Guest Additions time synchronization
      parameters</title>

      <para>The VirtualBox Guest Additions ensure that the guest's system time
      is synchronized with the host time. There are several parameters which
      can be tuned. The parameters can be set for a specific VM using the
      following command:</para>

      <screen>VBoxManage guestproperty set "VM name" "/VirtualBox/GuestAdd/VBoxService/PARAMETER" VALUE</screen>

      <para>where <computeroutput>PARAMETER</computeroutput> is one of the
      following:</para>

      <glosslist>
        <glossentry>
          <glossterm><computeroutput>--timesync-interval</computeroutput></glossterm>
          <glossdef>
            <para>Specifies the interval at which to synchronize the time
            with the host. The default is 10000 ms (10 seconds).</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>--timesync-min-adjust</computeroutput></glossterm>
          <glossdef>
            <para>The minimum absolute drift value measured in milliseconds
            to make adjustments for. The default is 1000 ms on OS/2 and 100
            ms elsewhere.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>--timesync-latency-factor</computeroutput></glossterm>
          <glossdef>
            <para>The factor to multiply the time query latency with to
            calculate the dynamic minimum adjust time. The default is 8
            times, that means in detail: Measure the time it takes to
            determine the host time (the guest has to contact the VM host
            service which may take some time), multiply this value by 8 and
            do an adjustment only if the time difference between host and
            guest is bigger than this value. Don't do any time adjustment
            otherwise.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>--timesync-max-latency</computeroutput></glossterm>
          <glossdef>
            <para>The max host timer query latency to accept. The default is
            250 ms.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>--timesync-set-threshold</computeroutput></glossterm>
          <glossdef>
            <para>The absolute drift threshold, given as milliseconds where
            to start setting the time instead of trying to smoothly adjust
            it. The default is 20 minutes.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>--timesync-set-start</computeroutput></glossterm>
          <glossdef>
            <para>Set the time when starting the time sync service.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>--timesync-set-on-restore
          0|1</computeroutput></glossterm>
          <glossdef>
            <para>Set the time after the VM was restored from a saved state
            when passing 1 as parameter (default). Disable by passing 0. In
            the latter case, the time will be adjusted smoothly which can
            take a long time.</para>
          </glossdef>
        </glossentry>
      </glosslist>

      <para>All these parameters can be specified as command line parameters
      to VBoxService as well.</para>
    </sect2>

    <sect2 id="disabletimesync">

      <title>Disabling the Guest Additions time synchronization</title>

      <para>Once installed and started, the VirtualBox Guest Additions will
        try to synchronize the guest time with the host time. This can be
        prevented by forbidding the guest service from reading the host
        clock:</para>

      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</screen>
    </sect2>
  </sect1>

  <sect1 id="vboxbowsolaris11">
    <title>Installing the alternate bridged networking driver on Solaris 11
    hosts</title>

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

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

    <screen>touch /etc/vboxinst_vboxflt</screen>

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

    <screen>touch /etc/vboxinst_vboxbow</screen>

    <para>To check which driver is currently being used by VirtualBox,
    execute:</para>

    <screen>modinfo | grep vbox</screen>

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

  <sect1 id="vboxbowvnictemplates">
    <title>VirtualBox VNIC templates for VLANs on Solaris 11 hosts</title>

    <para>VirtualBox supports VNIC (Virtual Network Interface) templates for
    configuring VMs over VLANs.<footnote>
        <para>Support for Crossbow based bridged networking was introduced
        with VirtualBox 4.1 and requires Solaris 11 build 159 or above.</para>
      </footnote> A VirtualBox VNIC template is a VNIC whose name starts with
    "vboxvnic_template" (case-sensitive).</para>

    <para>On Solaris 11 hosts<footnote><para>When Crossbow based bridged
    networking is used.</para></footnote>, a VNIC template may be used to
    specify the VLAN ID to use while bridging over a network link.</para>

    <para>Here is an example of how to use a VNIC template to configure a VM
    over a VLAN. Create a VirtualBox VNIC template, by executing as root:</para>

    <screen>dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0</screen>

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

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

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

    <para>Once the VNIC template is created, any VMs that need to be on VLAN
    23 over the interface "nge0" can be configured to bridge using this VNIC
    template.</para>

    <para>VNIC templates makes managing VMs on VLANs simpler and efficient.
    The VLAN details are not stored as part of every VM's configuration but
    rather inherited from the VNIC template while starting the VM. The VNIC
    template itself can be modified anytime using <computeroutput>dladm</computeroutput>.</para>

    <para>VNIC templates can be created with additional properties such as
    bandwidth limits, CPU fanout etc. Refer to your Solaris network
    documentation on how to accomplish this. These additional properties,
    if any, are also applied to VMs which bridge using the VNIC template.</para>
  </sect1>

  <sect1 id="addhostonlysolaris">
    <title>Configuring multiple host-only network interfaces on Solaris
    hosts</title>

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

    <para>Begin by stopping all running VMs. Then, unplumb the existing
    "vboxnet0" interface by execute the following command as root:</para>

    <screen>ifconfig vboxnet0 unplumb</screen>

    <para>If you have several vboxnet interfaces, you will need to unplumb
    all of them. Once all vboxnet interfaces are unplumbed, remove the
    driver by executing the following command as root:</para>

    <screen>rem_drv vboxnet</screen>

    <para>Edit the file <computeroutput>/platform/i86pc/kernel/drv/vboxnet.conf</computeroutput>
    and add a line for the new interface we want to add as shown below:</para>

    <screen>name="vboxnet" parent="pseudo" instance=1;
name="vboxnet" parent="pseudo" instance=2;</screen>

    <para>Add as many of these lines as required with each line having a
    unique instance number.</para>

    <para>Next, reload the vboxnet driver by executing the following command
    as root:</para>

    <screen>add_drv vboxnet</screen>

    <para>On Solaris 11.1 and newer hosts you may want to rename the default
    vanity interface name. To check what name has been assigned, execute:</para>

    <screen>dladm show-phys
LINK              MEDIA                STATE      SPEED  DUPLEX    DEVICE
net0              Ethernet             up         100    full      e1000g0
net2              Ethernet             up         1000   full      vboxnet1
net1              Ethernet             up         1000   full      vboxnet0</screen>

    <para>In the above example, we can rename "net2" to "vboxnet1" before
    proceeding to plumb the interface. This can be done by executing as root:</para>

    <screen>dladm rename-link net2 vboxnet1</screen>

    <para>Now plumb all the interfaces using
    <computeroutput>ifconfig vboxnetX plumb</computeroutput> (where 'X' would
    be 1 in this case). Once the interface is plumbed, it may be configured
    like any other network interface. Refer to the
    <computeroutput>ifconfig</computeroutput> documentation for further details.</para>

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

  <sect1 id="solariscodedumper">
    <title>Configuring the VirtualBox CoreDumper on Solaris hosts</title>

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

    <para>The VirtualBox CoreDumper can be enabled using the following
    command:</para>

    <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpEnabled 1</screen></para>

    <para>You can specify which directory to use for core dumps with this
    command:</para>

    <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir &lt;path-to-directory&gt;</screen>Make
    sure the directory you specify is on a volume with sufficient free space
    and that the VirtualBox process has sufficient permissions to write files
    to this directory. If you skip this command and don't specify any core
    dump directory, the current directory of the VirtualBox executable will be
    used (which would most likely fail when writing cores as they are
    protected with root permissions). It is recommended you explicitly set a
    core dump directory.</para>

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

    <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpReplaceSystemDump 1
VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpLive 1</screen>At
    least one of the above two commands will have to be provided if you have
    enabled the VirtualBox CoreDumper.</para>

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

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

    <para><screen>kill -s SIGUSR2 &lt;VM-process-id&gt;</screen></para>

    <para>Core files produced by the VirtualBox CoreDumper are of the form
    <computeroutput>core.vb.&lt;ProcessName&gt;.&lt;ProcessID&gt;</computeroutput>,
    for example <computeroutput>core.vb.VBoxHeadless.11321</computeroutput>.</para>
  </sect1>

  <sect1 id="vboxandsolzvmm">
    <title>VirtualBox and Solaris kernel zones</title>

    <para>Solaris kernel zones on x86-based systems make use of hardware-assisted
    virtualization features like VirtualBox does. However, for kernel zones and
    VirtualBox to share this hardware resource, they need to co-operate.</para>

    <para>By default, due to performance reasons, VirtualBox acquires the
    hardware-assisted virtualization resource (VT-x/AMD-V) globally on the
    host machine and uses it until the last VirtualBox VM that requires it is
    powered off. This prevents other software from using VT-x/AMD-V during the
    time VirtualBox has taken control of it.</para>

    <para>VirtualBox can be instructed to relinquish use of hardware-assisted
    virtualization features when not executing guest code, thereby allowing
    kernel zones to make use of them. To do this, shutdown all VirtualBox VMs
    and execute the following command:</para>

    <screen>VBoxManage setproperty hwvirtexclusive off</screen>

    <para>This command needs to be executed only once as the setting is stored
    as part of the global VirtualBox settings which will continue to persist
    across host-reboots and VirtualBox upgrades.</para>
  </sect1>

  <sect1 id="guitweaks">
    <title>Locking down the VirtualBox GUI</title>

    <sect2>
      <title>Customizing the VM manager</title>

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

      <para><screen>VBoxManage setextradata global GUI/Customizations OPTION[,OPTION...]</screen></para>

      <para>where <computeroutput>OPTION</computeroutput> is one of the
      following keywords:<glosslist>
          <glossentry>
            <glossterm><computeroutput>noSelector</computeroutput></glossterm>
            <glossdef>
              <para>Don't allow to start the VirtualBox manager. Trying to do so
              will show a window containing a proper error message.</para>
            </glossdef>
          </glossentry>

          <glossentry>
            <glossterm><computeroutput>noMenuBar</computeroutput></glossterm>
            <glossdef>
              <para>VM windows will not contain a menu bar.</para>
            </glossdef>
          </glossentry>

          <glossentry>
            <glossterm><computeroutput>noStatusBar</computeroutput></glossterm>
            <glossdef>
              <para>VM windows will not contain a status bar.</para>
            </glossdef>
          </glossentry>
        </glosslist></para>

      <para>To disable any of these VM manager customizations do
        <screen>VBoxManage setextradata global GUI/Customizations</screen></para>

    </sect2>
    <sect2>

      <title>VM selector customization</title>
      <para>The following per-machine VM extradata settings can be used to change the
        behavior of the VM selector window in respect of certain VMs:</para>
      <screen>VBoxManage setextradata "VM name" SETTING true</screen>
      <para>where <computeroutput>SETTING</computeroutput> can be:</para>
      <glosslist>
        <glossentry>
          <glossterm><computeroutput>GUI/HideDetails</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the VM configuration of a certain VM. The details
              window will remain just empty if this VM is selected.</para>
          </glossdef>
        </glossentry>
        <glossentry>
         <glossterm><computeroutput>GUI/PreventReconfiguration</computeroutput></glossterm>
          <glossdef>
            <para>Don't allow the user to open the settings dialog for a certain VM.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>GUI/PreventSnapshotOperations</computeroutput></glossterm>
          <glossdef>
            <para>Prevent snapshot operations for a VM from the GUI, either at runtime or when
              the VM is powered off.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>GUI/HideFromManager</computeroutput></glossterm>
          <glossdef>
            <para>Hide a certain VM in the VM selector window.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>GUI/PreventApplicationUpdate</computeroutput></glossterm>
          <glossdef>
            <para>Disable the automatic update check and hide the corresponding menu item.</para>
          </glossdef>
        </glossentry>
      </glosslist>
      <para>Please note that these settings wouldn't prevent the user from
        reconfiguring the VM by <computeroutput>VBoxManage modifyvm</computeroutput>.</para>

    </sect2>

    <sect2>
      <title>Configure VM selector menu entries</title>
      <para>You can disable (i.e. black-list) certain entries in the global settings
        page of the VM selector:</para>
      <screen>VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages OPTION[,OPTION...]</screen>
      <para>where <computeroutput>OPTION</computeroutput> is one of the
        following keywords:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>General</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>General</emphasis> settings pane.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Input</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Input</emphasis> settings pane.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Update</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Update</emphasis> settings pane.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Language</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Language</emphasis> settings pane.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Display</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Display</emphasis> settings pane.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Network</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Network</emphasis> settings pane.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Extensions</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Extensions</emphasis> settings pane.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Proxy</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Proxy</emphasis> settings pane.</para>
          </glossdef>
        </glossentry>

      </glosslist>

      <para>This is a global setting. Any combination of the above is allowed.
         To restore the default behavior, use</para>
      <screen>VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages</screen>

    </sect2>

    <sect2>
      <title>Configure VM window menu entries</title>
      <para>You can disable (i.e. black-list) certain menu actions in the VM window:</para>
      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus OPTION[,OPTION...]</screen>

      <para>where <computeroutput>OPTION</computeroutput> is one of the
        following keywords:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>All</computeroutput></glossterm>
          <glossdef>
            <para>Don't show any menu in the VM window.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Machine</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Machine</emphasis> menu in the VM window.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>View</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>View</emphasis> menu in the VM window.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Devices</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Devices</emphasis> menu in the VM window.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Help</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Help</emphasis> menu in the VM window.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Debug</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Debug</emphasis> menu in the VM window. The debug
              menu is only visible if the GUI was started with special command line parameters
              or environment variable settings.</para>
          </glossdef>
        </glossentry>

      </glosslist>

      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
      the default behavior, use</para>
      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus</screen>

      <para>You can also disable (i.e. blacklist) certain menu actions of certain
        menus. Use the following command to disable certain actions of the
        <emphasis>Application</emphasis> menu (only available on Mac OS X hosts):</para>
      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen>

      <para>where <computeroutput>OPTION</computeroutput> is one of the
        following keywords:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>All</computeroutput></glossterm>
          <glossdef>
            <para>Don't show any menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>About</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>About</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
      </glosslist>

      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
      the default behavior, use</para>
      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus</screen>

      <para>Use the following command to disable certain actions of the <emphasis>Machine</emphasis>
        menu:</para>

      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen>

      <para>where <computeroutput>OPTION</computeroutput> is one of the
        following keywords:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>All</computeroutput></glossterm>
          <glossdef>
            <para>Don't show any menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>SettingsDialog</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Settings</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>TakeSnapshot</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Take Snapshot</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>TakeScreenshot</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Take Screenshot</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>InformationDialog</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Session Information</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>MouseIntegration</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Disable Mouse Integration</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>TypeCAD</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Insert Ctrl+Alt+Del</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>TypeCABS</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Insert Ctrl+Alt+Backspace</emphasis> menu item in
              this menu (available on X11 hosts only).</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Pause</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Pause</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Reset</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Reset</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>SaveState</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Save the machine state</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Shutdown</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>ACPI Shutdown</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Power Off the machine</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
      </glosslist>

      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
      the default behavior, use</para>
      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions</screen>

      <para>Use the following command to disable certain actions of the <emphasis>View</emphasis>
        menu:</para>

      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeViewMenuActions OPTION[,OPTION...]</screen>

      <para>where <computeroutput>OPTION</computeroutput> is one of the
        following keywords:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>All</computeroutput></glossterm>
          <glossdef>
            <para>Don't show any menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Fullscreen</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Switch to Fullscreen</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Seamless</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Switch to Seamless Mode</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Scale</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Switch to Scaled Mode</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>GuestAutoresize</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Auto-resize Guest Display</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>AdjustWindow</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Adjust Window Size</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Multiscreen</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Multiscreen</emphasis> menu item in this menu (only visible in full screen / seamless mode).</para>
          </glossdef>
        </glossentry>
      </glosslist>

      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
      the default behavior, use</para>
      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeViewMenuActions</screen>

      <para>Use the following command to disable certain actions of the <emphasis>View</emphasis>
        menu:</para>

      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDevicesMenuActions OPTION[,OPTION...]</screen>

      <para>where <computeroutput>OPTION</computeroutput> is one of the
        following keywords to disable actions in the <emphasis>Devices</emphasis> menu:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>All</computeroutput></glossterm>
          <glossdef>
            <para>Don't show any menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>OpticalDevices</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>CD/DVD Devices</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>FloppyDevices</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>FLoppy Devices</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>USBDevices</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>USB Devices</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>SharedClipboard</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Shared Clipboard</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>DragAndDrop</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Drag and Drop</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>NetworkSettings</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Network Settings...</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>SharedFoldersSettings</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Shared Folders Settings...</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>VRDEServer</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Remove Display</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>InstallGuestTools</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Insert Guest Additions CD imnage...</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
      </glosslist>

      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
      the default behavior, use</para>
      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDevicesMenuActions</screen>

      <para>Use the following command to disable certain actions of the <emphasis>View</emphasis>
        menu:</para>

      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDebuggerMenuActions OPTION[,OPTION...]</screen>

      <para>where <computeroutput>OPTION</computeroutput> is one of the
        following keywords to disable actions in the <emphasis>Debug</emphasis> menu (normally completely disabled):</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>All</computeroutput></glossterm>
          <glossdef>
            <para>Don't show any menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Statistics</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Statistics...</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>CommandLine</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Command Line...</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Logging</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Logging...</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>LogDialog</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Show Log...</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
      </glosslist>

      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
      the default behavior, use</para>
      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDebuggerMenuActions</screen>

      <para>Use the following command to disable certain actions of the <emphasis>View</emphasis>
        menu:</para>

      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeHelpMenuActions OPTION[,OPTION...]</screen>

      <para>where <computeroutput>OPTION</computeroutput> is one of the
        following keywords to disable actions in the <emphasis>Help</emphasis> menu (normally completely disabled):</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>All</computeroutput></glossterm>
          <glossdef>
            <para>Don't show any menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Contents</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Contents...</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>WebSite</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>VirtualBox Web Site...</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>ResetWarnings</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Reset All Warnings</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>NetworkAccessManager</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Network Operations Manager</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>About</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>About</emphasis> menu item in this menu (only on non Mac OS X hosts).</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Contents</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Contents...</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Contents</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the <emphasis>Contents...</emphasis> menu item in this menu.</para>
          </glossdef>
        </glossentry>
      </glosslist>

      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
      the default behavior, use</para>
      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeHelpMenuActions</screen>

    </sect2>

    <sect2>

      <title>Configure VM window status bar entries</title>

      <para>You can disable (i.e. black-list) certain status bar items:</para>
      <screen>VBoxManage setextradata "VM name" GUI/RestrictedStatusBarIndicators OPTION[,OPTION...]</screen>

      <para>where <computeroutput>OPTION</computeroutput> is one of the
        following keywords:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>HardDisks</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the hard disk icon in the VM window status bar. By default
              the hard disk icon is only shown if the VM configuration contains one or
              more hard disks.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>OpticalDisks</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the CD icon in the VM window status bar. By default the
              CD icon is only shown if the VM configuration contains one or more CD
            drives.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>FloppyDisks</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the floppy icon in the VM window status bar. By default the
              floppy icon is only shown if the VM configuration contains one or more
              floppy drives.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Network</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the network icon in the VM window status bar. By default
              the network icon is only shown if the VM configuration contains one or more
            active network adapters.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>USB</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the USB icon in the status bar. </para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>SharedFolders</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the shared folders icon in the status bar.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>VideoCapture</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the video capture icon in the status bar.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Features</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the CPU features icon in the status bar.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Mouse</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the mouse icon in the status bar.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Keyboard</computeroutput></glossterm>
          <glossdef>
            <para>Don't show the keyboard icon in the status bar.</para>
          </glossdef>
        </glossentry>

      </glosslist>

      <para>This is a per-VM setting. Any combination of the above is allowed. If all options
        are specified, no icons are displayed in the status bar of the VM window. To restore
        the default behavior, use</para>

      <screen>VBoxManage setextradata "VM name" GUI/RestrictedStatusBarIndicators</screen>

    </sect2>

    <sect2>
      <title>Configure VM window visual modes</title>

      <para>You can disable (i.e. black-list) certain VM visual modes:</para>
      <screen>VBoxManage setextradata "VM name" GUI/RestrictedVisualStates OPTION[,OPTION...]</screen>

      <para>where <computeroutput>OPTION</computeroutput> is one of the
        following keywords:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>Fullscreen</computeroutput></glossterm>
          <glossdef>
            <para>Don't allow to switch the VM into full screen mode.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Seamless</computeroutput></glossterm>
          <glossdef>
            <para>Don't allow to switch the VM into seamless mode.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Scale</computeroutput></glossterm>
          <glossdef>
            <para>Don't allow to switch the VM into scale mode.</para>
          </glossdef>
        </glossentry>

      </glosslist>

      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
        the default behavior, use</para>

      <screen>VBoxManage setextradata "VM name" GUI/RestrictedVisualStates</screen>

    </sect2>

    <sect2>
      <title>Host Key customization</title>

      <para>To disable all host key combinations, open the preferences and
        change the host key to <emphasis>None</emphasis>. This might be useful
        when using VirtualBox in a kiosk mode.</para>

      <para>To redefine or disable certain host key actions, use the following command:</para>

      <screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...."</screen>

      <para>The following list shows the possible host key actions together with their default
        host key shortcut. Setting an action to <emphasis>None</emphasis> will disable
        that host key action.</para>
      <table>
        <title>Host Key customization</title>
        <tgroup cols="3">
          <thead>
            <row>
              <entry><emphasis role="bold">Action</emphasis></entry>
              <entry><emphasis role="bold">Default Key</emphasis></entry>
              <entry><emphasis role="bold">Action</emphasis></entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><computeroutput>TakeSnapshot</computeroutput></entry>
              <entry>T</entry>
              <entry>take a snapshot</entry>
            </row>
            <row>
              <entry><computeroutput>TakeScreenshot</computeroutput></entry>
              <entry>E</entry>
              <entry>take a screenshot</entry>
            </row>
            <row>
              <entry><computeroutput>MouseIntegration</computeroutput></entry>
              <entry>I</entry>
              <entry>toggle mouse integration</entry>
            </row>
            <row>
              <entry><computeroutput>TypeCAD</computeroutput></entry>
              <entry>Del</entry>
              <entry>inject Ctrl+Alt+Del</entry>
            </row>
            <row>
              <entry><computeroutput>TypeCABS</computeroutput></entry>
              <entry>Backspace</entry>
              <entry>inject Ctrl+Alt+Backspace</entry>
            </row>
            <row>
              <entry><computeroutput>Pause</computeroutput></entry>
              <entry>P</entry>
              <entry>Pause the VM</entry>
            </row>
            <row>
              <entry><computeroutput>Reset</computeroutput></entry>
              <entry>R</entry>
              <entry>(hard) reset the guest</entry>
            </row>
            <row>
              <entry><computeroutput>SaveState</computeroutput></entry>
              <entry></entry>
              <entry>save the VM state and terminate the VM</entry>
            </row>
            <row>
              <entry><computeroutput>Shutdown</computeroutput></entry>
              <entry>H</entry>
              <entry>press the (virtual) ACPI power button</entry>
            </row>
            <row>
              <entry><computeroutput>PowerOff</computeroutput></entry>
              <entry></entry>
              <entry>power the VM off (without saving the state!)</entry>
            </row>
            <row>
              <entry><computeroutput>Close</computeroutput></entry>
              <entry>Q</entry>
              <entry>show the VM close dialog</entry>
            </row>
            <row>
              <entry><computeroutput>FullscreenMode</computeroutput></entry>
              <entry>F</entry>
              <entry>switch the VM into full screen</entry>
            </row>
            <row>
              <entry><computeroutput>SeamlessMode</computeroutput></entry>
              <entry>L</entry>
              <entry>switch the VM into seamless mode</entry>
            </row>
            <row>
              <entry><computeroutput>ScaleMode</computeroutput></entry>
              <entry>C</entry>
              <entry>switch the VM into scale mode</entry>
            </row>
            <row>
              <entry><computeroutput>GuestAutoResize</computeroutput></entry>
              <entry>G</entry>
              <entry>automatically resize the guest window</entry>
            </row>
            <row>
              <entry><computeroutput>WindowAdjust</computeroutput></entry>
              <entry>A</entry>
              <entry>immediately resize the guest window</entry>
            </row>
            <row>
              <entry><computeroutput>PopupMenu</computeroutput></entry>
              <entry>Home</entry>
              <entry>show popup menu in full screen / seaml. mode</entry>
            </row>
            <row>
              <entry><computeroutput>SettingsDialog</computeroutput></entry>
              <entry>S</entry>
              <entry>open the VM settings dialog</entry>
            </row>
            <row>
              <entry><computeroutput>InformationDialog</computeroutput></entry>
              <entry>N</entry>
              <entry>show the VM information window</entry>
            </row>
            <row>
              <entry><computeroutput>NetworkAdaptersDialog</computeroutput></entry>
              <entry></entry>
              <entry>show the VM network adapters dialog</entry>
            </row>
            <row>
              <entry><computeroutput>SharedFoldersDialog</computeroutput></entry>
              <entry></entry>
              <entry>show the VM shared folders dialog</entry>
            </row>
            <row>
              <entry><computeroutput>InstallGuestAdditions</computeroutput></entry>
              <entry>D</entry>
              <entry>mount the ISO containing the Guest Additions</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para>To disable the full screen mode as well as the seamless mode, use the following command:
        <screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</screen>
      </para>

    </sect2>

    <sect2>
      <title>Action when terminating the VM</title>

      <para>You can disallow (i.e. black-list) certain actions when terminating a VM.
        To disallow specific actions, type:</para>

      <para><screen>VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...]</screen></para>

      <para>where <computeroutput>OPTION</computeroutput> is one of the
        following keywords:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>SaveState</computeroutput></glossterm>
          <glossdef>
            <para>Don't allow the user to save the VM state when terminating
            the VM.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Shutdown</computeroutput></glossterm>
          <glossdef>
            <para>Don't allow the user to shutdown the VM by sending the ACPI
            power-off event to the guest.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
          <glossdef>
            <para>Don't allow the user to power off the VM.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>PowerOffRestoringSnapshot</computeroutput></glossterm>
          <glossdef>
            <para>Don't allow the user to return to the last snapshot when
              powering off the VM.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Detach</computeroutput></glossterm>
          <glossdef>
            <para>Don't allow the user to detach from the VM process if the
              VM was started in separate mode.</para>
          </glossdef>
        </glossentry>

      </glosslist>

      <para>This is a per-VM setting. Any combination of the above is allowed. If all
        options are specified, the VM cannot be shut down at all.</para>
    </sect2>

    <sect2>
      <title>Default action when terminating the VM</title>

      <para>You can define a specific action for terminating a VM. In contrast to
        the setting decribed in the previous section, this setting allows only
        one action when the user terminates the VM. No exit menu is shown.</para>

      <para><screen>VBoxManage setextradata "VM name" GUI/DefaultCloseAction ACTION</screen></para>

      <para>where <computeroutput>ACTION</computeroutput> is one of the
        following keywords:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>SaveState</computeroutput></glossterm>
          <glossdef>
            <para>Save the VM state before terminating the VM process.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Shutdown</computeroutput></glossterm>
          <glossdef>
            <para>The VM is shut down by sending the ACPI power-off event to the guest.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
          <glossdef>
            <para>The VM is powered off.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>PowerOffRestoringSnapshot</computeroutput></glossterm>
          <glossdef>
            <para>The VM is powered off and the saved state returns to the last snapshot.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Detach</computeroutput></glossterm>
          <glossdef>
            <para>Terminate the frontend but leave the VM process running.</para>
          </glossdef>
        </glossentry>

      </glosslist>

      <para>This is a per-VM setting. Any combination of the above is allowed. If all
        options are specified, the VM cannot be shut down at all.</para>
    </sect2>

    <sect2>
      <title>Action for handling a Guru Meditation</title>

      <para>A VM runs into a Guru Meditation if there is a problem which
        cannot be fixed by other means than terminating the process. The
        default is to show a message window which instructs the user to
        open a bug report.</para>
      <para>This behavior can be configured:</para>

      <para><screen>VBoxManage setextradata "VM name" GUI/GuruMeditationHandler MODE</screen></para>

      <para>where <computeroutput>MODE</computeroutput> is one of the
        following keywords:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>Default</computeroutput></glossterm>
          <glossdef>
            <para>A message window is shown. After the user confirmed, the
              VM is terminated.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
          <glossdef>
            <para>The VM is immediately powered-off without showing any message
              window. The VM logfile will show information about what happened.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm><computeroutput>Ignore</computeroutput></glossterm>
          <glossdef>
            <para>The VM is left in stuck mode. Execution is stopped but no
            message window is shown. The VM has to be powered off manually.</para>
          </glossdef>
        </glossentry>
      </glosslist>

      <para>This is a per-VM setting.</para>
    </sect2>

    <sect2>
      <title>Configuring automatic mouse capturing</title>

      <para>
        By default, the mouse is captured if the user clicks on the guest window
        and the guest expects relative mouse coordinates at this time. This
        happens if the pointing device is configured as PS/2 mouse and the guest did
        not (yet) start the VirtualBox Guest Additions (for instance, the guest is
        booting or no Guest Additions installed at all) or if the pointing device
        is configured as USB tablet but the guest has no USB driver loaded yet.
        Once the Guest Additions become active or the USB guest driver is started,
        the mouse capture is automatically released.
      </para>
      <para>
        The default behavior is sometimes not desired. Therefore it can be configured:
      </para>
      <para><screen>VBoxManage setextradata "VM name" GUI/MouseCapturePolicy MODE</screen></para>

      <para>where <computeroutput>MODE</computeroutput> is one of the
        following keywords:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>Default</computeroutput></glossterm>
          <glossdef>
            <para>The default behavior as described above.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>HostComboOnly</computeroutput></glossterm>
          <glossdef>
            <para>The mouse is only captured if the Host Key is toggled.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Disabled</computeroutput></glossterm>
          <glossdef>
            <para>The mouse is never captured, also not by toggling the Host Key</para>
          </glossdef>
        </glossentry>
      </glosslist>

      <para>This is a per-VM setting.</para>

    </sect2>

    <sect2 id="mouse-capture">
      <title>Configuring automatic mouse capturing</title>

      <para>
        By default, the mouse is captured if the user clicks on the guest window
        and the guest expects relative mouse coordinates at this time. This
        happens if the pointing device is configured as PS/2 mouse and the guest did
        not (yet) start the VirtualBox Guest Additions (for instance, the guest is
        booting or no Guest Additions installed at all) or if the pointing device
        is configured as USB tablet but the guest has no USB driver loaded yet.
        Once the Guest Additions become active or the USB guest driver is started,
        the mouse capture is automatically released.
      </para>
      <para>
        The default behavior is sometimes not desired. Therefore it can be configured:
      </para>
      <para><screen>VBoxManage setextradata "VM name" GUI/MouseCapturePolicy MODE</screen></para>

      <para>where <computeroutput>MODE</computeroutput> is one of the
        following keywords:</para><glosslist>
        <glossentry>
          <glossterm><computeroutput>Default</computeroutput></glossterm>
          <glossdef>
            <para>The default behavior as described above.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>HostComboOnly</computeroutput></glossterm>
          <glossdef>
            <para>The mouse is only captured if the Host Key is toggled.</para>
          </glossdef>
        </glossentry>
        <glossentry>
          <glossterm><computeroutput>Disabled</computeroutput></glossterm>
          <glossdef>
            <para>The mouse is never captured, also not by toggling the Host Key</para>
          </glossdef>
        </glossentry>
      </glosslist>

      <para>This is a per-VM setting.</para>

    </sect2>

    <sect2 id="legacy-fullscreen-mode">
      <title>Requesting legacy full-screen mode</title>

      <para>
        As of version 4.3.16, VirtualBox uses special window manager facilities to switch
        a multi-screen machine to full-screen on a multi-monitor host system. However,
        not all window managers provide these facilities correctly, so VirtualBox can be
        told to use the old method of switching to full-screen mode instead using the command:
      </para>
      <para><screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode true</screen></para>

      <para>
        You can go back to the new method using the command:
      </para>
      <para><screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode</screen></para>

      <para>This is a global setting.</para>
    </sect2>
  </sect1>

  <sect1 id="vboxwebsrv-daemon">
    <title>Starting the VirtualBox web service automatically</title>

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

    <sect2 id="vboxwebsrv-linux">
      <title>Linux: starting the webservice via <computeroutput>init</computeroutput></title>

      <para>On Linux, the web service can be automatically started during
      host boot by adding appropriate parameters to the file
      <computeroutput>/etc/default/virtualbox</computeroutput>.
      There is one mandatory parameter, <computeroutput>VBOXWEB_USER</computeroutput>,
      which must be set to the user which will later start the VMs. The
      parameters in the table below all start with <computeroutput>VBOXWEB_</computeroutput>
      (<computeroutput>VBOXWEB_HOST</computeroutput>,
      <computeroutput>VBOXWEB_PORT</computeroutput> etc.):
      <table>
        <title>Web service configuration parameters</title>
        <tgroup cols="3">
          <thead>
            <row>
              <entry><emphasis role="bold">Parameter</emphasis></entry>
              <entry><emphasis role="bold">Description</emphasis></entry>
              <entry><emphasis role="bold">Default</emphasis></entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><computeroutput>USER</computeroutput></entry>
              <entry>The user as which the web service runs</entry>
              <entry></entry>
            </row>
            <row>
              <entry><computeroutput>HOST</computeroutput></entry>
              <entry>The host to bind the web service to</entry>
              <entry>localhost</entry>
            </row>
            <row>
              <entry><computeroutput>PORT</computeroutput></entry>
              <entry>The port to bind the web service to</entry>
              <entry>18083</entry>
            </row>
            <row>
              <entry><computeroutput>SSL_KEYFILE</computeroutput></entry>
              <entry>Server key and certificate file, PEM format</entry>
              <entry></entry>
            </row>
            <row>
              <entry><computeroutput>SSL_PASSWORDFILE</computeroutput></entry>
              <entry>File name for password to server key</entry>
              <entry></entry>
            </row>
            <row>
              <entry><computeroutput>SSL_CACERT</computeroutput></entry>
              <entry>CA certificate file, PEM format</entry>
              <entry></entry>
            </row>
            <row>
              <entry><computeroutput>SSL_CAPATH</computeroutput></entry>
              <entry>CA certificate path</entry>
              <entry></entry>
            </row>
            <row>
              <entry><computeroutput>SSL_DHFILE</computeroutput></entry>
              <entry>DH file name or DH key length in bits</entry>
              <entry></entry>
            </row>
            <row>
              <entry><computeroutput>SSL_RANDFILE</computeroutput></entry>
              <entry>File containing seed for random number generator</entry>
              <entry></entry>
            </row>
            <row>
              <entry><computeroutput>TIMEOUT</computeroutput></entry>
              <entry>Session timeout in seconds; 0 disables timeouts</entry>
              <entry>300</entry>
            </row>
            <row>
              <entry><computeroutput>CHECK_INTERVAL</computeroutput></entry>
              <entry>Frequency of timeout checks in seconds</entry>
              <entry>5</entry>
            </row>
            <row>
              <entry><computeroutput>THREADS</computeroutput></entry>
              <entry>Maximum number of worker threads to run in parallel</entry>
              <entry>100</entry>
            </row>
            <row>
              <entry><computeroutput>KEEPALIVE</computeroutput></entry>
              <entry>Maximum number of requests before a socket will be closed</entry>
              <entry>100</entry>
            </row>
            <row>
              <entry><computeroutput>ROTATE</computeroutput></entry>
              <entry>Number of log files; 0 disables log rotation</entry>
              <entry>10</entry>
            </row>
            <row>
              <entry><computeroutput>LOGSIZE</computeroutput></entry>
              <entry>Maximum size of a log file in bytes to trigger rotation</entry>
              <entry>1MB</entry>
            </row>
            <row>
              <entry><computeroutput>LOGINTERVAL</computeroutput></entry>
              <entry>Maximum time interval in seconds to trigger log rotation</entry>
              <entry>1 day</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      </para>

      <para>Setting the parameter <computeroutput>SSL_KEYFILE</computeroutput>
      enables the SSL/TLS support. Using encryption is strongly encouraged, as
      otherwise everything (including passwords) is transferred in clear
      text.</para>
    </sect2>

    <sect2 id="vboxwebsrv-solaris">
      <title>Solaris: starting the web service via SMF</title>

      <para>On Solaris hosts, the VirtualBox web service daemon is
      integrated into the SMF framework. You can change the parameters, but
      don't have to if the defaults below already match your needs:<screen>svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root</screen></para>

      <para>The table in the previous section showing the parameter names and
      defaults also applies to Solaris. The parameter names must be changed
      to lowercase and a prefix of <computeroutput>config/</computeroutput>
      has to be added, e.g. <computeroutput>config/user</computeroutput> or
      <computeroutput>config/ssl_keyfile</computeroutput>. If you made any
      change, don't forget to run the following command to put the changes into
      effect immediately:<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen></para>

      <para>If you forget the above command then the previous settings will
      be used when enabling the service. Check the current property settings
      with:<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen></para>

      <para>When everything is configured correctly you can start the
      VirtualBox web service with the following command:<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen></para>

      <para>For more information about SMF, please refer to the Solaris
      documentation.</para>
    </sect2>

    <sect2 id="vboxwebsrv-osx">
      <title>Mac OS X: starting the webservice via launchd</title>

      <para>On Mac OS X, launchd is used to start the VirtualBox webservice. An
      example configuration file can be found in
      <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>.
      It can be enabled by changing the
      <computeroutput>Disabled</computeroutput> key from
      <computeroutput>true</computeroutput> to
      <computeroutput>false</computeroutput>. To manually start the
      service use the following command: <screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
      For additional information on how launchd services could be
      configured see <literal><ulink
      url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html</ulink></literal>.</para>
    </sect2>
  </sect1>

  <sect1 id="vboxwatchdog">
    <title>VirtualBox Watchdog</title>
    <para>Starting with VirtualBox 4.2 the memory ballooning service formerly
    known as <computeroutput>VBoxBalloonCtrl</computeroutput> was renamed to
    VBoxWatchdog, which now incorporates several host services that are meant
    to be run in a server environment.</para>

    <para>These services are: <itemizedlist>
        <listitem>
            <para>Memory ballooning control, which automatically takes care of
            a VM's configured memory balloon (see <xref linkend="guestadd-balloon" />
            for an introduction to memory ballooning). This especially is useful
            for server environments where VMs may dynamically require more or
            less memory during runtime.</para>

            <para>The service periodically checks a VM's current memory balloon
            and its free guest RAM and automatically adjusts the current memory
            balloon by inflating or deflating it accordingly. This handling only
            applies to running VMs having recent Guest Additions installed.</para>
        </listitem>
        <listitem>
            <para>Host isolation detection, which provides a way to detect whether
            the host cannot reach the specific VirtualBox server instance anymore
            and take appropriate actions, such as shutting down, saving the
            current state or even powering down certain VMs.</para>
        </listitem>
    </itemizedlist></para>

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

    <sect2 id="vboxwatchdog-ballonctrl">
        <title>Memory ballooning control</title>
        <para>The memory ballooning control inflates and deflates the memory balloon
        of VMs based on the VMs free memory and the desired maximum balloon size.</para>

        <para>To set up the memory ballooning control the maximum ballooning size a
        VM can reach needs to be set. This can be specified via command line with
        <screen>--balloon-max &lt;Size in MB&gt;</screen>, on a per-VM basis extradata value with
        <screen>VBoxManage setextradata &lt;VM-Name&gt; VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
        or using a global extradata value with
        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
        <note><para>If no maximum ballooning size is specified by at least one of
            the parameters above, no ballooning will be performed at all.</para></note>
        </para>

        <para>Setting the ballooning increment in MB can be either done via
        command line with
        <screen>--balloon-inc &lt;Size in MB&gt;</screen> or using a global
        extradata value with
        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB &lt;Size in MB&gt;</screen>
        Default ballooning increment is 256 MB if not specified.</para>

        <para>Same goes with the ballooning decrement: Via command line with
        <screen>--balloon-dec &lt;Size in MB&gt;</screen> or using a global
        extradata value with
        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB &lt;Size in MB&gt;</screen>
        Default ballooning decrement is 128 MB if not specified.</para>

        <para>To define the lower limit in MB a balloon can be the command line with
        <screen>--balloon-lower-limit &lt;Size in MB&gt;</screen> can be used or using a global
        extradata value with
        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB &lt;Size in MB&gt;</screen>
        is available. Default lower limit is 128 if not specified.</para>
    </sect2>

    <sect2 id="vboxwatchdog-hostisln">
        <title>Host isolation detection</title>
        <para>To detect whether a host is being isolated, that is, the host cannot
        reach the VirtualBox server instance anymore, the host needs to set an
        alternating value to a global extradata value within a time period. If
        this value is not set within that time period a timeout occurred and the
        so-called host isolation response will be performed to the VMs handled.
        Which VMs are handled can be controlled by defining VM groups and assigning
        VMs to those groups. By default no groups are set, meaning that all VMs
        on the server will be handled when no host response is received within
        30 seconds.</para>

        <para>To set the groups handled by the host isolation detection via
        command line:
        <screen>--apimon-groups=&lt;string[,stringN]&gt;</screen> or using a global
        extradata value with
        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups &lt;string[,stringN]&gt;</screen>
        </para>

        <para>To set the host isolation timeout via command line:
        <screen>--apimon-isln-timeout=&lt;ms&gt;</screen> or using a global
        extradata value with
        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS &lt;ms&gt;</screen>
        </para>

        <para>To set the actual host isolation response via command line:
        <screen>--apimon-isln-response=&lt;cmd&gt;</screen> or using a global
        extradata value with
        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse &lt;cmd&gt;</screen>
        The following response commands are available:
        <itemizedlist>
            <listitem>
                <para><computeroutput>none</computeroutput>, which does nothing.</para>
            </listitem>
            <listitem>
                <para><computeroutput>pause</computeroutput>, which pauses the
                execution of a VM.</para>
            </listitem>
            <listitem>
                <para><computeroutput>poweroff</computeroutput>, which shuts down
                the VM by pressing the virtual power button. The VM will not have
                the chance of saving any data or veto the shutdown process.</para>
            </listitem>
            <listitem>
                <para><computeroutput>save</computeroutput>, which saves the current
                machine state and powers off the VM afterwards. If saving the machine
                state fails the VM will be paused.</para>
            </listitem>
            <listitem>
                <para><computeroutput>shutdown</computeroutput>, which shuts down
                the VM in a gentle way by sending an <computeroutput>ACPI</computeroutput>
                shutdown event to the VM's operating system. The OS then has the
                chance of doing a clean shutdown.</para>
            </listitem>
        </itemizedlist>
        </para>
    </sect2>

    <sect2 id="vboxwatchdog-moreinfo">
        <title>More information</title>
        <para>For more advanced options and parameters like verbose logging check
        the built-in command line help accessible with
        <computeroutput>--help</computeroutput>.</para>
    </sect2>

    <sect2 id="vboxwatchdog-linux">
      <title>Linux: starting the watchdog service via <computeroutput>init</computeroutput></title>

      <para>On Linux, the watchdog service can be automatically started during
      host boot by adding appropriate parameters to the file
      <computeroutput>/etc/default/virtualbox</computeroutput>.
      There is one mandatory parameter, <computeroutput>VBOXWATCHDOG_USER</computeroutput>,
      which must be set to the user which will later start the VMs. For backward
      compatibility you can also specify <computeroutput>VBOXBALLOONCTRL_USER</computeroutput>The
      parameters in the table below all start with <computeroutput>VBOXWATCHDOG_</computeroutput>
      (<computeroutput>VBOXWATCHDOG_BALLOON_INTERVAL</computeroutput>,
      <computeroutput>VBOXWATCHDOG_LOGSIZE</computeroutput> etc., and for
      previously existing parameters the
      <computeroutput>VBOXBALLOONCTRL_INTERVAL</computeroutput> etc. parameters
      can still be used):
      <table>
        <title>VirtualBox watchdog configuration parameters</title>
        <tgroup cols="3">
          <thead>
            <row>
              <entry><emphasis role="bold">Parameter</emphasis></entry>
              <entry><emphasis role="bold">Description</emphasis></entry>
              <entry><emphasis role="bold">Default</emphasis></entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><computeroutput>USER</computeroutput></entry>
              <entry>The user as which the watchdog service runs</entry>
              <entry></entry>
            </row>
            <row>
              <entry><computeroutput>ROTATE</computeroutput></entry>
              <entry>Number of log files; 0 disables log rotation</entry>
              <entry>10</entry>
            </row>
            <row>
              <entry><computeroutput>LOGSIZE</computeroutput></entry>
              <entry>Maximum size of a log file in bytes to trigger rotation</entry>
              <entry>1MB</entry>
            </row>
            <row>
              <entry><computeroutput>LOGINTERVAL</computeroutput></entry>
              <entry>Maximum time interval in seconds to trigger log rotation</entry>
              <entry>1 day</entry>
            </row>
            <row>
              <entry><computeroutput>BALLOON_INTERVAL</computeroutput></entry>
              <entry>Interval for checking the balloon size (msec)</entry>
              <entry>30000</entry>
            </row>
            <row>
              <entry><computeroutput>BALLOON_INCREMENT</computeroutput></entry>
              <entry>Balloon size increment (MByte)</entry>
              <entry>256</entry>
            </row>
            <row>
              <entry><computeroutput>BALLOON_DECREMENT</computeroutput></entry>
              <entry>Balloon size decrement (MByte)</entry>
              <entry>128</entry>
            </row>
            <row>
              <entry><computeroutput>BALLOON_LOWERLIMIT</computeroutput></entry>
              <entry>Balloon size lower limit (MByte)</entry>
              <entry>64</entry>
            </row>
            <row>
              <entry><computeroutput>BALLOON_SAFETYMARGIN</computeroutput></entry>
              <entry>Free memory required for decreasing the balloon size (MByte)</entry>
              <entry>1024</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      </para>
    </sect2>

    <sect2 id="vboxwatchdog-solaris">
      <title>Solaris: starting the watchdog service via SMF</title>

      <para>On Solaris hosts, the VirtualBox watchdog service daemon is
      integrated into the SMF framework. You can change the parameters, but
      don't have to if the defaults already match your needs:<screen>svccfg -s svc:/application/virtualbox/balloonctrl:default setprop config/balloon_interval=10000
svccfg -s svc:/application/virtualbox/balloonctrl:default setprop config/balloon_safetymargin=134217728</screen></para>

      <para>The table in the previous section showing the parameter names and
      defaults also applies to Solaris. The parameter names must be changed
      to lowercase and a prefix of <computeroutput>config/</computeroutput>
      has to be added, e.g. <computeroutput>config/user</computeroutput> or
      <computeroutput>config/balloon_safetymargin</computeroutput>. If you made any
      change, don't forget to run the following command to put the changes into
      effect immediately:<screen>svcadm refresh svc:/application/virtualbox/balloonctrl:default</screen></para>

      <para>If you forget the above command then the previous settings will
      be used when enabling the service. Check the current property settings
      with:<screen>svcprop -p config svc:/application/virtualbox/balloonctrl:default</screen></para>

      <para>When everything is configured correctly you can start the
      VirtualBox watchdog service with the following command:<screen>svcadm enable svc:/application/virtualbox/balloonctrl:default</screen></para>

      <para>For more information about SMF, please refer to the Solaris
      documentation.</para>
    </sect2>
  </sect1>

  <sect1 id="otherextpacks">
    <title>Other extension packs</title>

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

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

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

    <para>Configuring the remote access works very similarly to VRDP (see
    <xref linkend="vrde" />), with some limitations: VNC does not
    support specifying several port numbers, and the authentication is done
    differently. VNC can only deal with password authentication, and there
    is no option to use password hashes. This leaves no other choice than
    having a clear-text password in the VM configuration, which can be set with
    the following command:<screen>VBoxManage modifyvm "VM name" --vrdeproperty VNCPassword=secret</screen></para>

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

    <para>The following command switches back to VRDP (if
    installed):<screen>VBoxManage setproperty vrdeextpack "Oracle VM VirtualBox Extension Pack"</screen></para>
  </sect1>

  <sect1 id="autostart">
    <title>Starting virtual machines during system boot</title>

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

    <sect2 id="autostart-linux">
      <title>Linux: starting the autostart service via <computeroutput>init</computeroutput></title>

      <para>On Linux, the autostart service is activated by setting two variables in
      <computeroutput>/etc/default/virtualbox</computeroutput>.
      The first one is <computeroutput>VBOXAUTOSTART_DB</computeroutput> which
      contains an absolute path to the autostart database directory.
      The directory should have write access for every user who should be able to
      start virtual machines automatically. Furthermore the directory should have the
      sticky bit set.
      The second variable is <computeroutput>VBOXAUTOSTART_CONFIG</computeroutput>
      which points the service to the autostart configuration file which is used
      during boot to determine whether to allow individual users to start a VM
      automatically and configure startup delays.
      The configuration file can be placed in <computeroutput>/etc/vbox</computeroutput>
      and contains several options. One is <computeroutput>default_policy</computeroutput>
      which controls whether the autostart service allows or denies to start a VM
      for users which are not in the exception list.
      The exception list starts with <computeroutput>exception_list</computeroutput>
      and contains a comma separated list with usernames. Furthermore a separate
      startup delay can be configured for every user to avoid overloading the host.
      A sample configuration is given below:</para>

      <para><screen>
# Default policy is to deny starting a VM, the other option is "allow".
default_policy = deny

# Bob is allowed to start virtual machines but starting them
# will be delayed for 10 seconds
bob = {
    allow = true
    startup_delay = 10
}

# Alice is not allowed to start virtual machines, useful to exclude certain users
# if the default policy is set to allow.
alice = {
    allow = false
}
      </screen></para>

      <para>Every user who wants to enable autostart for individual machines
      has to set the path to the autostart database directory with
      <screen>VBoxManage setproperty autostartdbpath &lt;Autostart directory&gt;</screen>
      </para>
    </sect2>

    <sect2 id="autostart-solaris">
      <title>Solaris: starting the autostart service via SMF</title>

      <para>On Solaris hosts, the VirtualBox autostart daemon is
      integrated into the SMF framework. To enable it you have to point the service
      to an existing configuration file which has the same format as on Linux (see <xref linkend="autostart-linux" />):
      <screen>svccfg -s svc:/application/virtualbox/autostart:default setprop config/config=/etc/vbox/autostart.cfg</screen>
      </para>

      <para>When everything is configured correctly you can start the
      VirtualBox autostart service with the following command:<screen>svcadm enable svc:/application/virtualbox/autostart:default</screen></para>

      <para>For more information about SMF, please refer to the Solaris
      documentation.</para>
    </sect2>

    <sect2 id="autostart-osx">
      <title>Mac OS X: starting the autostart service via launchd</title>

      <para>On Mac OS X, launchd is used to start the VirtualBox autostart service. An
      example configuration file can be found in
      <computeroutput>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</computeroutput>.
      To enable the service copy the file to <computeroutput>/Library/LaunchDaemons</computeroutput> and change the
      <computeroutput>Disabled</computeroutput> key from
      <computeroutput>true</computeroutput> to
      <computeroutput>false</computeroutput>. Furthermore replace the second parameter
      to an existing configuration file which has the same format as on Linux (see <xref linkend="autostart-linux" />).
      To manually start the service use the following command:
      <screen>launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist</screen>
      For additional information on how launchd services could be
      configured see <literal><ulink
      url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html">http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html</ulink></literal>.</para>
    </sect2>
  </sect1>

  <sect1 id="vboxexpertstoragemgmt">
    <title>VirtualBox expert storage management</title>

    <para>In case the snapshot model of VirtualBox is not sufficient
    it is possible to enable a special mode which makes it possible to
    reconfigure storage attachments while the VM is paused.
    The user has to make sure that the disk data stays consistent to the guest
    because unlike with hotplugging the guest is not informed about detached
    or newly attached media.</para>

    <para>The expert storage management mode can be enabled per VM executing:</para>

    <screen>VBoxManage setextradata "VM name" "VBoxInternal2/SilentReconfigureWhilePaused" 1</screen>

    <para>Storage attachments can be reconfigured while the VM is paused afterwards using:</para>
    <screen>VBoxManage storageattach ...</screen>
  </sect1>

  <sect1 id="hostpowertweaks">
    <title>Handling of host power management events</title>

    <para>Some host power management events are handled by VirtualBox. The
    actual behavior depends on the platform:</para>

    <para>
      <glosslist>
        <glossentry>
          <glossterm>Host Suspends</glossterm>
           <glossdef>
             <para>
               This event is generated when the host is about to suspend, that is,
               the host saves the state to some non-volatile storage and powers off.
             </para>
             <para>
               This event is currently only handled on Windows hosts and Mac OS X hosts.
               When this event is generated, VirtualBox will pause all running VMs.
             </para>
           </glossdef>
         </glossentry>
         <glossentry>
           <glossterm>Host Resumes</glossterm>
           <glossdef>
             <para>
               This event is generated when the host woke up from the suspended
               state.
             </para>
             <para>
               This event is currently only handled on Windows hosts and Mac OS X hosts.
               When this event is generated, VirtualBox will resume all VMs which
               are where paused before.
             </para>
           </glossdef>
         </glossentry>
         <glossentry>
           <glossterm>Battery Low</glossterm>
           <glossdef>
             <para>
               The battery level reached a critical level (usually less than 5
               percent charged).
             </para>
             <para>
               This event is currently only handled on Windows hosts and Mac OS X hosts.
               When this event is generated, VirtualBox will save the state and
               terminate all VMs in preparation of a potential host powerdown.
             </para>
             <para>The behavior can be configured. By executing the following command,
             no VM is saved:</para>
             <screen>VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 0</screen>
             <para>This is a global setting as well as a per-VM setting. The per-VM
               value has higher precedence than the global value. The following command
               will save the state of all VMs but will not save the state of VM "foo":</para>
             <screen>VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 1
VBoxManage setextradata "foo" "VBoxInternal2/SavestateOnBatteryLow" 0</screen>
             <para>The first line is actually not required as by default the savestate
             action is performed.</para>
           </glossdef>
         </glossentry>
       </glosslist>
     </para>
   </sect1>

   <sect1 id="sse412passthrough">
     <title>Experimental support for passing through SSE4.1 / SSE4.2 instructions</title>
     <para>
       To provide SSE 4.1 / SSE 4.2 support to guests, the host CPU has to
       implement these instruction sets. Starting with VirtualBox 4.3.8 it is
       possible to enable these instructions for certain guests using the
       following commands:</para><screen>VBoxManage setextradata "VM name" VBoxInternal/CPUM/SSE4.1 1
VBoxManage setextradata "VM name" VBoxInternal/CPUM/SSE4.2 1</screen>
     <para>
       These are a per-VM settings and they are turned off by default.
     </para>
   </sect1>

  <sect1 id="hidledssync">
    <title>Support for keyboard indicators synchronization</title>

    <para>
      This feature makes the host keyboard lights match those of the virtual machine's virtual
      keyboard when the machine window is selected. It is currently implemented for Mac OS X and
      Windows hosts and available as of releases 4.2.24 and 4.3.8. The feature can be enabled using
      the following command:
    </para>

    <screen>VBoxManage setextradata "VM name" GUI/HidLedsSync "1"</screen>

    <para>
      In order to disable it, use the same command but change "1" to "0", or use the VBoxManage
      command to remove the extra data. This is a per-VM setting and it is disabled by default.
    </para>
  </sect1>

  <sect1 id="usbtrafficcapturing">
    <title>Capturing USB traffic for selected devices</title>

    <para>
      Starting with VirtualBox 5.0 it is possible to capture USB traffic for
      single USB devices or on the root hub level which captures the traffic of
      all USB devices attached to the root hub. VirtualBox stores the traffic
      in a format which is compatible with Wireshark. To capture the traffic
      of a specific USB device it must be attached to the VM with VBoxManage
      using the following command:
    </para>

    <screen>VBoxManage controlvm "VM name" usbattach "device uuid|address" --capturefile "filename"</screen>

    <para>
      In order to enable capturing on the root hub use the following command
      while the VM is not running:
    </para>

    <screen>VBoxManage setextradata "VM name" VBoxInternal/Devices/usb-ehci/0/LUN#0/Config/CaptureFilename "filename"</screen>

    <para>The command above enables capturing on the root hub attached to the EHCI controller.
    To enable it for the OHCI or XHCI controller replace <computeroutput>usb-ehci</computeroutput>
    with <computeroutput>usb-ohci</computeroutput> or <computeroutput>usb-xhci</computeroutput> respectively.</para>
  </sect1>

  <sect1 id="heartbeatservice">
    <title>Configuring the heartbeat service</title>
    <para>
      VirtualBox ships a simple heartbeat service. Once the Guest Additions are
      active, the guest sends frequent heartbeat pings to the host. If the guest
      stops sending the heartbeat pings without properly terminating the service,
      the VM process will log this event in the VBox.log file. In the future it
      might be possible to configure dedicated actions but for now there is only a
      warning in the log file.</para>

    <para>
      There are two parameters to configure. The <emphasis>heartbeat interval</emphasis>
      defines the time between two heartbeat pings. The default value is 2 seconds, that
      is, the heartbeat service of the VirtualBox Guest Additions will send a heartbeat
      ping every two seconds. The value in nanoseconds can be configured like this:
    </para>
    <screen>VBoxManage controlvm "VM name" VBoxInternal/Devices/VMMDev/0/Config/HeartbeatInterval 2000000000</screen>
    <para>
      The <emphasis>heartbeat timeout</emphasis> defines the time the host waits
      starting from the last heartbeat ping before it defines the guest as unresponsive.
      The default value is 2 times the heartbeat interval (4 seconds) and can be configured
      as following (in nanoseconds):
    </para>

    <screen>VBoxManage controlvm "VM name" VBoxInternal/Devices/VMMDev/0/Config/HeartbeatTimeout 4000000000</screen>

    <para>
      If the heartbeat timeout expires, there will be a log message like
      <emphasis>VMMDev: HeartBeatCheckTimer: Guest seems to be unresponsive. Last heartbeat
        received 5 seconds ago.</emphasis>
      If another heartbeat ping arrives after this warning, there will be a log
      message like
      <emphasis>VMMDev: GuestHeartBeat: Guest is alive.</emphasis>
    </para>
  </sect1>

  <sect1 id="diskencryption">
    <title>Encryption of disk images</title>

    <para>
      Starting with VirtualBox 5.0, it is possible to encrypt the data stored in
      hard disk images transparently for the guest. It does not depend on a specific
      image format to be used. Images which have the data encrypted are not portable
      between VirtualBox and other virtualization software.
    </para>

    <para>
      VirtualBox uses the AES algorithm in XTS mode and supports 128 or 256 bit
      data encryption keys (DEK).
      The DEK is stored encrypted in the medium properties and is decrypted during
      VM startup by entering a password which was chosen when the image was encrypted.
    </para>

    <para>
      Since the DEK is stored as part of the VM configuration file, it is
      important that it is kept safe. Losing the DEK means that the data stored
      in the disk images is lost irrecoverably. Having complete and up to
      date backups of all data related to the VM is the responsibility of the
      user.
    </para>

    <sect2 id="diskencryption-limitations">
      <title>Limitations</title>

      <para>
        There are some limitations the user needs to be aware of when using this
        feature:
      </para>

      <itemizedlist>

        <listitem>
          <para>This feature is part of the Oracle VM VirtualBox Extension
            Pack, which needs to be installed. Otherwise disk encryption
            is unavailable.</para>
        </listitem>

        <listitem>
          <para>Since encryption works only on the stored user data,
            it is currently not possible to check for metadata integrity of the disk image.
            Attackers might destroy data by removing or changing blocks of data
            in the image or change metadata items such as the disk size.
          </para>
        </listitem>

        <listitem>
          <para>Exporting appliances which contain encrypted disk images is not
            possible because the OVF specification doesn't support this.
            All images are therefore decrypted during export.</para>
        </listitem>

        <listitem>
          <para>The DEK is kept in memory while the VM is running to be able to
            decrypt data read and encrypt data written by the guest. While this should
            be obvious the user needs to be aware of this because an attacker might be able
            to extract the key on a compromised host and decrypt the data.</para>
        </listitem>

        <listitem>
          <para>When encrypting or decrypting the images, the password is
            passed in clear text via the VirtualBox API. This needs to be kept
            in mind, especially when using third party API clients which make
            use of the webservice where the password might be transmitted
            over the network. The use of HTTPS is mandatory in such a case.
          </para>
        </listitem>

        <listitem>
          <para>Encrypting images with differencing images is only possible if
            there are no snapshots or a linear chain of snapshots. This
            limitation may be addressed in a future VirtualBox version.</para>
        </listitem>

      </itemizedlist>

    </sect2>

    <sect2 id="diskencryption-encryption">
      <title>Encrypting disk images</title>

      <para>
        Encrypting disk images can be done either using the GUI or VBoxManage.
        While the GUI is easier to use, it works on a per VM basis and encrypts
        all disk images attached to the specific VM.
        With VBoxManage one can encrypt individual images (including all differencing
        images). To encrypt an unencrypted medium with VBoxManage, use:
      </para>

      <screen>VBoxManage encryptmedium "uuid|filename" --newpassword "file|-" --cipher "cipher id" --newpasswordid "id"</screen>

      <para>
        To supply the encryption password point VBoxManage to the file where the
        password is stored or specify <computeroutput>-</computeroutput> to let VBoxManage
        ask you for the password on the command line.
      </para>
      <para>
        The cipher parameter specifies the cipher to use for encryption and can be either
        <computeroutput>AES-XTS128-PLAIN64</computeroutput> or <computeroutput>AES-XTS256-PLAIN64</computeroutput>.
        The specified password identifier can be freely chosen by the user and is
        used for correct identification when supplying multiple passwords during
        VM startup.
      </para>
      <para>
        If the user uses the same password when encrypting multiple images and also the
        same password identifier, the user needs to supply the password only once during
        VM startup.
      </para>
    </sect2>

    <sect2 id="diskencryption-startvm">
      <title>Starting a VM with encrypted images</title>

      <para>
        When a VM is started using the GUI, a dialog will open where the user
        needs to enter all passwords for all encrypted images attached to the VM.
        If another frontend like VBoxHeadless is used, the VM will be paused as soon
        as the guest tries to access an encrypted disk.
        The user needs to provide the passwords through VBoxManage using the following
        command:
      </para>

      <screen>VBoxManage controlvm "uuid|vmname" addencpassword "id" "password" [--removeonsuspend "yes|no"]</screen>

      <para>
        The <computeroutput>id</computeroutput> parameter must be the same as the password identifier
        supplied when encrypting the images. <computeroutput>password</computeroutput> is the password
        used when encrypting the images. The user can optionally specify
        <computeroutput>--removeonsuspend "yes|no"</computeroutput> to specify whether
        to remove the password from VM memory when the VM is suspended. Before the VM can be
        resumed, the user needs to supply the passwords again. This is useful when
        a VM is suspended by a host suspend event and the user doesn't want
        the password to remain in memory.
      </para>
    </sect2>

    <sect2 id="diskencryption-decryption">
      <title>Decrypting encrypted images</title>

      <para>
        In some circumstances it might be required to decrypt previously encrypted
        images. This can be done in the GUI for a complete VM or using VBoxManage
        with the following command:
      </para>

      <screen>VBoxManage encryptmedium "uuid|filename" --oldpassword "file|-"</screen>

      <para>
        The only required parameter is the password the image was encrypted with.
        The options are the same as for encrypting images.
      </para>
    </sect2>
  </sect1>

  <sect1 id="gimdebug">
    <title>Paravirtualized debugging</title>

    <para>In this section we cover debugging of guest operating systems using interfaces
    supported by paravirtualization providers.</para>

    <note>
      <para>Paravirtualized debugging significantly alter guest operating system behaviour
      and should only be used by expert users for debugging and diagnostics.</para>
    </note>

    <para>These debug options are specified as a string of key-value pairs separated by
    commas. An empty string disables paravirtualized debugging.</para>

    <sect2 id="gimdebughyperv">
      <title>Hyper-V debug options</title>

      <para>All of the options listed below are optional, and thus the default value
      specified will be used when the corresponding key-value pair is not
      specified.</para>

      <itemizedlist>
        <listitem>
          <para>Key: <emphasis role="bold"><computeroutput>enabled</computeroutput></emphasis></para>
          <para>Value: <computeroutput>0</computeroutput> or <computeroutput>1</computeroutput></para>
          <para>Default: <computeroutput>0</computeroutput></para>
          <para>Specify <computeroutput>1</computeroutput> to enable the Hyper-V debug
            interface. If this key-value pair is not specified or the value is not
            <computeroutput>1</computeroutput>, the Hyper-V debug interface is disabled
            regardless of other key-value pairs being present.</para>
        </listitem>
        <listitem>
          <para>Key: <emphasis role="bold"><computeroutput>address</computeroutput></emphasis></para>
          <para>Value: IPv4 address</para>
          <para>Default: 127.0.0.1</para>
          <para>Specify the IPv4 address where the remote debugger is connected.</para>
        </listitem>
        <listitem>
          <para>Key: <emphasis role="bold"><computeroutput>port</computeroutput></emphasis></para>
          <para>Value: UDP port number</para>
          <para>Default: 50000</para>
          <para>Specify the UDP port number where the remote debugger is connected.</para>
        </listitem>
        <listitem>
          <para>Key: <emphasis role="bold"><computeroutput>vendor</computeroutput></emphasis></para>
          <para>Value: Hyper-V vendor signature reported via CPUID to the guest</para>
          <para>Default: When debugging is enabled: <computeroutput>Microsoft Hv</computeroutput>,
          otherwise: <computeroutput>VBoxVBoxVBox</computeroutput></para>
          <para>Specify the Hyper-V vendor signature which is exposed to the guest via CPUID.
          For debugging Microsoft Windows guests, it is required the hypervisor reports
          the Microsoft vendor.</para>
        </listitem>
        <listitem>
          <para>Key: <emphasis role="bold"><computeroutput>hypercallinterface</computeroutput>
          </emphasis></para>
          <para>Value: <computeroutput>0</computeroutput> or <computeroutput>1</computeroutput></para>
          <para>Default: <computeroutput>0</computeroutput></para>
          <para>Specify whether hypercalls should be suggested for initiating debug data
          transfers between host and guest rather than MSRs when requested by the guest.</para>
        </listitem>
        <listitem>
          <para>Key: <emphasis role="bold"><computeroutput>vsinterface</computeroutput>
          </emphasis></para>
          <para>Value: <computeroutput>0</computeroutput> or <computeroutput>1</computeroutput></para>
          <para>Default: When debugging is enabled, <computeroutput>1</computeroutput>,
          otherwise <computeroutput>0</computeroutput></para>
          <para>Specify whether to expose the "VS#1" (virtualization service) interface to the
          guest. This interface is required for debugging Microsoft Windows 10 32-bit guests, but
          is optional for other Windows versions.</para>
        </listitem>
      </itemizedlist>

      <sect3 id="gimdebughyperv-windows-setup">
        <title>Setting up Windows guests for debugging with the Hyper-V paravirtualization provider</title>

        <para>Windows supports debugging over a serial cable, USB, IEEE 1394 Firewire, and Ethernet
        (only Windows 8 and later). USB and IEEE 1394 are not applicable for virtual machines, and
        Ethernet requires Windows 8 or later. While serial connection is universally usable, it is
        slow.</para>

        <para>Debugging using the Hyper-V debug transport, supported on Windows Vista and later,
        offers significant benefits. It provides excellent performance due to direct host-to-guest
        transfers, it is easy to set up and requires minimal support from the hypervisor. It can be
        used with the debugger running on the same host as the VM or with the debugger and VM on
        separate machines connected over a network.</para>

        <sect4><title>Prerequisites</title>
          <itemizedlist>
            <listitem>
              <para>A VM configured for Hyper-V paravirtualization running a Windows Vista or newer
              Windows guest. You may check the effective paravirtualization provider for your VM from
              the output of the following VBoxManage command:</para>
              <para><screen>VBoxManage showvminfo "VM name"</screen></para>
            </listitem>

            <listitem>
              <para>A sufficiently up-to-date version of the Microsoft WinDbg debugger required
              to debug the version of Windows in your VM.</para>
            </listitem>

            <listitem>
              <para>While Windows 8 and newer Windows guests ship with Hyper-V debug support,
              Windows 7 and Vista do not. To use Hyper-V debugging with a Windows 7 or Vista
              guest, copy the file
              <computeroutput>kdvm.dll</computeroutput> from a Windows 8.0 installation<footnote>
              <para>Only Windows 8.0 ships <computeroutput>kdvm.dll</computeroutput>. Windows 8.1
              and newer Windows versions do not.</para></footnote>. This file is
              typically located in <computeroutput>C:\Windows\System32</computeroutput>. Copy it
              to the same location in your Windows 7/Vista guest. Make sure you copy the 32-bit or
              64-bit version of the DLL which matches your guest OS.</para>
            </listitem>
          </itemizedlist>
        </sect4>

        <sect4><title>VM and guest configuration</title>
          <orderedlist>
            <listitem>
              <para>Power off the VM.</para>
            </listitem>

            <listitem>
              <para>Enable the debug options by executing the following VBoxManage command:</para>
              <para><screen>VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1"</screen></para>
              <para>The above command assumes your debugger will connect to your host machine
              on UDP port 50000. However, if you need to run the debugger on a remote machine
              you may specify the remote address and port here, e.g. using:</para>
              <para>
              <screen>VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1,address=192.168.32.1,port=55000"</screen>
              </para>
              <para>Refer <xref linkend="gimdebughyperv" /> for the complete set of options.</para>
            </listitem>

            <listitem>
              <para>Start the VM.</para>
            </listitem>

            <listitem>
              <para>In the guest, start an elevated command prompt and execute the
              following commands:</para>
              <itemizedlist>
                <listitem><para>For a Windows 8 or newer Windows guest:</para>
                  <para>
                  <screen>bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4</screen>
                  </para>
                </listitem>
                <listitem><para>For a Windows 7 or Vista guest:</para>
                  <para>
                  <screen>bcdedit /set loadoptions host_ip=5.5.5.5,host_port=50000,encryption_key=1.2.3.4</screen>
                  <screen>bcdedit /set dbgtransport kdvm.dll</screen>
                  </para>
                  <para>The IP address and port in the <computeroutput>bcdedit</computeroutput> command
                  are ignored when using the Hyper-V debug transport. Any valid IP and a port number greater
                  than 49151 and lower than 65536 can be entered.</para>

                  <para>The encryption key in the <computeroutput>bcdedit</computeroutput> command is
                  relevant and must be valid. The key "1.2.3.4" used in the above example is valid
                  and may be used if security is not a concern. If you do not specify any encryption key,
                  <computeroutput>bcdedit</computeroutput> will generate one for you and you will need to copy
                  this key to later enter in Microsoft WinDbg on the remote end. This encryption key is used
                  to encrypt the debug data exchanged between Windows and the debugger.</para>
                </listitem>
                <listitem>
                  <para>Execute one or more of the following commands to enable debugging for
                  the appropriate phase or component of your Windows guest: </para>
                  <para>
                    <screen>bcdedit /set debug on</screen>
                    <screen>bcdedit /set bootdebug on</screen>
                    <screen>bcdedit /set {bootmgr} bootdebug on</screen>
                  </para>
                  <para>Please note that the <computeroutput>bootdebug</computeroutput> options are only
                  effective on Windows 8 or newer when using the Hyper-V debug transport. Refer to Microsoft
                  Windows documentation for detailed explanation of <computeroutput>bcdedit</computeroutput>
                  options.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Start Microsoft WinDbg on your host machine or remote host.</para>

              <para>From the "File" menu, select "Kernel debug". Under the "NET" tab, specify the UDP port
              number you used in the <computeroutput>paravirtdebug</computeroutput> options. If you didn't
              specify any, leave it as 50000. Ensure that the UDP port is not blocked by a firewall or other
              security software.</para>

              <para>In the "Key" field, enter <computeroutput>1.2.3.4</computeroutput> or the encryption
              key from the <computeroutput>bcdedit</computeroutput> command in your Windows guest.</para>

              <para>Now press "OK" to start listening for connections. Microsoft WinDbg typically shows
              a "Waiting to reconnect" message during this phase.</para>

              <para>Alternatively, launch WinDbg from the command line to directly start a debug session:
                <screen>windbg.exe -k net:port=50000,key=1.2.3.4</screen>
              Please refer to the WinDbg documentation for complete command line syntax.
              </para>

            </listitem>

            <listitem>
              <para>Reboot your Windows guest and it should then connect as a debuggee with Microsoft
              WinDbg.</para>
            </listitem>
          </orderedlist>
        </sect4>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="pcspeaker_passthrough">
    <title>PC speaker passthrough</title>

    <para>As an experimental feature (primarily due to being limited to Linux
    host only and unknown Linux distribution coverage) VirtualBox supports
    passing through the PC speaker to the host. The PC speaker (sometimes
    called system speaker) is a way to produce audible feedback such as beeps
    without the need for regular audio/sound card support.</para>

    <para>The PC speaker passthrough feature in VirtualBox handles beeps only.
    Advanced PC speaker use by the VM (such as PCM audio) will not work,
    resulting in undefined host behavior.</para>

    <para>Producing beeps on Linux is unfortunately a very complex topic.
    VirtualBox offers a collection of options, in an attempt to make this work
    deterministically and reliably on as many Linux distributions and system
    configurations as possible:
      <table>
        <title>PC speaker configuration options</title>
        <tgroup cols="3">
          <thead>
            <row>
              <entry><emphasis role="bold">Code</emphasis></entry>
              <entry><emphasis role="bold">Device</emphasis></entry>
              <entry><emphasis role="bold">Notes</emphasis></entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>1</entry>
              <entry><computeroutput>/dev/input/ by-path/platform- pcspkr-event-spkr</computeroutput></entry>
              <entry>Direct host PC speaker use.</entry>
            </row>
            <row>
              <entry>2</entry>
              <entry><computeroutput>/dev/tty</computeroutput></entry>
              <entry>Uses the terminal association of the VM process. VM needs
              to be started on a virtual console.</entry>
            </row>
            <row>
              <entry>3</entry>
              <entry><computeroutput>/dev/tty0</computeroutput> or
              <computeroutput>/dev/vc/0</computeroutput></entry>
              <entry>Can only be used by user <computeroutput>root</computeroutput>
              or users with capability <computeroutput>cap_sys_tty_config</computeroutput></entry>
            </row>
            <row>
              <entry>9</entry>
              <entry>user specified console or evdev device path</entry>
              <entry>Like 1-3, just with a custom device path.</entry>
            </row>
            <row>
              <entry>70</entry>
              <entry><computeroutput>/dev/tty</computeroutput></entry>
              <entry>Standard beep only. Loses frequency and length. See code
              2.</entry>
            </row>
            <row>
              <entry>79</entry>
              <entry>user specified terminal device path</entry>
              <entry>Like 70, just with a custom device path.</entry>
            </row>
            <row>
              <entry>100</entry>
              <entry>all of the above</entry>
              <entry>Tries all above codes.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </para>

    <para>To enable PC speaker passthrough use the following command:
      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" N</screen>
    Replace <computeroutput>N</computeroutput> with the code representing the
    case you want to use. Changing this setting will take effect when the VM is
    started next. It is safe to enable PC speaker passthrough on all host OSes.
    It will only have an effect on Linux.</para>

    <para>The VM log file, <computeroutput>VBox.log</computeroutput>, will
    contain lines with the prefix <computeroutput>PIT: speaker:</computeroutput>
    showing the PC speaker passthrough setup activities. It gives hints which
    device it picked or why it failed.</para>

    <para>Enabling PC speaker passthrough for the VM is usually the simple
    part. The real difficulty is making sure that VirtualBox can access the
    necessary device, because in a typical Linux install most of them can only
    be accessed by user <computeroutput>root</computeroutput>. You should
    follow the preferred way to persistently change this, e.g. by referring to
    your distribution's documentation. Since there are countless Linux
    distribution variants, we can only give the general hints that there is
    often a way to give the X11 session user access to additional devices, or
    you need to find a working solution using a udev configuration file. If
    everything fails you might try setting the permissions using a script
    which is run late enough in the host system startup.</para>

    <para>Sometimes additional rules are applied by the kernel to limit access
    (e.g. that the VM process must have the same controlling terminal as the
    device configured to be used for beeping, something which is often very
    difficult to achieve for GUI applications such as VirtualBox). The table
    above contains some hints, but generally refer to the Linux
    documentation.</para>

    <para>If you have trouble getting any beeps even if the device permissions
    are set up and VBox.log confirms that it uses evdev or console for the
    PC speaker control, check if your system has a PC speaker. Some systems do
    not have one. Other complications can arise from Linux rerouting the PC
    speaker output to a sound card. Check if the beeps are audible if you
    connect speakers to your sound card. Today almost all systems have one.
    Finally, check if the audio mixer control has a channel named "beep"
    (could be hidden in the mixer settings) and that it isn't muted.</para>
  </sect1>

  <sect1 id="usbip">
    <title>Accessing USB devices exposed over the network with USB/IP</title>

    <para>Starting with 5.1.0, VirtualBox supports passing through USB
    devices which are exposed over the network using the USB over IP protocol
    without the need to configure the client side provided by the kernel and
    usbip tools. Furthermore, this feature works with VirtualBox running on any
    supported host, rather than just Linux alone - as is the case with the official
    client.</para>

    <para>To enable support for passing through USB/IP devices, the device server exporting
    the devices must be added with the following command:
    <screen>VBoxManage usbdevsource add "Unique name" --backend "USBIP" --address "Device server[:port]"</screen>
    USB devices exported on the device server are then accessible through the GUI
    or VBoxManage, like any USB devices attached locally. This can be used multiple times
    to access different device servers.</para>

    <para>To remove a device server, the following command can be used:
      <screen>VBoxManage usbdevsource remove "Unique name"</screen>
    </para>

    <sect2 id="usbip-setup-server">
      <title>Setting up USB/IP support on a Linux system</title>

      <para>This section gives a brief overview on how to set up a Linux based system
      to act as a USB device server. The system on the server requires that the
      <computeroutput>usbip-core.ko</computeroutput> and
      <computeroutput>usbip-host.ko</computeroutput> kernel drivers
      are available, and that the USB/IP tools package is installed.
      The particular installation method for the necessary tools depends on which 
      distribution is used.
      For example, for Debian based systems - the following command should be used to 
      install the required tools:
      <screen>apt-get install usbip-utils</screen></para>
      <para>To check whether the necessary tools are already installed use
      the following command:
      <screen>
$ usbip list -l
      </screen></para>
      <para>
      which should produce output similar to that shown in the example below:
      <screen>
 - busid 4-2 (0bda:0301)
   Realtek Semiconductor Corp. : multicard reader (0bda:0301)

 - busid 5-1 (046d:c52b)
   Logitech, Inc. : Unifying Receiver (046d:c52b)
      </screen></para>

      <para>If everything is installed, the USB/IP server needs to be started as
      <computeroutput>root</computeroutput> using the following command:
      <screen>usbipd -D</screen>
      Refer to the documentation for the installed distribution to determine how to start the
      service when the system boots.</para>

      <para>By default, no device on the server is exported - and this must be done manually
      for each device. To export a device use: 
      <screen>usbip bind -b "bus identifier"</screen>
      To export the multicard reader from above, for example  - use:
      <screen>usbip bind -b 4-2</screen></para>
    </sect2>

    <sect2 id="usbip-security">
      <title>Security considerations</title>

      <para>The communication between the server and client is unencrypted and
      there is no authorization required to access exported devices. An attacker
      might sniff sensitive data or gain control over a device. To mitigate this
      risk, the device should be exposed over a local network to which only trusted
      clients have access. To access the device remotely over a public network,
      a VPN solution should be used to provide the required level of security protection.</para>
    </sect2>
  </sect1>

</chapter>