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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
<!ENTITY % all.entities SYSTEM "all-entities.ent">
%all.entities;
]>
<chapter id="AdvancedTopics">

  <title>Advanced Topics</title>

  <sect1 id="vboxsdl">

    <title>VBoxSDL, The Simplified VM Displayer</title>

    <sect2 id="vboxsdl-intro">

      <title>Introduction</title>

      <para>
        VBoxSDL is a simple graphical user interface (GUI) that lacks
        the nice point-and-click support of the main GUI, VirtualBox.
        VBoxSDL is currently primarily used internally for debugging
        VirtualBox and therefore not officially supported. But you may
        find it useful for environments where the virtual machines are
        not necessarily controlled by the same person that uses the
        virtual machine.
      </para>

      <note>
        <para>
          VBoxSDL is not available on the Mac OS X host platform.
        </para>
      </note>

      <para>
        As shown in the following screenshot, VBoxSDL provides a simple
        window that contains only the "pure" virtual machine, without
        menus or other controls to click and with 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:
      </para>

<screen>VBoxSDL --startvm &lt;vm&gt;</screen>

      <para>
        where <computeroutput>&lt;vm&gt;</computeroutput> is the name or
        UUID of an existing virtual machine.
      </para>

    </sect2>

    <sect2 id="vboxsdl-secure-label">

      <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
        is 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:
      </para>

<screen>VBoxManage setextradata "VM name" "VBoxSDL/SecureLabel" "The Label"</screen>

      <para>
        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, such as 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:
        <ulink
      url="http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html">http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html</ulink>.
      </para>

    </sect2>

    <sect2 id="vboxsdl-modifier-release">

      <title>Releasing Modifiers with VBoxSDL on Linux</title>

      <para>
        When switching from a X virtual terminal (VT) to another VT
        using Ctrl-Alt-F<replaceable>x</replaceable> 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, the 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>

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

    </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. Credentials are 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, called Winlogon, which can be customized and extended
        by means of so-called GINA (Graphical Identification and
        Authentication) modules. 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 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 as shown in
        <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 with a value of
        <computeroutput>VBoxGINA.dll</computeroutput>.:
      </para>

<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen>

      <note>
        <para>
          The VirtualBox GINA module is implemented as a wrapper around
          the standard Windows GINA module,
          <computeroutput>MSGINA.DLL</computeroutput>. As a result, it
          may not work correctly with third party GINA modules.
        </para>
      </note>

      <para>
        To manually install the VirtualBox credential provider module,
        extract the Guest Additions as shown in
        <xref
      linkend="windows-guest-file-extraction" /> and copy
        the file <computeroutput>VBoxCredProv.dll</computeroutput> to
        the Windows <computeroutput>SYSTEM32</computeroutput> directory.
        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>
        All default values, the key named
        <computeroutput>Default</computeroutput>, must be set to
        <computeroutput>VBoxCredProv</computeroutput>.
      </para>

      <para>
        Create a new string named as follows, with a value of
        <computeroutput>Apartment</computeroutput>.
      </para>

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

      <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
        <emphasis>logged out</emphasis> 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. 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:
      </para>

      <itemizedlist>

        <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>
            <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 as Windows never
            renames user accounts internally.
          </para>
        </listitem>

        <listitem>
          <para>
            Auto-logon handling of the built-in
            <emphasis role="bold">Windows Remote Desktop
            Service</emphasis>, formerly known as Terminal Services, is
            disabled by default. To enable it, create the following
            registry key with a <computeroutput>DWORD</computeroutput>
            value of <computeroutput>1</computeroutput>.
          </para>

<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen>
        </listitem>

      </itemizedlist>

      <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 and 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 and Unix distributions
        rely on PAM.
      </para>

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

      <para>
        The <computeroutput>pam_vbox.so</computeroutput> module itself
        <emphasis>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> module 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. This is usually
        <computeroutput>/lib/security/</computeroutput> on 32-bit Linux
        guests or <computeroutput>/lib64/security/</computeroutput> on
        64-bit Linux guests. 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 the GNOME Desktop Manager (GDM)
        to logon users automatically with the credentials passed by the
        host, configure the guest OS as follows:
      </para>

      <orderedlist>

        <listitem>
          <para>
            Copy the <computeroutput>pam_vbox.so</computeroutput> module
            to the security modules directory. In this case,
            <computeroutput>/lib/security</computeroutput>.
          </para>
        </listitem>

        <listitem>
          <para>
            Edit the PAM configuration file for GDM, found at
            <computeroutput>/etc/pam.d/gdm</computeroutput>. Add 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, such as the ones provided by the VirtualBox PAM
            module.
          </para>
        </listitem>

      </orderedlist>

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

      <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>

      <note>
        <para>
          By default, pam_vbox will not wait for credentials to arrive
          from the host. 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>
        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>

      <itemizedlist>

        <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 gets deleted no waiting for credentials will be
            performed and pam_vbox will act like before. 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>

      </itemizedlist>

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

      <itemizedlist>

        <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 has
            timed out. For example, they did not arrive within time.
            This property must be set read-only for the guest
            (<computeroutput>RDONLYGUEST</computeroutput>).
          </para>
        </listitem>

      </itemizedlist>

      <note>
        <para>
          If a pam_vbox guest property does not have the correct flag
          set (<computeroutput>RDONLYGUEST</computeroutput>) the
          property is ignored and, depending on the property, a default
          value will be used. 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>

      <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 with the pam_vbox module, vbox-greeter is shipped as part
          of the Guest Additions but it is not installed or activated on
          the guest OS by default. To install 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>
          <itemizedlist>

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

            <listitem>
              <para>
                vbox-greeter is independent of the graphical session
                chosen by the user, such as Gnome, KDE, or Unity.
                However, it requires FLTK 1.3 for representing its own
                user interface.
              </para>
            </listitem>

          </itemizedlist>
        </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>

        <itemizedlist>

          <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>

        </itemizedlist>

        <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 id="adv-config-win-guest">

    <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 called 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. See
        <xref linkend="guestadd-guestcontrol" /> for details of how to
        use this 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:
        </para>

        <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>

        <para>
          The Guest Additions will automatically use the appropriate
          path to execute the system preparation tool.
        </para>
      </note>

    </sect2>

  </sect1>

  <sect1 id="adv-config-linux-guest">

    <title>Advanced Configuration for Linux and Solaris Guests</title>

    <sect2 id="linux-guest-manual-setup">

      <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 as root:
      </para>

<screen>  rcvboxadd setup</screen>

      <para>
        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 include the following drivers for
        X.Org versions:
      </para>

      <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
            vboxmouse_drv_13.so, and later versions).
          </para>
        </listitem>

      </itemizedlist>

      <para>
        By default these drivers can be found in the folowing directory:
      </para>

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

      <para>
        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. 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 following section 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:
    </para>

    <para>
      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:
    </para>

<screen>echo 1 &gt; /sys/devices/system/cpu/cpu&lt;id&gt;/online</screen>

  </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" />.
      </para>
    </note>

    <para>
      Essentially this feature allows a guest to directly use physical
      PCI devices on the host, even if host does not 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 Graphics Address Remapping
      Table (GART) 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, for example 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 called Intel Virtualization
      Technology for Directed I/O (VT-d), and AMD's solution is called
      AMD-Vi. Check your motherboard datasheet for the appropriate
      technology. Even if your hardware does not 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
      the following apply:
    </para>

    <itemizedlist>

      <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 the
          <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. The
          <computeroutput>intel_iommu=on</computeroutput> boot option
          could be needed. Search for DMAR and PCI-DMA in kernel boot
          log.
        </para>
      </listitem>

    </itemizedlist>

    <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 as follows:
    </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 the 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:
    </para>

<screen>VBoxManage modifyvm "VM name" --pciattach 02:00.0@01:05.0</screen>

    <para>
      To detach the same device, use:
    </para>

<screen>VBoxManage modifyvm "VM name" --pcidetach 02:00.0</screen>

    <para>
      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:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          Only PCI cards with non-shared interrupts, such as those using
          MSI on the host, are supported at the moment.
        </para>
      </listitem>

      <listitem>
        <para>
          No guest state can be reliably saved or restored. The internal
          state of the PCI card cannot be retrieved.
        </para>
      </listitem>

      <listitem>
        <para>
          Teleportation, also called live migration, does not work. The
          internal state of the PCI card cannot be retrieved.
        </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>

    </itemizedlist>

  </sect1>

  <sect1 id="webcam-passthrough">

    <title>Webcam Passthrough</title>

    <sect2 id="webcam-using-guest">

      <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" />.
        </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:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            Get a list of host webcams, or other video input devices:
          </para>

<screen>VBoxManage list webcams</screen>

          <para>
            The output format is as follows:
          </para>

<screen>alias "user friendly name"
host path or identifier</screen>

          <para>
            The alias can be used as a shortcut in other commands. Alias
            '.0' means the default video input device on the host. Alias
            '.1', '.2'means first, second video input device, and so on.
            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 enables you to configure the emulated webcam device.
            The following settings are supported:
          </para>

          <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>
        </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 the webcams attached to a running VM:

<screen>VBoxManage controlvm "VM name" webcam list</screen>

            The output contains the path or alias which was used in the
            <computeroutput>webcam attach</computeroutput> command for
            each attached webcam.
          </para>
        </listitem>

      </itemizedlist>

    </sect2>

    <sect2 id="webcam-win-hosts">

      <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 id="webcam-mac-hosts">

      <title>Mac OS X Hosts</title>

      <para>
        OS X version 10.9 or later 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 id="webcam-linux-hosts">

      <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 id="adv-display-config">

    <title>Advanced Display Configuration</title>

    <sect2 id="customvesa">

      <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 id="max-resolution-guests">

      <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 id="adv-storage-config">

    <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 <xref linkend="storage" />,
        VirtualBox can also present either entire physical hard disks or
        selected partitions as virtual disks to virtual machines.
      </para>

      <para>
        With VirtualBox, this type of access is called <emphasis>raw
        hard disk access</emphasis>. 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. For
        example, whether the virtual disk contains all data written
        before a host OS crash. Consult your host OS documentation for
        details on this.
      </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>
        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, see <xref linkend="vdis" />, or
        <computeroutput>VBoxManage</computeroutput> to assign the image
        to a virtual machine.
      </para>

      <sect3 id="rawdisk-access-entire-physical-disk">

        <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>
          On a Linux host, 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, 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>, which
          must be an absolute path. 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, such as
          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 as follows:

<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 id="rawdisk-access-disk-partitions">

        <title>Access to Individual Physical Hard Disk Partitions</title>

        <para>
          This <emphasis>raw partition support</emphasis> 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. This means that you can 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, on a Linux host, use the
          command:
        </para>

<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
      -rawdisk /dev/sda -partitions 1,5</screen>

        <para>
          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
          <code>/dev/disk1</code>, for example. 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:
        </para>

<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
      -rawdisk /dev/sda -partitions 1,5 -relative</screen>

        <para>
          When used from a virtual machine, the image will then refer
          not to the entire disk, but only to the individual partitions.
          In this 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. For example, to replace the Linux
          boot loader that is used on the host by another boot loader.
          This allows for example 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:
        </para>

<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
      -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr</screen>

        <para>
          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 is 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. See
        <xref linkend="storage-iscsi" />,
        <xref linkend="network_internal" />, and
        <xref
      linkend="vboxmanage-storageattach" />.
      </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:
      </para>

<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>
        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, the 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 id="serialports-legacy-cmds">

    <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 described in <xref
    linkend="serialports" />.
    </para>

    <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 does not work, make sure the VM in question
        does not have old configuration data such as below still active.
      </para>
    </note>

    <para>
      The old sequence of configuring a serial port used the following
      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. 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 id="nat-address-config">

      <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 the NAT network needs to be changed, use 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,
        where 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 id="nat-bind-sockets">

      <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 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:
      </para>

<screen>VBoxManage modifyvm "VM name" --natdnsproxy1 on</screen>

    </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:
      </para>

<screen>VBoxManage modifyvm "VM name" --natdnshostresolver1 on</screen>

      <para>
        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 do not 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 that 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>

    <itemizedlist>

      <listitem>
        <para>
          DMI BIOS information (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>
      </listitem>

      <listitem>
        <para>
          DMI system information (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>
      </listitem>

      <listitem>
        <para>
          DMI board information (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>
      </listitem>

      <listitem>
        <para>
          DMI system enclosure or chassis (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>
      </listitem>

      <listitem>
        <para>
          DMI processor information (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>
      </listitem>

      <listitem>
        <para>
          DMI OEM strings (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>
      </listitem>

    </itemizedlist>

    <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
      example:
    </para>

<screen>VBoxManage setextradata "VM name"
      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial"      "string:1234"</screen>

    <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>

      The DMI system information can be obtained with:

<screen>dmidecode -t1</screen>
    </para>

  </sect1>

  <sect1 id="changeacpicust">

    <title>Configuring Custom ACPI Tables</title>

    <para>
      VirtualBox can be configured to present up to four custom ACPI tables
      to the guest. A command such as the following can be used to configure
      custom ACPI tables (note that CustomTable1, CustomTable2, and
      CustomTable3 are available in addition to CustomTable0):
    </para>

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

    <para>
      Configuring custom ACPI tables can for example avoid the need to
      ask for a new product key in Windows Vista/7/8 and later guests.
    </para>

    <para>
      On Linux hosts, one of the system's ACPI tables can be read from
      <filename>/sys/firmware/acpi/tables/</filename>.
    </para>

  </sect1>

  <sect1 id="fine-tune-timers">

    <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 time stamp counter (TSC) 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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>--timesync-interval</computeroutput>
          </term>

          <listitem>
            <para>
              Specifies the interval at which to synchronize the time
              with the host. The default is 10000 ms (10 seconds).
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>--timesync-min-adjust</computeroutput>
          </term>

          <listitem>
            <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>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>--timesync-latency-factor</computeroutput>
          </term>

          <listitem>
            <para>
              The factor to multiply the time query latency with to
              calculate the dynamic minimum adjust time. The default is
              8 times, which means as follows:
            </para>

            <para>
              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. Do not do any time adjustment
              otherwise.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>--timesync-max-latency</computeroutput>
          </term>

          <listitem>
            <para>
              The max host timer query latency to accept. The default is
              250 ms.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>--timesync-set-threshold</computeroutput>
          </term>

          <listitem>
            <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>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>--timesync-set-start</computeroutput>
          </term>

          <listitem>
            <para>
              Set the time when starting the time sync service.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>--timesync-set-on-restore
            0|1</computeroutput>
          </term>

          <listitem>
            <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>
          </listitem>
        </varlistentry>

      </variablelist>

      <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 Virtual Network Interface (VNIC) 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". The string is case-sensitive.
    </para>

    <para>
      On Solaris 11 hosts, a VNIC template may be used to specify the
      VLAN ID to use while bridging over a network link.

      <footnote>

        <para>
          When Crossbow based bridged networking is used.
        </para>

      </footnote>
    </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 is 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 settings for the newly added interfaces 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 do not specify any core dump directory, the current
      directory of the VirtualBox executable will be used. This 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 id="customize-vm-manager">

      <title>Customizing the VM Manager</title>

      <para>
        There are several advanced customization settings for locking
        down the VirtualBox manager. Locking down means 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:
      </para>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>noSelector</computeroutput>
          </term>

          <listitem>
            <para>
              Do not allow users to start the VirtualBox manager. Trying
              to do so will show a window containing a proper error
              message.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>noMenuBar</computeroutput>
          </term>

          <listitem>
            <para>
              VM windows will not contain a menu bar.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>noStatusBar</computeroutput>
          </term>

          <listitem>
            <para>
              VM windows will not contain a status bar.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <para>
        To disable any of these VM manager customizations do

<screen>VBoxManage setextradata global GUI/Customizations</screen>
      </para>

    </sect2>

    <sect2 id="customize-vm-selector">

      <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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>GUI/HideDetails</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the VM configuration of a certain VM. The
              details window will remain just empty if this VM is
              selected.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>GUI/PreventReconfiguration</computeroutput>
          </term>

          <listitem>
            <para>
              Do not allow the user to open the settings dialog for a
              certain VM.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>GUI/PreventSnapshotOperations</computeroutput>
          </term>

          <listitem>
            <para>
              Prevent snapshot operations for a VM from the GUI, either
              at runtime or when the VM is powered off.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>GUI/HideFromManager</computeroutput>
          </term>

          <listitem>
            <para>
              Hide a certain VM in the VM selector window.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>GUI/PreventApplicationUpdate</computeroutput>
          </term>

          <listitem>
            <para>
              Disable the automatic update check and hide the
              corresponding menu item.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <para>
        Please note that these settings would not prevent the user from
        reconfiguring the VM by <computeroutput>VBoxManage
        modifyvm</computeroutput>.
      </para>

    </sect2>

    <sect2 id="config-vm-selector-menu">

      <title>Configure VM Selector Menu Entries</title>

      <para>
        You can disable, or blacklist, 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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>General</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>General</emphasis> settings
              pane.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Input</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Input</emphasis> settings pane.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Update</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Update</emphasis> settings pane.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Language</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Language</emphasis> settings
              pane.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Display</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Display</emphasis> settings
              pane.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Network</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Network</emphasis> settings
              pane.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Extensions</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Extensions</emphasis> settings
              pane.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Proxy</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Proxy</emphasis> settings pane.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <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 id="config-vm-window-menu">

      <title>Configure VM Window Menu Entries</title>

      <para>
        You can disable, or blacklist, 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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>All</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show any menu in the VM window.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Machine</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Machine</emphasis> menu in the
              VM window.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>View</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>View</emphasis> menu in the VM
              window.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Devices</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Devices</emphasis> menu in the
              VM window.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Help</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Help</emphasis> menu in the VM
              window.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Debug</computeroutput>
          </term>

          <listitem>
            <para>
              Do not 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>
          </listitem>
        </varlistentry>

      </variablelist>

      <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, or blacklist, certain menu actions of
        certain menus. Use the following command to disable certain
        actions of the <emphasis>Application</emphasis> menu. This is
        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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>All</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show any menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>About</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>About</emphasis> menu item in
              this menu.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>All</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show any menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>SettingsDialog</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Settings</emphasis> menu item in
              this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>TakeSnapshot</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Take Snapshot</emphasis> menu
              item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>TakeScreenshot</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Take Screenshot</emphasis> menu
              item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>InformationDialog</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Session Information</emphasis>
              menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>MouseIntegration</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Disable Mouse
              Integration</emphasis> menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>TypeCAD</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Insert Ctrl+Alt+Del</emphasis>
              menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>TypeCABS</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Insert
              Ctrl+Alt+Backspace</emphasis> menu item in this menu.
              Available on X11 hosts only.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Pause</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Pause</emphasis> menu item in
              this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Reset</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Reset</emphasis> menu item in
              this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>SaveState</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Save the machine
              state</emphasis> menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Shutdown</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>ACPI Shutdown</emphasis> menu
              item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>PowerOff</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Power Off the machine</emphasis>
              menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>All</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show any menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Fullscreen</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Switch to Fullscreen</emphasis>
              menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Seamless</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Switch to Seamless
              Mode</emphasis> menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Scale</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Switch to Scaled Mode</emphasis>
              menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>GuestAutoresize</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Auto-resize Guest
              Display</emphasis> menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>AdjustWindow</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Adjust Window Size</emphasis>
              menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Multiscreen</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Multiscreen</emphasis> menu item
              in this menu. Only visible in full screen/seamless mode.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>All</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show any menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>OpticalDevices</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>CD/DVD Devices</emphasis> menu
              item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>FloppyDevices</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Floppy Devices</emphasis> menu
              item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>USBDevices</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>USB Devices</emphasis> menu item
              in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>SharedClipboard</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Shared Clipboard</emphasis> menu
              item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>DragAndDrop</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Drag and Drop</emphasis> menu
              item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>NetworkSettings</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Network Settings...</emphasis>
              menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>SharedFoldersSettings</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Shared Folders
              Settings...</emphasis> menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>VRDEServer</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Remove Display</emphasis> menu
              item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>InstallGuestTools</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Insert Guest Additions CD
              image...</emphasis> menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <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, which is normally completely
        disabled:
      </para>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>All</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show any menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Statistics</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Statistics...</emphasis> menu
              item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>CommandLine</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Command Line...</emphasis> menu
              item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Logging</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Logging...</emphasis> menu item
              in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>LogDialog</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Show Log...</emphasis> menu item
              in this menu.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <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, which is normally completely
        disabled:
      </para>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>All</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show any menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Contents</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Contents...</emphasis> menu item
              in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>WebSite</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>VirtualBox Web
              Site...</emphasis> menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>ResetWarnings</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Reset All Warnings</emphasis>
              menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>NetworkAccessManager</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Network Operations
              Manager</emphasis> menu item in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>About</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>About</emphasis> menu item in
              this menu. Only for non-Mac OS X hosts.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Contents</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Contents...</emphasis> menu item
              in this menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Contents</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the <emphasis>Contents...</emphasis> menu item
              in this menu.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <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 id="config-vm-window-status-bar">

      <title>Configure VM Window Status Bar Entries</title>

      <para>
        You can disable, or blacklist, 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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>HardDisks</computeroutput>
          </term>

          <listitem>
            <para>
              Do not 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>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>OpticalDisks</computeroutput>
          </term>

          <listitem>
            <para>
              Do not 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>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>FloppyDisks</computeroutput>
          </term>

          <listitem>
            <para>
              Do not 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>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Network</computeroutput>
          </term>

          <listitem>
            <para>
              Do not 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>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>USB</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the USB icon in the status bar.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>SharedFolders</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the shared folders icon in the status bar.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Capture</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the capture icon in the status bar.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Features</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the CPU features icon in the status bar.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Mouse</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the mouse icon in the status bar.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Keyboard</computeroutput>
          </term>

          <listitem>
            <para>
              Do not show the keyboard icon in the status bar.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <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 id="config-vm-window-visual-modes">

      <title>Configure VM Window Visual Modes</title>

      <para>
        You can disable, or blacklist, 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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>Fullscreen</computeroutput>
          </term>

          <listitem>
            <para>
              Do not allow to switch the VM into full screen mode.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Seamless</computeroutput>
          </term>

          <listitem>
            <para>
              Do not allow to switch the VM into seamless mode.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Scale</computeroutput>
          </term>

          <listitem>
            <para>
              Do not allow to switch the VM into scale mode.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <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 id="host-key-customize">

      <title>Host Key Customization</title>

      <para>
        To disable all Host key combinations, open the preferences and
        change the Host key to None. 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>
        <xref linkend="table-host-key-customize"/> shows the possible
        Host key actions, together with their default Host key shortcut.
        Setting an action to None will disable that Host key action.
      </para>

      <table id="table-host-key-customize">
        <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 id="terminate-vm-action">

      <title>Action when Terminating the VM</title>

      <para>
        You can disallow, or blacklist, 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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>SaveState</computeroutput>
          </term>

          <listitem>
            <para>
              Do not allow the user to save the VM state when
              terminating the VM.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Shutdown</computeroutput>
          </term>

          <listitem>
            <para>
              Do not allow the user to shutdown the VM by sending the
              ACPI power-off event to the guest.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>PowerOff</computeroutput>
          </term>

          <listitem>
            <para>
              Do not allow the user to power off the VM.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>PowerOffRestoringSnapshot</computeroutput>
          </term>

          <listitem>
            <para>
              Do not allow the user to return to the last snapshot when
              powering off the VM.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Detach</computeroutput>
          </term>

          <listitem>
            <para>
              Do not allow the user to detach from the VM process if the
              VM was started in separate mode.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <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 id="terminate-vm-default-action">

      <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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>SaveState</computeroutput>
          </term>

          <listitem>
            <para>
              Save the VM state before terminating the VM process.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Shutdown</computeroutput>
          </term>

          <listitem>
            <para>
              The VM is shut down by sending the ACPI power-off event to
              the guest.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>PowerOff</computeroutput>
          </term>

          <listitem>
            <para>
              The VM is powered off.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>PowerOffRestoringSnapshot</computeroutput>
          </term>

          <listitem>
            <para>
              The VM is powered off and the saved state returns to the
              last snapshot.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Detach</computeroutput>
          </term>

          <listitem>
            <para>
              Terminate the frontend but leave the VM process running.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <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 id="guru-meditation-action">

      <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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>Default</computeroutput>
          </term>

          <listitem>
            <para>
              A message window is shown. After the user confirmed, the
              VM is terminated.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>PowerOff</computeroutput>
          </term>

          <listitem>
            <para>
              The VM is immediately powered-off without showing any
              message window. The VM logfile will show information about
              what happened.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Ignore</computeroutput>
          </term>

          <listitem>
            <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>
          </listitem>
        </varlistentry>

      </variablelist>

      <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 has not yet started the VirtualBox
        Guest Additions. For instance, the guest is booting or the Guest
        Additions are not installed, or if the pointing device is
        configured as a 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>

      <variablelist>

        <varlistentry>
          <term>
            <computeroutput>Default</computeroutput>
          </term>

          <listitem>
            <para>
              The default behavior as described above.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>HostComboOnly</computeroutput>
          </term>

          <listitem>
            <para>
              The mouse is only captured if the Host Key is toggled.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <computeroutput>Disabled</computeroutput>
          </term>

          <listitem>
            <para>
              The mouse is never captured, also not by toggling the Host
              Key
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <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). 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 Web Service via init</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
        <xref linkend="table-websrv-config-params"/> all start with the
        <computeroutput>VBOXWEB_</computeroutput> prefix string. For
        example: <computeroutput>VBOXWEB_HOST</computeroutput> and
        <computeroutput>VBOXWEB_PORT</computeroutput>.

        <table id="table-websrv-config-params">
          <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 do not 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>
        <xref linkend="table-websrv-config-params"/> showing the
        parameter names and defaults also applies for Solaris. The
        parameter names must be changed to lowercase and a prefix of
        <computeroutput>config/</computeroutput> has to be added. For
        example: <computeroutput>config/user</computeroutput> or
        <computeroutput>config/ssl_keyfile</computeroutput>. If you make
        any change, do not 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 are
        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 Web Service 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:
      </para>

      <para>
        <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>.
      </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 as follows:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          Memory ballooning control, which automatically takes care of a
          VM's configured memory balloon. See
          <xref linkend="guestadd-balloon" />. This service 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>
      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
        the command line with:

<screen>--balloon-max &lt;Size in MB&gt;</screen>

        or 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>

        The default ballooning increment is 256 MB if not specified.
      </para>

      <para>
        The same options apply for a ballooning decrement. Using the
        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>

        The 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:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <computeroutput>none</computeroutput>. This has no effect.
          </para>
        </listitem>

        <listitem>
          <para>
            <computeroutput>pause</computeroutput>. Pauses the execution
            of a VM.
          </para>
        </listitem>

        <listitem>
          <para>
            <computeroutput>poweroff</computeroutput>. 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>. 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>. 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>

    </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 init</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>.
      </para>

      <para>
        The parameters in
        <xref linkend="table-vboxwatchdog-config-params"/> all start
        with the <computeroutput>VBOXWATCHDOG_</computeroutput> prefix
        string. For example:
        <computeroutput>VBOXWATCHDOG_BALLOON_INTERVAL</computeroutput>
        and <computeroutput>VBOXWATCHDOG_LOGSIZE</computeroutput>.
        Legacy parameters such as
        <computeroutput>VBOXBALLOONCTRL_INTERVAL</computeroutput> can
        still be used.

        <table id="table-vboxwatchdog-config-params">
          <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 do not have to if the defaults already match
        your needs:
      </para>

<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>
        <xref linkend="table-vboxwatchdog-config-params"/> also applies
        for Solaris. The parameter names must be changed to lowercase
        and a prefix of <computeroutput>config/</computeroutput> has to
        be added. For example:
        <computeroutput>config/user</computeroutput> or
        <computeroutput>config/balloon_safetymargin</computeroutput>. If
        you made any change, do not 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 with 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 init</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" />. For
        example:

<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:
      </para>

      <para>
        <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>.
      </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>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Host Suspends.</emphasis> 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>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Host Resumes.</emphasis> 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>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Battery Low.</emphasis> 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>
      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="sse412passthrough">

    <title>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. The instruction sets are exposed
      to guests by default, but it is possible to disable the instructions
      for certain guests using the following commands:</para>
<screen>VBoxManage setextradata "VM name" VBoxInternal/CPUM/IsaExts/SSE4.1 0
VBoxManage setextradata "VM name" VBoxInternal/CPUM/IsaExts/SSE4.2 0</screen>

    <para>
      These are a per-VM settings which are turned on 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 emulated keyboard when the machine window is
      selected. It is currently implemented for Mac OS X and Windows
      hosts. The feature is enabled by default (on a supported host OS),
      but can be disabled using the following command:
    </para>

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

    <para>
      This is a per-VM setting and it is enabled 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 setextradata "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 setextradata "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-bit
      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 of Disk Encryption</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 does not 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 does not 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>

        <para>
          <emphasis role="bold">Prerequisites</emphasis>
        </para>

        <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>

        <para>
          <emphasis role="bold">VM and Guest Configuration</emphasis>
        </para>

        <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. For example::
            </para>

            <para>
<screen>VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1,address=192.168.32.1,port=55000"</screen>
            </para>

            <para>
              See <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 <emphasis role="bold">File</emphasis> menu,
              select <emphasis role="bold">Kernel Debug</emphasis>. On
              the NET tab, specify the UDP port number you used in the
              <computeroutput>paravirtdebug</computeroutput> options. If
              you did not 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>
              Click <emphasis role="bold">OK</emphasis> 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>

      </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 the system speaker, is a way to
      produce audible feedback such as beeps without the need for
      regular audio and 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 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. These are summarized in
      <xref linkend="table-pcspeaker-config"/>.
    </para>

    <table id="table-pcspeaker-config">
      <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>
      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 is not 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>
        This 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. 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>

  <xi:include href="user_isomakercmd-man.xml"    xmlns:xi="http://www.w3.org/2001/XInclude" />

</chapter>