Adding upstream version 7.0.6-dfsg.upstream/7.0.6-dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 7676 insertions, 0 deletions

diff --git a/doc/manual/en_US/user_AdvancedTopics.xml b/doc/manual/en_US/user_AdvancedTopics.xml
new file mode 100644
index 00000000..3069578c
--- /dev/null
+++ b/doc/manual/en_US/user_AdvancedTopics.xml
@@ -0,0 +1,7676 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    Copyright (C) 2006-2022 Oracle and/or its affiliates.
+
+    This file is part of VirtualBox base platform packages, as
+    available from https://www.virtualbox.org.
+
+    This program is free software; you can redistribute it and/or
+    modify it under the terms of the GNU General Public License
+    as published by the Free Software Foundation, in version 3 of the
+    License.
+
+    This program is distributed in the hope that it will be useful, but
+    WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, see <https://www.gnu.org/licenses>.
+
+    SPDX-License-Identifier: GPL-3.0-only
+-->
+<!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="autologon">
+
+    <title>Automated Guest Logins</title>
+
+    <para>
+      &product-name; provides Guest Addition modules for Windows, Linux,
+      and Oracle Solaris to enable automated logins 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 logins
+      using credentials passed from the host. Credentials are user name,
+      password, and domain name, where each value might be empty.
+    </para>
+
+    <sect2 id="autologon_win">
+
+      <title>Automated Windows Guest Logins</title>
+
+      <para>
+        Windows provides a modular system login subsystem, called
+        Winlogon, which can be customized and extended by means of
+        so-called GINA (Graphical Identification and Authentication)
+        modules. In Windows Vista and later releases, the GINA modules
+        were replaced with a new mechanism called credential providers.
+        The &product-name; Guest Additions for Windows come with both, a
+        GINA and a credential provider module, and therefore enable any
+        Windows guest to perform automated logins.
+      </para>
+
+      <para>
+        To activate the &product-name; GINA or credential provider
+        module, install the Guest Additions using the command line
+        switch <option>/with_autologon</option>. All the following
+        manual steps required for installing these modules will be then
+        done by the installer.
+      </para>
+
+      <para>
+        To manually install the &product-name; GINA module, extract the
+        Guest Additions as shown in
+        <xref linkend="windows-guest-file-extraction" />, and copy the
+        <filename>VBoxGINA.dll</filename> file to the Windows
+        <filename>SYSTEM32</filename> directory. In the registry, create
+        the following key with a value of
+        <filename>VBoxGINA.dll</filename>:
+      </para>
+
+<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen>
+
+      <note>
+        <para>
+          The &product-name; GINA module is implemented as a wrapper
+          around the <filename>MSGINA.DLL</filename> standard Windows
+          GINA module. As a result, it might not work correctly with
+          third-party GINA modules.
+        </para>
+      </note>
+
+      <para>
+        To manually install the &product-name; credential provider
+        module, extract the Guest Additions as shown in
+        <xref linkend="windows-guest-file-extraction" /> and copy the
+        <filename>VBoxCredProv.dll</filename> file to the Windows
+        <filename>SYSTEM32</filename> directory. In the registry, create
+        the following keys:
+      </para>
+
+<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>
+        All default values, the key named <literal>Default</literal>,
+        must be set to <literal>VBoxCredProv</literal>.
+      </para>
+
+      <para>
+        Create the following string and assign it a value of
+        <literal>Apartment</literal>.
+      </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
+        &product-name; login modules, GINA or credential provider, using
+        the &product-name; Guest Additions device driver. When Windows
+        is in <emphasis>logged out</emphasis> mode, the login modules
+        will constantly poll for credentials and if they are present, a
+        login will be attempted. After retrieving the credentials, the
+        login modules will erase them so that the above command will
+        have to be repeated for subsequent logins.
+      </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 Windows guest version, the following
+        restrictions apply:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            For <emphasis role="bold">Windows XP guests.</emphasis> The
+            login subsystem needs to be configured to use the classic
+            login dialog, as the &product-name; GINA module does not
+            support the Windows XP-style welcome dialog.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Windows Vista, Windows 7, Windows 8,
+            and Windows 10 guests.</emphasis> The login subsystem does
+            not support the so-called Secure Attention Sequence,
+            <literal>Ctrl+Alt+Del</literal>. 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>
+            Automatic login 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 <literal>DWORD</literal> value of
+            <literal>1</literal>.
+          </para>
+
+<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        The following command forces &product-name; to keep the
+        credentials after they were read by the guest and on VM reset:
+      </para>
+
+<screen>$ VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</screen>
+
+      <para>
+        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 Logins</title>
+
+      <para>
+        &product-name; provides a custom PAM module (Pluggable
+        Authentication Module) which can be used to perform automated
+        guest logins on platforms which support this framework.
+        Virtually all modern Linux and UNIX distributions rely on PAM.
+      </para>
+
+      <para>
+        For automated logins on Ubuntu, or Ubuntu-derived, distributions
+        using LightDM as the display manager. See
+        <xref linkend="autologon_unix_lightdm" />.
+      </para>
+
+      <para>
+        The <filename>pam_vbox.so</filename> 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 <filename>pam_unix.so</filename> or
+        <filename>pam_unix2.so</filename> down in the PAM stack to do
+        the actual validation using the credentials retrieved by
+        <filename>pam_vbox.so</filename>. Therefore
+        <filename>pam_vbox.so</filename> has to be on top of the
+        authentication PAM service list.
+      </para>
+
+      <note>
+        <para>
+          The <filename>pam_vbox.so</filename> module only supports the
+          <literal>auth</literal> primitive. Other primitives such as
+          <literal>account</literal>, <literal>session</literal>, or
+          <literal>password</literal> are not supported.
+        </para>
+      </note>
+
+      <para>
+        The <filename>pam_vbox.so</filename> 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
+        <filename>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/other/</filename>
+        to the security modules directory. This is usually
+        <filename>/lib/security/</filename> on 32-bit Linux guests or
+        <filename>/lib64/security/</filename> on 64-bit Linux guests.
+        Please refer to your guest OS documentation for the correct PAM
+        module directory.
+      </para>
+
+      <para>
+        For example, to use <filename>pam_vbox.so</filename> with a
+        Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM) to log
+        in users automatically with the credentials passed by the host,
+        configure the guest OS as follows:
+      </para>
+
+      <orderedlist>
+
+        <listitem>
+          <para>
+            Copy the <filename>pam_vbox.so</filename> module to the
+            security modules directory. In this case,
+            <filename>/lib/security</filename>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Edit the PAM configuration file for GDM, found at
+            <filename>/etc/pam.d/gdm</filename>. Add the line
+            <literal>auth requisite pam_vbox.so</literal> at the top.
+            Additionally, in most Linux distributions there is a file
+            called <filename>/etc/pam.d/common-auth</filename>. This
+            file is included in many other services, like the GDM file
+            mentioned above. There you also have to add the line
+            <literal>auth requisite pam_vbox.so</literal>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            If authentication against the shadow database using
+            <filename>pam_unix.so</filename> or
+            <filename>pam_unix2.so</filename> is desired, the argument
+            <literal>try_first_pass</literal> for
+            <filename>pam_unix.so</filename> or
+            <literal>use_first_pass</literal> for
+            <filename>pam_unix2.so</filename> is needed in order to pass
+            the credentials from the &product-name; module to the shadow
+            database authentication module. For Ubuntu, this needs to be
+            added to <filename>/etc/pam.d/common-auth</filename>, to the
+            end of the line referencing
+            <filename>pam_unix.so</filename>. This argument tells the
+            PAM module to use credentials already present in the stack,
+            such as the ones provided by the &product-name; 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
+        <literal>debug</literal> right after the
+        <filename>pam_vbox.so</filename> statement. Debug log output
+        will then be recorded using syslog.
+      </para>
+
+      <note>
+        <para>
+          By default, <command>pam_vbox</command> does 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
+          <command>pam_vbox</command> 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>
+        <command>pam_vbox</command> supports various guest property
+        parameters that are located in
+        <filename>/VirtualBox/GuestAdd/PAM/</filename>. These parameters
+        allow <command>pam_vbox</command> 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>
+            <literal>CredsWait</literal>: Set to 1 if
+            <command>pam_vbox</command> 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
+            <command>pam_vbox</command> will act like before. This
+            property must be set read-only for the guest
+            (<literal>RDONLYGUEST</literal>).
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal>CredsWaitAbort</literal>: Aborts waiting for
+            credentials when set to any value. Can be set from host and
+            the guest.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal>CredsWaitTimeout</literal>: Timeout, in seconds, to
+            let <command>pam_vbox</command> wait for credentials to
+            arrive. When no credentials arrive within this timeout,
+            authentication of <command>pam_vbox</command> 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
+            (<literal>RDONLYGUEST</literal>).
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        To customize <command>pam_vbox</command> further there are the
+        following guest properties:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <literal>CredsMsgWaiting</literal>: Custom message showed
+            while pam_vbox is waiting for credentials from the host.
+            This property must be set read-only for the guest
+            (<literal>RDONLYGUEST</literal>).
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal>CredsMsgWaitTimeout</literal>: Custom message
+            showed when waiting for credentials by
+            <command>pam_vbox</command> has timed out. For example, they
+            did not arrive within time. This property must be set
+            read-only for the guest (<literal>RDONLYGUEST</literal>).
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <note>
+        <para>
+          If a <command>pam_vbox</command> guest property does not have
+          the correct flag set (<literal>RDONLYGUEST</literal>) 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 <literal>debug</literal> option.
+        </para>
+      </note>
+
+      <sect3 id="autologon_unix_lightdm">
+
+        <title>&product-name; Greeter for Ubuntu/LightDM</title>
+
+        <para>
+          &product-name; comes with a greeter module, named
+          <command>vbox-greeter</command>, that can be used with
+          LightDM. LightDM is the default display manager for Ubuntu
+          Linux and therefore can also be used for automated guest
+          logins.
+        </para>
+
+        <para>
+          <command>vbox-greeter</command> does not need the
+          <command>pam_vbox</command> module described in
+          <xref linkend="autologon_unix"/>in order to function. It comes
+          with its own authentication mechanism provided by LightDM.
+          However, to provide maximum flexibility both modules can be
+          used together on the same guest.
+        </para>
+
+        <para>
+          As with the <command>pam_vbox</command> module,
+          <command>vbox-greeter</command> is shipped as part of the
+          Guest Additions but it is not installed or activated on the
+          guest OS by default. To install
+          <command>vbox-greeter</command> automatically upon Guest
+          Additions installation, use the
+          <option>--with-autologon</option> option when starting the
+          <command>VBoxLinuxAdditions.run</command> file:
+        </para>
+
+<screen># ./VBoxLinuxAdditions.run -- --with-autologon</screen>
+
+        <para>
+          For manual or postponed installation, copy the
+          <filename>vbox-greeter.desktop</filename> file from
+          <filename>/opt/VBoxGuestAdditions-&lt;version&gt;/other/</filename>
+          to the <filename>xgreeters</filename> directory, which is
+          usually <filename>/usr/share/xgreeters/</filename>. See your
+          guest OS documentation for the name of the correct LightDM
+          greeter directory.
+        </para>
+
+        <para>
+          The <command>vbox-greeter</command> module is installed by the
+          &product-name; Guest Additions installer and is located in
+          <filename>/usr/sbin/</filename>. To enable
+          <command>vbox-greeter</command> as the standard greeter
+          module, edit the file
+          <filename>/etc/lightdm/lightdm.conf</filename> as follows:
+        </para>
+
+<screen>[SeatDefaults]
+greeter-session=vbox-greeter</screen>
+
+        <note>
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                The LightDM server must be fully restarted in order for
+                <command>vbox-greeter</command> to be used as the
+                default greeter. As <literal>root</literal> on Ubuntu,
+                run <command>service lightdm --full-restart</command> or
+                restart the guest.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <command>vbox-greeter</command> is independent of the
+                graphical session you choose, such as Gnome, KDE, or
+                Unity. However, <command>vbox-greeter</command> does
+                require FLTK 1.3 or later to implement 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
+          <command>pam_vbox</command>. See
+          <xref linkend="autologon_unix" />.
+        </para>
+
+        <para>
+          In addition to the previously mentioned guest properties,
+          <command>vbox-greeter</command> enables you to further
+          customize its user interface. The following guest properties
+          are located in the
+          <filename>/VirtualBox/GuestAdd/Greeter/</filename> directory:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <literal>HideRestart</literal>: Set to 1 if
+              <command>vbox-greeter</command> should hide the button to
+              restart the guest. This property must be set read-only for
+              the guest (<literal>RDONLYGUEST</literal>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <literal>HideShutdown</literal>: Set to 1 if
+              <command>vbox-greeter</command> should hide the button to
+              shutdown the guest. This property must be set read-only
+              for the guest (<literal>RDONLYGUEST</literal>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <literal>BannerPath</literal>: Path to a
+              <filename>.PNG</filename> file to use as a banner image on
+              the top of the greeter. The image size must be 460 x 90
+              pixels, any bit depth. This property must be set read-only
+              for the guest (<literal>RDONLYGUEST</literal>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <literal>UseTheming</literal>: Set to 1 for turning on the
+              following theming options. This property must be set
+              read-only for the guest (<literal>RDONLYGUEST</literal>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <literal>Theme/BackgroundColor</literal>: Hexadecimal
+              RRGGBB color for the background. This property must be set
+              read-only for the guest (<literal>RDONLYGUEST</literal>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <literal>Theme/LogonDialog/HeaderColor</literal>:
+              Hexadecimal RRGGBB foreground color for the header text.
+              This property must be set read-only for the guest
+              (<literal>RDONLYGUEST</literal>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <literal>Theme/LogonDialog/BackgroundColor</literal>:
+              Hexadecimal RRGGBB color for the login dialog background.
+              This property must be set read-only for the guest
+              (<literal>RDONLYGUEST</literal>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <literal>Theme/LogonDialog/ButtonColor</literal>:
+              Hexadecimal RRGGBB background color for the login dialog
+              button. This property must be set read-only for the guest
+              (<literal>RDONLYGUEST</literal>).
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <note>
+          <para>
+            The same restrictions for the guest properties above apply
+            as for the ones specified in the <literal>pam_vbox</literal>
+            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>
+        Microsoft offers a system preparation tool called Sysprep, to
+        prepare a Windows system for deployment or redistribution. Some
+        Windows releases include Sysprep on the installation medium, but
+        the tool is also available for download from the Microsoft web
+        site. In a standard For most Windows versions, Sysprep is
+        included in a default installation. Sysprep mainly consists of
+        an executable called <command>sysprep.exe</command> which is
+        invoked by the user to put the Windows installation into
+        preparation mode.
+      </para>
+
+      <para>
+        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
+        <literal>sysprep</literal> as the program to execute, along with
+        the user name <literal>sysprep</literal> and password
+        <literal>sysprep</literal> for the credentials. Sysprep is then
+        started with the required system rights.
+      </para>
+
+      <note>
+        <para>
+          Specifying the location of <command>sysprep.exe</command> is
+          <emphasis role="bold">not possible</emphasis>. Instead the
+          following paths are used, based on the Windows release:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <filename>C:\sysprep\sysprep.exe</filename> for Windows XP
+              and earlier
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <filename>%WINDIR%\System32\sysprep\sysprep.exe</filename>
+              for Windows Vista and later
+            </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 Oracle Solaris Guests</title>
+
+    <sect2 id="linux-guest-manual-setup">
+
+      <title>Manual Setup of Selected Guest Services on Linux</title>
+
+      <para>
+        The &product-name; Guest Additions contain several different
+        drivers. If you do not want to configure them all, use the
+        following command to install the Guest Additions:
+      </para>
+
+<screen>$ sh ./VBoxLinuxAdditions.run no_setup</screen>
+
+      <para>
+        After running this script, run the <command>rcvboxadd
+        setup</command> command as <literal>root</literal> to compile
+        the kernel modules.
+      </para>
+
+      <para>
+        On some 64-bit guests, you must replace <filename>lib</filename>
+        with <filename>lib64</filename>. On older guests that do not run
+        the <command>udev</command> service, you must add the
+        <command>vboxadd</command> service to the default runlevel to
+        ensure that the modules are loaded.
+      </para>
+
+      <para>
+        To set up the time synchronization service, add the
+        <command>vboxadd-service</command> service to the default
+        runlevel. To set up the X11 and OpenGL part of the Guest
+        Additions, run the <command>rcvboxadd-x11 setup</command>
+        command. Note that you do not need to enable additional
+        services.
+      </para>
+
+      <para>
+        Use the <command>rcvboxadd setup</command> to recompile the
+        guest kernel modules.
+      </para>
+
+      <para>
+        After compilation, reboot your guest to ensure that the new
+        modules are loaded.
+      </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 &product-name; Guest Additions includes drivers for X.Org.
+        By default these drivers are in the following directory:
+      </para>
+
+      <para>
+        <filename>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/other/</filename>
+      </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 <literal>vboxvideo</literal> driver. Many recent X
+        server versions look for it automatically if they see that they
+        are running in &product-name;. For an optimal user experience,
+        the guest kernel drivers must be loaded and the Guest Additions
+        tool <command>VBoxClient</command> must be running as a client
+        in the X session.
+      </para>
+
+      <para>
+        For mouse integration to work correctly, the guest kernel
+        drivers must be loaded. In addition, for legacy X servers the
+        correct <literal>vboxmouse</literal> driver must be loaded and
+        associated with <filename>/dev/mouse</filename> or
+        <filename>/dev/psaux</filename>. For most guests, a driver for a
+        PS/2 mouse must be loaded and the correct vboxmouse driver must
+        be associated with <filename>/dev/vboxguest</filename>.
+      </para>
+
+      <para>
+        The &product-name; 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. 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 legacy X Servers before version 1.3, you can also add your
+        own modes to the X server configuration file. 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,
+      &product-name; supports CPU hot-plugging.
+    </para>
+
+    <para>
+      On a physical computer CPU hot-plugging would mean that a CPU can
+      be added or removed while the machine is running. &product-name;
+      supports adding and removing of virtual CPUs while a virtual
+      machine is running.
+    </para>
+
+    <para>
+      CPU hot-plugging works only with guest operating systems that
+      support the feature. So far this applies only to Linux and Windows
+      Server. Windows supports only hot-add, while Linux supports
+      hot-add and hot-remove. To use this feature with more than 8 CPUs,
+      a 64-bit Linux guest is required.
+    </para>
+
+    <para>
+      CPU hot-plugging is done using the <command>VBoxManage</command>
+      command-line interface. First, hot-plugging needs to be enabled
+      for a virtual machine:
+    </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --cpu-hotplug on</screen>
+
+    <para>
+      The <option>--cpus</option> option is used to specify the maximum
+      number of CPUs that the virtual machine can have:
+    </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --cpus 8</screen>
+
+    <para>
+      When the VM is off, you can then add and remove virtual CPUs with
+      the <command>VBoxManage modifyvm --plug-cpu</command> and
+      <command>VBoxManage modifyvm --unplug-cpu</command> commands,
+      which take the number of the virtual CPU as a parameter, as
+      follows:
+    </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --plug-cpu 3
+$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --unplug-cpu 3</screen>
+
+    <para>
+      Note that CPU 0 can never be removed.
+    </para>
+
+    <para>
+      While the VM is running, CPUs can be added and removed with the
+      <command>VBoxManage controlvm plugcpu</command> and
+      <command>VBoxManage controlvm unplugcpu</command> commands
+      instead, as follows:
+    </para>
+
+<screen>$ VBoxManage controlvm <replaceable>VM-name</replaceable> plugcpu 3
+$ VBoxManage controlvm <replaceable>VM-name</replaceable> unplugcpu 3</screen>
+
+    <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 kernel version later than
+      <literal>2.6.31</literal>, experimental host PCI devices
+      passthrough is available.
+    </para>
+
+    <note>
+      <para>
+        The PCI passthrough module is shipped as an &product-name;
+        extension package, which must be installed separately. See
+        <xref linkend="intro-installing" />.
+      </para>
+    </note>
+
+    <para>
+      This feature enables 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 &product-name;
+      depends upon an IOMMU hardware unit. 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 <literal>CONFIG_DMAR</literal> kernel
+          compilation option. The PCI stub driver
+          (<literal>CONFIG_PCI_STUB</literal>) is required as well.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Your Linux kernel recognizes and uses the IOMMU unit. The
+          <literal>intel_iommu=on</literal> 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
+      <command>lspci</command> 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
+      <literal><replaceable>bus</replaceable>:<replaceable>device</replaceable>.<replaceable>function</replaceable></literal>.
+      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 <replaceable>VM-name</replaceable> -\-pciattach 02:00.0@01:05.0</screen>
+
+    <para>
+      To detach the same device, use:
+    </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> -\-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 on the host, and during BIOS PCI init on the
+      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>
+        &product-name; includes a feature called <emphasis>webcam
+        passthrough</emphasis>, which enables a guest to use a host
+        webcam. This complements the general USB passthrough support
+        which was the typical way of using host webcams in legacy
+        releases. 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
+          &product-name; 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 the
+        <emphasis role="bold">Devices</emphasis> menu in the VM menu
+        bar. The <emphasis role="bold">Webcams</emphasis> 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 <command>VBoxManage</command> 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, as follows:
+          </para>
+
+<screen>VBoxManage controlvm <replaceable>VM name</replaceable> webcam attach [<replaceable>host_path</replaceable>|<replaceable>alias</replaceable> [<replaceable>settings</replaceable>]]</screen>
+
+          <para>
+            This attaches a USB webcam device to the guest.
+          </para>
+
+          <para>
+            The <literal>settings</literal> parameter is a string
+            <literal>Setting1=Value1;Setting2=Value2</literal>, which
+            enables you to configure the emulated webcam device. The
+            following settings are supported:
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <literal>MaxFramerate</literal>: 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>
+                <literal>MaxPayloadTransferSize</literal>: 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
+                <literal>MaxPayloadTransferSize</literal> might be not
+                supported by some guests.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para>
+            Detach a webcam from a running VM, as follows:
+          </para>
+
+<screen>VBoxManage controlvm <replaceable>VM-name</replaceable> webcam detach [<replaceable>host_path</replaceable>|<replaceable>alias</replaceable>]</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            List the webcams attached to a running VM, as follows:
+          </para>
+
+<screen>VBoxManage controlvm <replaceable>VM-name</replaceable> webcam list</screen>
+
+          <para>
+            The output contains the path or alias which was used in the
+            <command>webcam attach</command> 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>macOS Hosts</title>
+
+      <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 <command>VBoxManage controlvm
+        <replaceable>VM-name</replaceable> webcam detach</command>
+        command.
+      </para>
+
+    </sect2>
+
+    <sect2 id="webcam-linux-hosts">
+
+      <title>Linux and Oracle 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 <command>VBoxManage
+        controlvm <replaceable>VM-name</replaceable> webcam
+        detach</command> command.
+      </para>
+
+      <para>
+        Aliases <filename>.0</filename> and <filename>.1</filename> are
+        mapped to <filename>/dev/video0</filename>, alias
+        <filename>.2</filename> is mapped to
+        <filename>/dev/video1</filename> 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 &product-name;
+        VESA BIOS enables you to add up to 16 custom video modes which
+        will be reported to the guest operating system. When using
+        Windows guests with the &product-name; 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<replaceable>x</replaceable></literal>
+        with <replaceable>x</replaceable> 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 <replaceable>VM-name</replaceable> "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 to be supplied
+        to Linux:
+      </para>
+
+<screen>vga = 0x200 | 0x160
+vga = 864</screen>
+
+      <para>
+        For guest operating systems with &product-name; 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 &product-name;
+        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
+        <command>VBoxManage</command>. This behavior is what most users
+        will want, but if you have different needs, you can change it by
+        issuing one of the following commands from the command line:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Remove all limits on guest resolutions.
+          </para>
+
+<screen>VBoxManage setextradata global GUI/MaxGuestResolution any</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Manually specify a maximum resolution.
+          </para>
+
+<screen>VBoxManage setextradata global GUI/MaxGuestResolution <replaceable>width</replaceable>x<replaceable>height</replaceable></screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Restore the default settings to all guest VMs.
+          </para>
+
+<screen>VBoxManage setextradata global GUI/MaxGuestResolution auto</screen>
+        </listitem>
+
+      </itemizedlist>
+
+    </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>
+        As an alternative to using virtual disk images as described in
+        <xref linkend="storage" />, &product-name; can also present
+        either entire physical hard disks or selected partitions as
+        virtual disks to virtual machines.
+      </para>
+
+      <para>
+        With &product-name;, this type of access is called <emphasis>raw
+        hard disk access</emphasis>. It enables 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 compared to 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 Virtual
+        Media Manager, see <xref linkend="virtual-media-manager" />, or
+        <command>VBoxManage</command> 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
+          following command:
+        </para>
+
+<screen>$ VBoxManage createmedium disk --filename <replaceable>path-to-file</replaceable>.vmdk --format=VMDK
+ --variant RawDisk --property RawDrive=/dev/sda</screen>
+
+        <para>
+          This creates the
+          <filename><replaceable>path-to-file</replaceable>.vmdk</filename>
+          file image that must be an absolute path. All data is read and
+          written from <filename>/dev/sda</filename>.
+        </para>
+
+        <para>
+          On a Windows host, instead of the above device specification,
+          for example use <filename>\\.\PhysicalDrive0</filename>. On a
+          macOS host, instead of the above device specification use for
+          example <filename>/dev/rdisk1</filename>. Note that on Mac 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, 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:
+        </para>
+
+<screen>$ VBoxManage storageattach WindowsXP --storagectl "IDE Controller" \
+ --port 0 --device 0 --type hdd --medium <replaceable>path-to-file</replaceable>.vmdk</screen>
+
+        <para>
+          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 createmedium disk --filename <replaceable>path-to-file</replaceable>.vmdk --format=VMDK
+--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5</screen>
+
+        <para>
+          The command is identical to the one for full hard disk access,
+          except for the additional <option>--property
+          Partitions=1,5</option> parameter. This example would create
+          the image
+          <filename><replaceable>path-to-file</replaceable>.vmdk</filename>,
+          which must be absolute, and partitions 1 and 5 of
+          <filename>/dev/sda</filename> would be made accessible to the
+          guest.
+        </para>
+
+        <para>
+          &product-name; 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 for example <filename>\\.\PhysicalDrive0</filename>. On a
+          macOS host, instead of the above device specification use
+          <filename>/dev/rdisk1</filename>, for example. Note that on OS
+          X you can only use partitions which are not mounted. Unmount
+          the respective disk first using <emphasis>diskutil unmountDisk
+          <filename>/dev/diskX</filename></emphasis>. Partition numbers
+          are the same on Linux, Windows, and macOS hosts.
+        </para>
+
+        <para>
+          The numbers for the list of partitions can be taken from the
+          output of the following command:
+        </para>
+
+<screen>$ VBoxManage list hostdrives</screen>
+
+        <para>
+          The output lists available drives and their partitions with
+          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 createmedium disk --filename <replaceable>path-to-file</replaceable>.vmdk --format=VMDK
+--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5
+--property Relative=1</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, <filename>/dev/sda1</filename> and
+          <filename>/dev/sda5</filename>. 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 enables for example the guest to boot directly to
+          Windows, while the host boots Linux from the "same" disk. For
+          this purpose the <option>--property-file
+          BootSector=<replaceable>path-to-file-with-boot-sector</replaceable></option>
+          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 createmedium disk --filename <replaceable>path-to-file</replaceable>.vmdk --format=VMDK
+--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5
+--property-file BootSector=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>
+        &product-name; 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 <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"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 <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model"</screen>
+
+      <para>
+        For hard disks, you can mark the drive as having a
+        non-rotational medium by using the following command:
+      </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"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 <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor"
+VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product"
+VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"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 Using Internal Networking</title>
+
+      <para>
+        As an experimental feature, &product-name; enables access to an
+        iSCSI target running in a virtual machine which is configured to
+        use 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 <replaceable>VM-name</replaceable> \
+VBoxInternal/Devices/IntNetIP/0/Trusted 1
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/TrunkType 2
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen>
+
+      <para>
+        Finally the iSCSI disk must be attached with the
+        <option>--intnet</option> option to tell the iSCSI initiator to
+        use internal networking, as follows:
+      </para>
+
+<screen>$ VBoxManage storageattach ... --medium iscsi --server 10.0.9.30 \
+--target iqn.2008-12.com.sun:sampletarget --intnet</screen>
+
+      <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="changenat">
+
+    <title>Fine Tuning the &product-name; 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 <literal>10.0.<replaceable>x</replaceable>.0/24</literal>
+        by default where <replaceable>x</replaceable> corresponds to the
+        instance of the NAT interface +2. So
+        <replaceable>x</replaceable> is 2 when there is only one NAT
+        instance active. In that case the guest is assigned to the
+        address <literal>10.0.2.15</literal>, the gateway is set to
+        <literal>10.0.2.2</literal> and the name server can be found at
+        <literal>10.0.2.3</literal>.
+      </para>
+
+      <para>
+        If the NAT network needs to be changed, use the following
+        command:
+      </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \
+--natnet1 "192.168/16"</screen>
+
+      <para>
+        This command would reserve the network addresses from
+        <literal>192.168.0.0</literal> to
+        <literal>192.168.254.254</literal> for the first NAT network
+        instance of <replaceable>VM-name</replaceable> The guest IP
+        would be assigned to <literal>192.168.0.15</literal> and the
+        default gateway could be found at
+        <literal>192.168.0.2</literal>.
+      </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 &product-name; 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:
+      </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \
+--nattftpserver1 10.0.2.2
+$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \
+--nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</screen>
+
+    </sect2>
+
+    <sect2 id="nat-adv-settings">
+
+      <title>Tuning TCP/IP Buffers for NAT</title>
+
+      <para>
+        The &product-name; NAT stack performance is often determined by
+        its interaction with the host's TCP/IP stack and the size of
+        several buffers, <literal>SO_RCVBUF</literal> and
+        <literal>SO_SNDBUF</literal>. 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:
+      </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \
+--natsettings1 16000,128,128,0,0</screen>
+
+      <para>
+        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, &product-name;'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. For example, use the following
+        command:
+      </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \
+--natbindip1 "10.45.0.2"</screen>
+
+      <para>
+        After this, all outgoing traffic will be sent through the
+        interface with the IP address 10.45.0.2. Ensure that this
+        interface is up and running before changing the NAT bind
+        address.
+      </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 <replaceable>VM-name</replaceable> --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 &product-name; NAT engine
+        to intercept DNS requests and forward them to host's resolver,
+        use the following command:
+      </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --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 enables 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 <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
+<replaceable>unique-rule-name-of-interception-rule</replaceable>/HostIP" <replaceable>IPv4</replaceable>
+
+VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
+<replaceable>unique-rule-name</replaceable>/HostName" <replaceable>hostname</replaceable></screen>
+
+        <para>
+          The following command sets a rule for mapping a pattern name
+          to a specified IP:
+        </para>
+
+<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
+<replaceable>unique-rule-name</replaceable>/HostIP" <replaceable>IPv4</replaceable>
+
+VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
+<replaceable>unique-rule-name</replaceable>/HostNamePattern" <replaceable>hostpattern</replaceable></screen>
+
+        <para>
+          The host name pattern can include the following wildcard
+          characters: pipe (<literal>|</literal>), question mark
+          (<literal>?</literal>), and asterisk (<literal>*</literal>).
+        </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 <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/all_blocked_site/HostIP" 127.0.0.1
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"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. You can change
+        the NAT mode by using the following commands:
+      </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \
+--nataliasmode1 proxyonly</screen>
+
+<screen>$ VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</screen>
+
+      <para>
+        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 &product-name; 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 <literal>pcbios</literal> by
+      <literal>efi</literal> in the keys.
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          DMI BIOS information (type 0)
+        </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor"        "BIOS Vendor"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion"       "BIOS Version"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate"   "BIOS Release Date"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor"  1
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor"  2
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4</screen>
+      </listitem>
+
+      <listitem>
+        <para>
+          DMI system information (type 1)
+        </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor"      "System Vendor"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct"     "System Product"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion"     "System Version"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial"      "System Serial"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU"         "System SKU"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily"      "System Family"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid" \
+"9852bf98-b83c-49db-a8de-182c42c7226b"</screen>
+      </listitem>
+
+      <listitem>
+        <para>
+          DMI board information (type 2)
+        </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBoardVendor"       "Board Vendor"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBoardProduct"      "Board Product"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBoardVersion"      "Board Version"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBoardSerial"       "Board Serial"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBoardAssetTag"     "Board Tag"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBoardLocInChass"   "Board Location"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiBoardBoardType"    10</screen>
+      </listitem>
+
+      <listitem>
+        <para>
+          DMI system enclosure or chassis (type 3)
+        </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiChassisVendor"     "Chassis Vendor"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiChassisType"       3
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiChassisVersion"    "Chassis Version"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiChassisSerial"     "Chassis Serial"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiChassisAssetTag"   "Chassis Tag"</screen>
+      </listitem>
+
+      <listitem>
+        <para>
+          DMI processor information (type 4)
+        </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiProcManufacturer"  "GenuineIntel"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiProcVersion"       "Pentium(R) III"</screen>
+      </listitem>
+
+      <listitem>
+        <para>
+          DMI OEM strings (type 11)
+        </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxVer"        "vboxVer_1.2.3"
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxRev"        "vboxRev_12345"</screen>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      If a DMI string is not set, the default value of &product-name; is
+      used. To set an empty string use
+      <literal>"&lt;EMPTY&gt;"</literal>.
+    </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 <literal>VERR_CFGM_NOT_STRING</literal> error. In that
+      case, use
+      <literal>"string:<replaceable>value</replaceable>"</literal>. For
+      example:
+    </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"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 the following command:
+    </para>
+
+<screen>$ dmidecode -t0</screen>
+
+    <para>
+      The DMI system information can be obtained as follows:
+    </para>
+
+<screen>$ dmidecode -t1</screen>
+
+  </sect1>
+
+  <sect1 id="changeacpicust">
+
+    <title>Configuring Custom ACPI Tables</title>
+
+    <para>
+      You can configure &product-name; to present up to four custom ACPI
+      tables to the guest. Use a command such as the following to
+      configure custom ACPI tables. Note that
+      <literal>CustomTable1</literal>, <literal>CustomTable2</literal>,
+      and <literal>CustomTable3</literal> are available in addition to
+      <literal>CustomTable0</literal>.
+    </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+"VBoxInternal/Devices/acpi/0/Config/CustomTable0" "/<replaceable>path-to-table</replaceable>.bin"</screen>
+
+    <para>
+      Configuring custom ACPI tables can for example avoid the need for
+      asking for a new product key on Windows Vista, Windows 7, Windows
+      8 and later guests. 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, &product-name; 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 <replaceable>VM-name</replaceable> "VBoxInternal/TM/TSCTiedToExecution" 1</screen>
+
+      <para>
+        To revert to the default TSC handling mode use:
+      </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "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 <replaceable>VM-name</replaceable> "VBoxInternal/TM/WarpDrivePercentage" 200</screen>
+
+      <para>
+        The above example will double the speed of the guest clock while
+      </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "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 &product-name; 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 &product-name; 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 <replaceable>VM-name</replaceable> "/VirtualBox/GuestAdd/VBoxService/<replaceable>property</replaceable>" <replaceable>value</replaceable></screen>
+
+      <para>
+        <replaceable>property</replaceable> is one of the following:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <option>--timesync-interval</option>
+          </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>
+            <option>--timesync-min-adjust</option>
+          </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>
+            <option>--timesync-latency-factor</option>
+          </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>
+            <option>--timesync-max-latency</option>
+          </term>
+
+          <listitem>
+            <para>
+              The max host timer query latency to accept. The default is
+              250 ms.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>--timesync-set-threshold</option>
+          </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>
+            <option>--timesync-set-start</option>
+          </term>
+
+          <listitem>
+            <para>
+              Set the time when starting the time sync service.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>--timesync-set-on-restore 0|1</option>
+          </term>
+
+          <listitem>
+            <para>
+              Set the time after the VM was restored from a saved state
+              when passing 1 as parameter. This is the 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 &product-name; 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 <replaceable>VM-name</replaceable> "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</screen>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="vboxbowsolaris11">
+
+    <title>Installing the Alternate Bridged Networking Driver on Oracle Solaris 11
+      Hosts</title>
+
+    <para>
+      &product-name; includes a network filter driver that utilizes
+      Oracle Solaris 11's Crossbow functionality. By default, this new
+      driver is installed for Oracle Solaris 11 hosts that have 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 &product-name; 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
+      &product-name; package:
+    </para>
+
+<screen>$ touch /etc/vboxinst_vboxbow</screen>
+
+    <para>
+      To check which driver is currently being used by &product-name;,
+      execute:
+    </para>
+
+<screen>$ modinfo | grep vbox</screen>
+
+    <para>
+      If the output contains "vboxbow", it indicates &product-name; 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>&product-name; VNIC Templates for VLANs on Oracle Solaris 11 Hosts</title>
+
+    <para>
+      &product-name; supports Virtual Network Interface (VNIC) templates
+      for configuring VMs over VLANs. An &product-name; VNIC template is
+      a VNIC whose name starts with
+      <filename>vboxvnic_template</filename>. The string is
+      case-sensitive.
+    </para>
+
+    <para>
+      On Oracle Solaris 11 hosts, when Crossbow-based bridged networking
+      is used, a VNIC template may be used to specify the VLAN ID to use
+      while bridging over a network link.
+    </para>
+
+    <para>
+      The following is an example of how to use a VNIC template to
+      configure a VM over a VLAN. Create an &product-name; 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
+      <command>nge0</command> with the VLAN ID 23. To create VNIC
+      templates that are persistent across host reboots, skip the
+      <option>-t</option> parameter in the above command. You may check
+      the current state of links using the following command:
+    </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>
+      Once the VNIC template is created, any VMs that need to be on VLAN
+      23 over the interface <command>nge0</command> 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 the <command>dladm</command> command.
+    </para>
+
+    <para>
+      VNIC templates can be created with additional properties such as
+      bandwidth limits and CPU fanout. Refer to your Oracle Solaris
+      network documentation for details. The additional properties are
+      also applied to VMs which bridge using the VNIC template.
+    </para>
+
+  </sect1>
+
+  <sect1 id="addhostonlysolaris">
+
+    <title>Configuring Multiple Host-Only Network Interfaces on Oracle Solaris
+      Hosts</title>
+
+    <para>
+      By default &product-name; provides you with one host-only network
+      interface. Adding more host-only network interfaces on Oracle
+      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
+      <filename>/platform/i86pc/kernel/drv/vboxnet.conf</filename> 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 Oracle 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 <command>ifconfig
+      vboxnet<replaceable>X</replaceable> plumb</command>, where
+      <replaceable>X</replaceable> would be 1 in this case. Once the
+      interface is plumbed, it may be configured like any other network
+      interface. Refer to the <command>ifconfig</command> 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
+      <filename>/etc/inet/netmasks</filename>, and if you are using NWAM
+      <filename>/etc/nwam/llp</filename> and add the appropriate entries
+      to set the netmask and static IP for each of those interfaces. The
+      &product-name; installer only updates these configuration files
+      for the one "vboxnet0" interface it creates by default.
+    </para>
+
+  </sect1>
+
+  <sect1 id="solariscodedumper">
+
+    <title>Configuring the &product-name; CoreDumper on Oracle Solaris Hosts</title>
+
+    <para>
+      &product-name; is capable of producing its own core files for
+      extensive debugging when things go wrong. Currently this is only
+      available on Oracle Solaris hosts.
+    </para>
+
+    <para>
+      The &product-name; CoreDumper can be enabled using the following
+      command:
+    </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> VBoxInternal2/CoreDumpEnabled 1</screen>
+
+    <para>
+      You can specify which directory to use for core dumps with this
+      command, as follows:
+    </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> VBoxInternal2/CoreDumpDir <replaceable>path-to-directory</replaceable></screen>
+
+    <para>
+      Make sure the directory you specify is on a volume with sufficient
+      free space and that the &product-name; 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 &product-name; 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 &product-name; CoreDumper should be
+      triggered. This is done using the following commands:
+    </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> VBoxInternal2/CoreDumpReplaceSystemDump 1
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> VBoxInternal2/CoreDumpLive 1</screen>
+
+    <para>
+      At least one of the above two commands will have to be provided if
+      you have enabled the &product-name; CoreDumper.
+    </para>
+
+    <para>
+      Setting <literal>CoreDumpReplaceSystemDump</literal> sets up the
+      VM to override the host's core dumping mechanism and in the event
+      of any crash only the &product-name; CoreDumper would produce the
+      core file.
+    </para>
+
+    <para>
+      Setting <literal>CoreDumpLive</literal> sets up the VM to produce
+      cores whenever the VM process receives a
+      <literal>SIGUSR2</literal> 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 the following command:
+    </para>
+
+<screen>$ kill -s SIGUSR2 <replaceable>VM-process-id</replaceable></screen>
+
+    <para>
+      The &product-name; CoreDumper creates core files of the form
+      <filename>core.vb.<replaceable>process-name</replaceable>.<replaceable>process-ID</replaceable></filename>
+      such as <filename>core.vb.VBoxHeadless.11321</filename>.
+    </para>
+
+  </sect1>
+
+  <sect1 id="vboxandsolzvmm">
+
+    <title>&product-name; and Oracle Solaris Kernel Zones</title>
+
+    <para>
+      Oracle Solaris kernel zones on x86-based systems make use of
+      hardware-assisted virtualization features like &product-name;
+      does. However, for kernel zones and &product-name; to share this
+      hardware resource, they need to cooperate.
+    </para>
+
+    <para>
+      By default, due to performance reasons, &product-name; acquires
+      the hardware-assisted virtualization resource (VT-x/AMD-V)
+      globally on the host machine and uses it until the last
+      &product-name; VM that requires it is powered off. This prevents
+      other software from using VT-x/AMD-V during the time
+      &product-name; has taken control of it.
+    </para>
+
+    <para>
+      &product-name; 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 &product-name; 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 &product-name; settings which will
+      continue to persist across host-reboots and &product-name;
+      upgrades.
+    </para>
+
+  </sect1>
+
+  <sect1 id="guitweaks">
+
+    <title>Locking Down &vbox-mgr;</title>
+
+    <sect2 id="customize-vm-manager">
+
+      <title>Customizing &vbox-mgr;</title>
+
+      <para>
+        There are several advanced customization settings for locking
+        down &vbox-mgr;. Locking down means removing some features that
+        the user should not see.
+      </para>
+
+<screen>VBoxManage setextradata global GUI/Customizations <replaceable>property</replaceable>[,<replaceable>property</replaceable> ...]</screen>
+
+      <para>
+        <replaceable>property</replaceable> is one of the following
+        properties:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>noSelector</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow users to start &vbox-mgr;. Trying to do so
+              will show a window containing a proper error message.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>noMenuBar</literal>
+          </term>
+
+          <listitem>
+            <para>
+              VM windows will not contain a menu bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>noStatusBar</literal>
+          </term>
+
+          <listitem>
+            <para>
+              VM windows will not contain a status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        To disable any of these &vbox-mgr; customizations use the
+        following command:
+      </para>
+
+<screen>$ VBoxManage setextradata global GUI/Customizations</screen>
+
+    </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 <replaceable>VM-name</replaceable> <replaceable>property</replaceable> true</screen>
+
+      <para>
+        <replaceable>property</replaceable> can be any of the following:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>GUI/HideDetails</literal>
+          </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>
+            <literal>GUI/PreventReconfiguration</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow the user to open the
+              <emphasis role="bold">Settings</emphasis> dialog for a
+              certain VM.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>GUI/PreventSnapshotOperations</literal>
+          </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>
+            <literal>GUI/HideFromManager</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Hide a certain VM in the VM selector window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>GUI/PreventApplicationUpdate</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Disable the automatic update check and hide the
+              corresponding menu item.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        Note that these settings do not prevent the user from
+        reconfiguring the VM by using the <command>VBoxManage
+        modifyvm</command> command.
+      </para>
+
+    </sect2>
+
+    <sect2 id="config-vm-selector-menu">
+
+      <title>Configure VM Selector Menu Entries</title>
+
+      <para>
+        You can disable certain entries in the global settings page of
+        the VM selector:
+      </para>
+
+<screen>$ VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages <replaceable>property</replaceable>[,<replaceable>property</replaceable>...]</screen>
+
+      <para>
+        <replaceable>property</replaceable> is one of the following:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>General</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">General</emphasis>
+              settings pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Input</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Input</emphasis>
+              settings pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Update</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Update</emphasis>
+              settings pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Language</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Language</emphasis>
+              settings pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Display</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Display</emphasis>
+              settings pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Network</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Network</emphasis>
+              settings pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Extensions</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the
+              <emphasis role="bold">Extensions</emphasis> settings pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Proxy</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Proxy</emphasis>
+              settings pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a global setting. You can specify any combination of
+        properties. To restore the default behavior, use the following
+        command:
+      </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 certain menu actions in the VM window:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus OPTION[,OPTION...]</screen>
+
+      <para>
+        where <literal>OPTION</literal> is one of the following
+        keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>All</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu in the VM window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Application</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show
+              <emphasis role="bold">Application/File</emphasis> menu in
+              the VM window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Machine</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Machine</emphasis>
+              menu in the VM window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>View</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">View</emphasis> menu
+              in the VM window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Input</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show <emphasis role="bold">Input</emphasis> menu in
+              the VM window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Devices</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Devices</emphasis>
+              menu in the VM window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Help</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Help</emphasis> menu
+              in the VM window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Debug</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">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 or global setting. Any combination of the above
+        is allowed. To restore the default behavior, use the following
+        command:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus</screen>
+
+      <para>
+        You can also disable certain menu actions of certain menus. Use
+        the following command to disable certain actions of the
+        <emphasis role="bold">Application</emphasis> menu. This is only
+        available on macOS hosts.
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <literal>OPTION</literal> is one of the following
+        keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>All</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>About</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">About</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Preferences</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the
+              <emphasis role="bold">Preferences</emphasis> menu item in
+              this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>NetworkAccessManager</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Network Operations
+              Manager</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>ResetWarnings</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Reset All
+              Warnings</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Close</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Close</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM or global setting. Any combination of the above
+        is allowed. To restore the default behavior, use the following
+        command:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus</screen>
+
+      <para>
+        Use the following command to disable certain actions of the
+        <emphasis role="bold">Machine</emphasis> menu:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMachineMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <literal>OPTION</literal> is one of the following
+        keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>All</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>SettingsDialog</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Settings</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>TakeSnapshot</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Take
+              Snapshot...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>InformationDialog</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Session
+              Information...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>FileManagerDialog</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">File
+              Manager...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Pause</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Pause</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Reset</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Reset</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Shutdown</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">ACPI
+              Shutdown</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM or global setting. Any combination of the above
+        is allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMachineMenuActions</screen>
+
+      <para>
+        Use the following command to disable certain actions of the
+        <emphasis role="bold">View</emphasis> menu:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeViewMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <literal>OPTION</literal> is one of the following
+        keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>All</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Fullscreen</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Full-screen
+              Mode</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Seamless</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Seamless
+              Mode</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Scale</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Scaled
+              Mode</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>GuestAutoresize</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Auto-resize Guest
+              Display</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>AdjustWindow</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Adjust Window
+              Size</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>TakeScreenshot</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Take
+              Screenshot...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Recording</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Recording</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>VRDEServer</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Remote
+              Display</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>MenuBar</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Menu Bar</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>MenuBarSettings</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Menu Bar
+              Settings...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>StatusBar</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Status
+              Bar</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>StatusbarSettings</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Statusbar
+              Settings...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM or global setting. Any combination of the above
+        is allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeViewMenuActions</screen>
+
+      <para>
+        Use the following command to disable certain actions of the
+        <emphasis role="bold">Input</emphasis> menu:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeInputMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <literal>OPTION</literal> is one of the following
+        keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>All</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Keyboard</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Keyboard</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>KeyboardSettings</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Keyboard
+              Settings...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>SoftKeyboard</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Soft
+              Keyboard...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>TypeCAD</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Insert
+              Ctrl-Alt-Del</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>TypeCABS</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Insert
+              Ctrl-Alt-Backspace</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>TypeCtrlBreak</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Insert
+              Ctrl-Break</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>TypeInsert</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Insert
+              Insert</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>TypePrintScreen</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Insert Print
+              Screen</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>TypeAltPrintScreen</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Insert Alt Print
+              Screen</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>TypeHostKeyCombo</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Insert Host Key
+              Combo</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>MouseIntegration</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the
+              <emphasis role="bold">MouseIntegration</emphasis> menu
+              item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM or global setting. Any combination of the above
+        is allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeInputMenuActions</screen>
+
+      <para>
+        Use the following command to disable certain actions of the
+        <emphasis role="bold">Devices</emphasis> menu:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDevicesMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <literal>OPTION</literal> is one of the following keywords
+        to disable actions in the
+        <emphasis role="bold">Devices</emphasis> menu:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>All</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>HardDrives</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Hard
+              Disks</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>OpticalDevices</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Optical
+              Devices</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>FloppyDevices</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Floppy
+              Drives</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Audio</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Audio</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Network</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Network</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>NetworkSettings</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Network
+              Settings</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>USBDevices</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">USB </emphasis> menu
+              item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>WebCams</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">WebCams </emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>SharedFolders</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Shared
+              Folders</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>SharedFoldersSettings</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Shared Folders
+              Settings...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>SharedClipboard</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Shared
+              Clipboard</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>DragAndDrop</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Drag and
+              Drop</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>InstallGuestTools</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Insert Guest
+              Additions CD image...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM or global or global setting. Any combination of
+        the above is allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDevicesMenuActions</screen>
+
+      <para>
+        Use the following command to disable certain actions of the
+        <emphasis role="bold">Debug</emphasis> menu:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDebuggerMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <literal>OPTION</literal> is one of the following keywords
+        to disable actions in the <emphasis>Debug</emphasis> menu, which
+        is normally completely disabled:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>All</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Statistics</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the
+              <emphasis role="bold">Statistics...</emphasis> menu item
+              in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>CommandLine</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Command
+              Line...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Logging</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the
+              <emphasis role="bold">Logging...</emphasis> menu item in
+              this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>LogDialog</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Show
+              Log...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>GuestControlConsole</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Guest Control
+              Terminal...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM or global setting. Any combination of the above
+        is allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDebuggerMenuActions</screen>
+
+      <para>
+        Use the following command to disable certain actions of the
+        <emphasis role="bold">View</emphasis> menu:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeHelpMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <literal>OPTION</literal> is one of the following keywords
+        to disable actions in the <emphasis role="bold">Help</emphasis>
+        menu, which is normally completely disabled:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>All</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Contents</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the
+              <emphasis role="bold">Contents...</emphasis> menu item in
+              this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>WebSite</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">VirtualBox Web
+              Site...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>BugTracker</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">VirtualBox Bug
+              Tracker...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Forums</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">VirtualBox
+              Forums...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Oracle</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">Oracle Web
+              Site...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>About</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis role="bold">About
+              VirtualBox...</emphasis> menu item in this menu. Only for
+              non-macOS hosts.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM or global setting. Any combination of the above
+        is allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeHelpMenuActions</screen>
+
+    </sect2>
+
+    <sect2 id="config-vm-window-status-bar">
+
+      <title>Configure VM Window Status Bar Entries</title>
+
+      <para>
+        You can disable certain status bar items:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedStatusBarIndicators OPTION[,OPTION...]</screen>
+
+      <para>
+        where <literal>OPTION</literal> is one of the following
+        keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>HardDisks</literal>
+          </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>
+            <literal>OpticalDisks</literal>
+          </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>
+            <literal>FloppyDisks</literal>
+          </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>
+            <literal>Network</literal>
+          </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>
+            <literal>USB</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the USB icon in the status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>SharedFolders</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the shared folders icon in the status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Capture</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the capture icon in the status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Features</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the CPU features icon in the status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Mouse</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the mouse icon in the status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Keyboard</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the keyboard icon in the status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM or global 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"|global GUI/RestrictedStatusBarIndicators</screen>
+
+    </sect2>
+
+    <sect2 id="config-vm-window-visual-modes">
+
+      <title>Configure VM Window Visual Modes</title>
+
+      <para>
+        You can disable certain VM visual modes:
+      </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/RestrictedVisualStates <replaceable>property</replaceable>[,<replaceable>property</replaceable>...]</screen>
+
+      <para>
+        <replaceable>property</replaceable> is one of the following:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>Fullscreen</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow to switch the VM into full screen mode.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Seamless</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow to switch the VM into seamless mode.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Scale</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow to switch the VM into scale mode.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. You can specify any combination of
+        properties. To restore the default behavior, use the following
+        command:
+      </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> 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
+        &product-name; in a kiosk mode.
+      </para>
+
+      <para>
+        To redefine or disable certain Host key actions, use the
+        following command:
+      </para>
+
+<screen>$ VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...."</screen>
+
+      <para>
+        The following table 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" tabstyle="oracle-all">
+        <title>Host Key Customization</title>
+        <tgroup cols="3">
+          <thead>
+            <row>
+              <entry><para>
+                  <emphasis role="bold">Action</emphasis>
+                </para></entry>
+              <entry><para>
+                  <emphasis role="bold">Default Key</emphasis>
+                </para></entry>
+              <entry><para>
+                  <emphasis role="bold">Action</emphasis>
+                </para></entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><para>
+                  <literal>TakeSnapshot</literal>
+                </para></entry>
+              <entry><para>
+                  T
+                </para></entry>
+              <entry><para>
+                  Take a snapshot
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>TakeScreenshot</literal>
+                </para></entry>
+              <entry><para>
+                  E
+                </para></entry>
+              <entry><para>
+                  Take a screenshot
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>MouseIntegration</literal>
+                </para></entry>
+              <entry><para>
+                  I
+                </para></entry>
+              <entry><para>
+                  Toggle mouse integration
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>TypeCAD</literal>
+                </para></entry>
+              <entry><para>
+                  Del
+                </para></entry>
+              <entry><para>
+                  Inject Ctrl+Alt+Del
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>TypeCABS</literal>
+                </para></entry>
+              <entry><para>
+                  Backspace
+                </para></entry>
+              <entry><para>
+                  Inject Ctrl+Alt+Backspace
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>Pause</literal>
+                </para></entry>
+              <entry><para>
+                  P
+                </para></entry>
+              <entry><para>
+                  Pause the VM
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>Reset</literal>
+                </para></entry>
+              <entry><para>
+                  R
+                </para></entry>
+              <entry>Hard reset the guest</entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>SaveState</literal>
+                </para></entry>
+              <entry><para></para></entry>
+              <entry><para>
+                  Save the VM state and terminate the VM
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>Shutdown</literal>
+                </para></entry>
+              <entry><para>
+                  H
+                </para></entry>
+              <entry><para>
+                  Press the virtual ACPI power button
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>PowerOff</literal>
+                </para></entry>
+              <entry><para></para></entry>
+              <entry><para>
+                  Power off the VM without saving the state
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>Close</literal>
+                </para></entry>
+              <entry><para>
+                  Q
+                </para></entry>
+              <entry><para>
+                  Show the Close VM dialog
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>FullscreenMode</literal>
+                </para></entry>
+              <entry><para>
+                  F
+                </para></entry>
+              <entry><para>
+                  Switch the VM into full screen mode
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>SeamlessMode</literal>
+                </para></entry>
+              <entry><para>
+                  L
+                </para></entry>
+              <entry><para>
+                  Switch the VM into seamless mode
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>ScaleMode</literal>
+                </para></entry>
+              <entry><para>
+                  C
+                </para></entry>
+              <entry><para>
+                  Switch the VM into scaled mode
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>GuestAutoResize</literal>
+                </para></entry>
+              <entry><para>
+                  G
+                </para></entry>
+              <entry><para>
+                  Automatically resize the guest window
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>WindowAdjust</literal>
+                </para></entry>
+              <entry><para>
+                  A
+                </para></entry>
+              <entry><para>
+                  Immediately resize the guest window
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>PopupMenu</literal>
+                </para></entry>
+              <entry><para>
+                  Home
+                </para></entry>
+              <entry><para>
+                  Show the popup menu in full screen mode and seamless
+                  mode
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>SettingsDialog</literal>
+                </para></entry>
+              <entry><para>
+                  S
+                </para></entry>
+              <entry><para>
+                  Open the VM Settings dialog
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>InformationDialog</literal>
+                </para></entry>
+              <entry><para>
+                  N
+                </para></entry>
+              <entry><para>
+                  Show the VM Session Information window
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>NetworkAdaptersDialog</literal>
+                </para></entry>
+              <entry><para></para></entry>
+              <entry><para>
+                  Show the VM Network Adapters dialog
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>SharedFoldersDialog</literal>
+                </para></entry>
+              <entry><para></para></entry>
+              <entry><para>
+                  Show the VM Shared Folders dialog
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>InstallGuestAdditions</literal>
+                </para></entry>
+              <entry><para>
+                  D
+                </para></entry>
+              <entry><para>
+                  Mount the ISO containing the Guest Additions
+                </para></entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+
+      <para>
+        To disable full screen mode and seamless mode, use the following
+        command:
+      </para>
+
+<screen>$ VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</screen>
+
+    </sect2>
+
+    <sect2 id="terminate-vm-action">
+
+      <title>Action when Terminating the VM</title>
+
+      <para>
+        You can disallow certain actions when terminating a VM. To
+        disallow specific actions, use the following command:
+      </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/RestrictedCloseActions <replaceable>property</replaceable>[,<replaceable>property</replaceable>...]</screen>
+
+      <para>
+        <replaceable>property</replaceable> is one of the following:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>SaveState</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow the user to save the VM state when
+              terminating the VM.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Shutdown</literal>
+          </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>
+            <literal>PowerOff</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow the user to power off the VM.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>PowerOffRestoringSnapshot</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow the user to return to the last snapshot when
+              powering off the VM.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Detach</literal>
+          </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. You can specify any combination of
+        properties. If all properties are specified, the VM cannot be
+        shut down.
+      </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. Use the following command:
+      </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/DefaultCloseAction <replaceable>action</replaceable></screen>
+
+      <para>
+        <replaceable>action</replaceable> is one of the following:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>SaveState</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Save the VM state before terminating the VM process.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Shutdown</literal>
+          </term>
+
+          <listitem>
+            <para>
+              The VM is shut down by sending the ACPI power-off event to
+              the guest.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>PowerOff</literal>
+          </term>
+
+          <listitem>
+            <para>
+              The VM is powered off.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>PowerOffRestoringSnapshot</literal>
+          </term>
+
+          <listitem>
+            <para>
+              The VM is powered off and the saved state returns to the
+              last snapshot.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Detach</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Terminate the frontend but leave the VM process running.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. You can specify any combination of
+        properties. If all properties are specified, the VM cannot be
+        shut down.
+      </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 as follows:
+      </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/GuruMeditationHandler <replaceable>mode</replaceable></screen>
+
+      <para>
+        <replaceable>mode</replaceable> is one of the following:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>Default</literal>
+          </term>
+
+          <listitem>
+            <para>
+              A message window is shown. After the user confirmed, the
+              VM is terminated.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>PowerOff</literal>
+          </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>
+            <literal>Ignore</literal>
+          </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 &product-name;
+        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 as follows:
+      </para>
+
+<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/MouseCapturePolicy <replaceable>mode</replaceable></screen>
+
+      <para>
+        <replaceable>mode</replaceable> is one of the following:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>Default</literal>
+          </term>
+
+          <listitem>
+            <para>
+              The default behavior as described above.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>HostComboOnly</literal>
+          </term>
+
+          <listitem>
+            <para>
+              The mouse is only captured if the Host Key is toggled.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>Disabled</literal>
+          </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>
+        &product-name; 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. &product-name; can be configured to use a
+        legacy method of switching to full-screen mode instead, by using
+        the command:
+      </para>
+
+<screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode true</screen>
+
+      <para>
+        You can go back to the default method by using the following
+        command:
+      </para>
+
+<screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode</screen>
+
+      <para>
+        This is a global setting.
+      </para>
+
+    </sect2>
+
+    <sect2 id="restrict-network-attachments">
+
+      <title>Removing Certain Modes of Networking From the GUI</title>
+
+      <para>
+        It is possible to remove networking modes from &product-name;
+        GUI. To do this, use the following command:
+      </para>
+
+<screen>VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes <replaceable>property</replaceable>[,<replaceable>property</replaceable>...]</screen>
+
+      <para>
+        <replaceable>property</replaceable> is one of the following:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <literal>NAT</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Remove the <emphasis role="bold">NAT</emphasis> option
+              from the GUI.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>NATNetwork</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Remove the <emphasis role="bold">NAT network</emphasis>
+              option from the GUI.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>BridgedAdapter</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Remove the <emphasis role="bold">Bridged
+              networking</emphasis> option from the GUI.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>InternalNetwork</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Remove the <emphasis role="bold">Internal
+              networking</emphasis> option from the GUI.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>HostOnlyAdapter</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Remove the <emphasis role="bold">Host Only
+              networking</emphasis> option from the GUI.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <literal>GenericDriver</literal>
+          </term>
+
+          <listitem>
+            <para>
+              Remove the <emphasis role="bold">Generic
+              networking</emphasis> option from the GUI.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a global setting. You can specify any combination of
+        properties. To restore the default behavior, use the following
+        command:
+      </para>
+
+<screen>VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes</screen>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="vboxwebsrv-daemon">
+
+    <title>Starting the &product-name; Web Service Automatically</title>
+
+    <para>
+      The &product-name; web service, <command>vboxwebsrv</command>, is
+      used for controlling &product-name; remotely. It is documented in
+      detail in the &product-name; Software Development Kit (SDK). See
+      <xref linkend="VirtualBoxAPI" />. Web service start scripts are
+      available for supported host operating systems. The following
+      sections describe how to use the scripts. The &product-name; web
+      service is never started automatically as a result of a standard
+      installation.
+    </para>
+
+    <sect2 id="vboxwebsrv-linux">
+
+      <title>Linux: Starting the Web Service With init</title>
+
+      <para>
+        On Linux, the web service can be automatically started during
+        host boot by adding appropriate parameters to the file
+        <filename>/etc/default/virtualbox</filename>. There is one
+        mandatory parameter, <literal>VBOXWEB_USER</literal>, which must
+        be set to the user which will later start the VMs. The
+        parameters in the following table all start with the
+        <literal>VBOXWEB_</literal> prefix string. For example:
+        <literal>VBOXWEB_HOST</literal> and
+        <literal>VBOXWEB_PORT</literal>.
+      </para>
+
+      <table id="table-websrv-config-params" tabstyle="oracle-all">
+        <title>Web Service Configuration Parameters</title>
+        <tgroup cols="3">
+          <thead>
+            <row>
+              <entry><para>
+                  <emphasis role="bold">Parameter</emphasis>
+                </para></entry>
+              <entry><para>
+                  <emphasis role="bold">Description</emphasis>
+                </para></entry>
+              <entry><para>
+                  <emphasis role="bold">Default</emphasis>
+                </para></entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><para>
+                  <literal>USER</literal>
+                </para></entry>
+              <entry><para>
+                  The user which the web service runs as
+                </para></entry>
+              <entry><para></para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>HOST</literal>
+                </para></entry>
+              <entry><para>
+                  The host to bind the web service to
+                </para></entry>
+              <entry><para>
+                  localhost
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>PORT</literal>
+                </para></entry>
+              <entry><para>
+                  The port to bind the web service to
+                </para></entry>
+              <entry><para>
+                  18083
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>SSL_KEYFILE</literal>
+                </para></entry>
+              <entry><para>
+                  Server key and certificate file, in PEM format
+                </para></entry>
+              <entry><para></para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>SSL_PASSWORDFILE</literal>
+                </para></entry>
+              <entry><para>
+                  File name for password to server key
+                </para></entry>
+              <entry><para></para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>SSL_CACERT</literal>
+                </para></entry>
+              <entry><para>
+                  CA certificate file, in PEM format
+                </para></entry>
+              <entry><para></para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>SSL_CAPATH</literal>
+                </para></entry>
+              <entry><para>
+                  CA certificate path
+                </para></entry>
+              <entry><para></para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>SSL_DHFILE</literal>
+                </para></entry>
+              <entry><para>
+                  DH file name or DH key length in bits
+                </para></entry>
+              <entry><para></para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>SSL_RANDFILE</literal>
+                </para></entry>
+              <entry><para>
+                  File containing seed for random number generator
+                </para></entry>
+              <entry><para></para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>TIMEOUT</literal>
+                </para></entry>
+              <entry><para>
+                  Session timeout in seconds, 0 disables timeouts
+                </para></entry>
+              <entry><para>
+                  300
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>CHECK_INTERVAL</literal>
+                </para></entry>
+              <entry><para>
+                  Frequency of timeout checks in seconds
+                </para></entry>
+              <entry><para>
+                  5
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>THREADS</literal>
+                </para></entry>
+              <entry><para>
+                  Maximum number of worker threads to run in parallel
+                </para></entry>
+              <entry><para>
+                  100
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>KEEPALIVE</literal>
+                </para></entry>
+              <entry><para>
+                  Maximum number of requests before a socket will be
+                  closed
+                </para></entry>
+              <entry><para>
+                  100
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>ROTATE</literal>
+                </para></entry>
+              <entry><para>
+                  Number of log files, 0 disables log rotation
+                </para></entry>
+              <entry><para>
+                  10
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>LOGSIZE</literal>
+                </para></entry>
+              <entry><para>
+                  Maximum log file size to trigger rotation, in bytes
+                </para></entry>
+              <entry><para>
+                  1MB
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>LOGINTERVAL</literal>
+                </para></entry>
+              <entry><para>
+                  Maximum time interval to trigger log rotation, in
+                  seconds
+                </para></entry>
+              <entry><para>
+                  1 day
+                </para></entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+
+      <para>
+        Setting the parameter <literal>SSL_KEYFILE</literal> 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>Oracle Solaris: Starting the Web Service With SMF</title>
+
+      <para>
+        On Oracle Solaris hosts, the &product-name; 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:
+      </para>
+
+<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>
+        The table in <xref linkend="vboxwebsrv-linux"/> showing the
+        parameter names and defaults also applies for Oracle Solaris.
+        The parameter names must be changed to lowercase and a prefix of
+        <literal>config/</literal> has to be added. For example:
+        <literal>config/user</literal> or
+        <literal>config/ssl_keyfile</literal>. If you make any change,
+        do not forget to run the following command to put the changes
+        into effect immediately:
+      </para>
+
+<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen>
+
+      <para>
+        If you forget the above command then the previous settings are
+        used when enabling the service. Check the current property
+        settings as follows:
+      </para>
+
+<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen>
+
+      <para>
+        When everything is configured correctly you can start the
+        &product-name; web service with the following command:
+      </para>
+
+<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen>
+
+      <para>
+        For more information about SMF, please refer to the Oracle
+        Solaris documentation.
+      </para>
+
+    </sect2>
+
+    <sect2 id="vboxwebsrv-osx">
+
+      <title>macOS: Starting the Web Service With launchd</title>
+
+      <para>
+        On macOS, launchd is used to start the &product-name;
+        webservice. An example configuration file can be found in
+        <filename>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</filename>.
+        It can be enabled by changing the <literal>Disabled</literal>
+        key from <literal>true</literal> to <literal>false</literal>. To
+        manually start the service use the following command:
+      </para>
+
+<screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
+
+      <para>
+        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" />.
+      </para>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="vboxwatchdog">
+
+    <title>&product-name; Watchdog</title>
+
+    <para>
+      The memory ballooning service, formerly known as
+      <command>VBoxBalloonCtrl</command>, was renamed to VBoxWatchdog.
+      This service now incorporates the following host services that are
+      meant to be run in a server environment:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Memory ballooning control.</emphasis>
+          This service 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>
+          <emphasis role="bold">Host isolation detection.</emphasis>
+          This service provides a way to detect whether the host cannot
+          reach the specific &product-name; 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 using the 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 using
+        the command line, as follows:
+      </para>
+
+<screen>--balloon-max &lt;Size in MB&gt;</screen>
+
+      <para>
+        Using a per-VM basis extradata value, as follows:
+      </para>
+
+<screen>VBoxManage setextradata &lt;VM-Name&gt; VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
+
+      <para>
+        Using a global extradata value, as follows:
+      </para>
+
+<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>
+        Setting the ballooning increment in MB can be either done using
+        command line, as follows:
+      </para>
+
+<screen>--balloon-inc &lt;Size in MB&gt;</screen>
+
+      <para>
+        Using a global extradata value, as follows:
+      </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB &lt;Size in MB&gt;</screen>
+
+      <para>
+        The default ballooning increment is 256 MB if not specified.
+      </para>
+
+      <para>
+        The same options apply for a ballooning decrement. Using the
+        command line, as follows:
+      </para>
+
+<screen>--balloon-dec &lt;Size in MB&gt;</screen>
+
+      <para>
+        Using a global extradata value, as follows:
+      </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB &lt;Size in MB&gt;</screen>
+
+      <para>
+        The default ballooning decrement is 128 MB if not specified.
+      </para>
+
+      <para>
+        The lower limit in MB for a balloon can be defined using the
+        command line, as follows:
+      </para>
+
+<screen>--balloon-lower-limit &lt;Size in MB&gt;</screen>
+
+      <para>
+        Using a global extradata value, as follows:
+      </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB &lt;Size in MB&gt;</screen>
+
+      <para>
+        The default lower limit is 128 MB 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 &product-name; 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>
+        Set the groups handled by the host isolation detection using the
+        following command line:
+      </para>
+
+<screen>--apimon-groups=&lt;string[,stringN]&gt;</screen>
+
+      <para>
+        Using a global extradata value, as follows:
+      </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups &lt;string[,stringN]&gt;</screen>
+
+      <para>
+        Set the host isolation timeout using the following command line:
+      </para>
+
+<screen>--apimon-isln-timeout=&lt;ms&gt;</screen>
+
+      <para>
+        Using a global extradata value, as follows:
+      </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS &lt;ms&gt;</screen>
+
+      <para>
+        Set the actual host isolation response using the following
+        command line:
+      </para>
+
+<screen>--apimon-isln-response=&lt;cmd&gt;</screen>
+
+      <para>
+        Using a global extradata value, as follows:
+      </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse &lt;cmd&gt;</screen>
+
+      <para>
+        The following response commands are available:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <literal>none</literal>. This has no effect.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal>pause</literal>. Pauses the execution of a VM.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal>poweroff</literal>. 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>
+            <literal>save</literal>. 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>
+            <literal>shutdown</literal>. Shuts down the VM in a gentle
+            way by sending an <literal>ACPI</literal> 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
+        <option>--help</option>.
+      </para>
+
+    </sect2>
+
+    <sect2 id="vboxwatchdog-linux">
+
+      <title>Linux: Starting the Watchdog Service With init</title>
+
+      <para>
+        On Linux, the watchdog service can be automatically started
+        during host boot by adding appropriate parameters to the file
+        <filename>/etc/default/virtualbox</filename>. There is one
+        mandatory parameter, <literal>VBOXWATCHDOG_USER</literal>, which
+        must be set to the user which will later start the VMs. For
+        backward compatibility you can also specify
+        <literal>VBOXBALLOONCTRL_USER</literal>.
+      </para>
+
+      <para>
+        The parameters in the following table all start with the
+        <literal>VBOXWATCHDOG_</literal> prefix string. For example:
+        <literal>VBOXWATCHDOG_BALLOON_INTERVAL</literal> and
+        <literal>VBOXWATCHDOG_LOGSIZE</literal>. Legacy parameters such
+        as <literal>VBOXBALLOONCTRL_INTERVAL</literal> can still be
+        used.
+      </para>
+
+      <table id="table-vboxwatchdog-config-params" tabstyle="oracle-all">
+        <title>&product-name; Watchdog Configuration Parameters</title>
+        <tgroup cols="3">
+          <thead>
+            <row>
+              <entry><para>
+                  <emphasis role="bold">Parameter</emphasis>
+                </para></entry>
+              <entry><para>
+                  <emphasis role="bold">Description</emphasis>
+                </para></entry>
+              <entry><para>
+                  <emphasis role="bold">Default</emphasis>
+                </para></entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><para>
+                  <literal>USER</literal>
+                </para></entry>
+              <entry><para>
+                  The user which the watchdog service runs as
+                </para></entry>
+              <entry><para></para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>ROTATE</literal>
+                </para></entry>
+              <entry><para>
+                  Number of log files, 0 disables log rotation
+                </para></entry>
+              <entry><para>
+                  10
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>LOGSIZE</literal>
+                </para></entry>
+              <entry><para>
+                  Maximum log file size to trigger rotation, in bytes
+                </para></entry>
+              <entry><para>
+                  1MB
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>LOGINTERVAL</literal>
+                </para></entry>
+              <entry><para>
+                  Maximum time interval to trigger log rotation, in
+                  seconds
+                </para></entry>
+              <entry><para>
+                  1 day
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>BALLOON_INTERVAL</literal>
+                </para></entry>
+              <entry><para>
+                  Interval for checking the balloon size, in
+                  milliseconds
+                </para></entry>
+              <entry><para>
+                  30000
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>BALLOON_INCREMENT</literal>
+                </para></entry>
+              <entry><para>
+                  Balloon size increment, in megabytes
+                </para></entry>
+              <entry><para>
+                  256
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>BALLOON_DECREMENT</literal>
+                </para></entry>
+              <entry><para>
+                  Balloon size decrement, in megabytes
+                </para></entry>
+              <entry><para>
+                  128
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>BALLOON_LOWERLIMIT</literal>
+                </para></entry>
+              <entry><para>
+                  Balloon size lower limit, in megabytes
+                </para></entry>
+              <entry><para>
+                  64
+                </para></entry>
+            </row>
+            <row>
+              <entry><para>
+                  <literal>BALLOON_SAFETYMARGIN</literal>
+                </para></entry>
+              <entry><para>
+                  Free memory required for decreasing the balloon size,
+                  in megabytes
+                </para></entry>
+              <entry><para>
+                  1024
+                </para></entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+
+    </sect2>
+
+    <sect2 id="vboxwatchdog-solaris">
+
+      <title>Oracle Solaris: Starting the Watchdog Service With SMF</title>
+
+      <para>
+        On Oracle Solaris hosts, the &product-name; 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 Oracle Solaris. The parameter names must be changed to
+        lowercase and a prefix of <literal>config/</literal> has to be
+        added. For example: <literal>config/user</literal> or
+        <literal>config/balloon_safetymargin</literal>. If you made any
+        change, do not forget to run the following command to put the
+        changes into effect immediately:
+      </para>
+
+<screen>svcadm refresh svc:/application/virtualbox/balloonctrl:default</screen>
+
+      <para>
+        If you forget the above command then the previous settings will
+        be used when enabling the service. Check the current property
+        settings with the following command:
+      </para>
+
+<screen>svcprop -p config svc:/application/virtualbox/balloonctrl:default</screen>
+
+      <para>
+        When everything is configured correctly you can start the
+        &product-name; watchdog service with the following command:
+      </para>
+
+<screen>svcadm enable svc:/application/virtualbox/balloonctrl:default</screen>
+
+      <para>
+        For more information about SMF, please refer to the Oracle
+        Solaris documentation.
+      </para>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="otherextpacks">
+
+    <title>Other Extension Packs</title>
+
+    <para>
+      Another extension pack called VNC is available. This extension
+      pack is open source and replaces the previous integration of the
+      VNC remote access protocol. This is experimental code, and is
+      initially available in the &product-name; 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 &product-name; 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:
+    </para>
+
+<screen>VBoxManage setproperty vrdeextpack VNC</screen>
+
+    <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:
+    </para>
+
+<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property VNCPassword=secret</screen>
+
+    <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 only as
+      secure as using clear-text passwords.
+    </para>
+
+    <para>
+      The following command switches back to VRDP, if installed:
+    </para>
+
+<screen>VBoxManage setproperty vrdeextpack "&product-name; Extension Pack"</screen>
+
+  </sect1>
+
+  <sect1 id="autostart">
+
+    <title>Starting Virtual Machines During System Boot</title>
+
+    <para>
+      You can start VMs automatically during system boot on Linux,
+      Oracle Solaris, and macOS platforms for all users.
+    </para>
+
+    <sect2 id="autostart-linux">
+
+      <title>Linux: Starting the Autostart Service With init</title>
+
+      <para>
+        On Linux, the autostart service is activated by setting two
+        variables in <filename>/etc/default/virtualbox</filename>. The
+        first one is <literal>VBOXAUTOSTART_DB</literal> 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
+        <literal>VBOXAUTOSTART_CONFIG</literal> 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 <filename>/etc/vbox</filename> and
+        contains several options. One is
+        <literal>default_policy</literal> 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
+        <literal>exception_list</literal> 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>
+
+<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>
+        Any user who wants to enable autostart for individual machines
+        must set the path to the autostart database directory with the
+        following command:
+      </para>
+
+<screen>VBoxManage setproperty autostartdbpath <replaceable>autostart-directory</replaceable></screen>
+
+    </sect2>
+
+    <sect2 id="autostart-solaris">
+
+      <title>Oracle Solaris: Starting the Autostart Service With SMF</title>
+
+      <para>
+        On Oracle Solaris hosts, the &product-name; autostart daemon is
+        integrated into the SMF framework. To enable it you must point
+        the service to an existing configuration file which has the same
+        format as on Linux, see <xref linkend="autostart-linux" />. For
+        example:
+      </para>
+
+<screen># svccfg -s svc:/application/virtualbox/autostart:default setprop \
+  config/config=/etc/vbox/autostart.cfg</screen>
+
+      <para>
+        When everything is configured correctly you can start the
+        &product-name; autostart service with the following command:
+      </para>
+
+<screen># svcadm enable svc:/application/virtualbox/autostart:default</screen>
+
+      <para>
+        For more information about SMF, see the Oracle Solaris
+        documentation.
+      </para>
+
+    </sect2>
+
+    <sect2 id="autostart-osx">
+
+      <title>macOS: Starting the Autostart Service With launchd</title>
+
+      <para>
+        On macOS, launchd is used to start the &product-name; autostart
+        service. An example configuration file can be found in
+        <filename>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</filename>.
+        To enable the service copy the file to
+        <filename>/Library/LaunchDaemons</filename> and change the
+        <literal>Disabled</literal> key from <literal>true</literal> to
+        <literal>false</literal>. Furthermore replace the second
+        parameter to an existing configuration file which has the same
+        format as on Linux, see <xref linkend="autostart-linux" />.
+      </para>
+
+      <para>
+        To manually start the service use the following command:
+      </para>
+
+<screen># launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist</screen>
+
+      <para>
+        For additional information on how launchd services can be
+        configured see:
+      </para>
+
+      <para>
+        <ulink
+      url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html" />.
+      </para>
+
+    </sect2>
+
+    <sect2 id="autostart-windows">
+
+      <title>Windows: Starting the Autostart Service</title>
+
+      <para>
+        On Windows, autostart functionality consist of two components.
+        The first component is a configuration file where the
+        administrator can both set a delayed start for the VMs and
+        temporarily disable autostarting for a particular user. The
+        configuration file should be located in a folder accessible by
+        all required users but it should have permissions allowing only
+        reading by everyone but administrators. The configuration file
+        contains several options. The <literal>default_policy</literal>
+        controls whether the autostart service allows or denies starting
+        of a VM for users that are not in the exception list. The
+        exception list starts with <literal>exception_list</literal> 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>
+
+<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>
+        The user name can be specified using the following forms:
+        "user", "domain\user", ".\user" and "user@domain". An
+        administrator must add the
+        <literal>VBOXAUTOSTART_CONFIG</literal> environment variable
+        into system variables containing the path to the configuration
+        file described above. The environment variable tells the
+        autostart services which configuration file is used.
+      </para>
+
+      <para>
+        The second component of autostart functionality is a Windows
+        service. Every instance of this works on behalf of a particular
+        user using their credentials.
+      </para>
+
+      <para>
+        To enable autostarting for a particular user, a member of the
+        administrators group must run the following command:
+      </para>
+
+<screen>VBoxAutostartSvc install --user=<replaceable>user</replaceable> [--password-file=<replaceable>password_file</replaceable>]</screen>
+
+      <para>
+        The password file should contain the password followed by a line
+        break. The rest of the file is ignored. The user will be asked
+        for a password if the password file is not specified.
+      </para>
+
+      <para>
+        To disable autostarting for particular user, a member of the
+        administrators group must run the following command:
+      </para>
+
+<screen>VBoxAutostartSvc delete --user=<replaceable>user</replaceable></screen>
+
+      <para>
+        If a user has changed their password then a member of the
+        administrators group must either reinstall the service or change
+        the service credentials using Windows Service Manager. Due to
+        Windows security policies, the autostart service cannot be
+        installed for users with empty passwords.
+      </para>
+
+      <para>
+        Finally, the user should define which VMs should be started at
+        boot. The user should run the following command for every VM
+        they wish to start at boot:
+      </para>
+
+<screen>VBoxManage modifyvm <replaceable>VM name or UUID</replaceable> --autostart-enabled on</screen>
+
+      <para>
+        The user can remove a particular VM from the VMs starting at
+        boot by running the following command:
+      </para>
+
+<screen>VBoxManage modifyvm <replaceable>VM name or UUID</replaceable> --autostart-enabled off</screen>
+
+      <note>
+        <para>
+          On Windows hosts, starting VMs via the autostart service might
+          cause some issues, as the virtual machines are starting within
+          the same session as VBoxSVC. For more information see
+          <xref linkend="vboxsvc-session-0" />.
+        </para>
+      </note>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="vmencryption">
+
+    <title>Encryption of VMs</title>
+
+    <para>
+      &product-name; enables you to transparently encrypt the VM data
+      stored in the configuration file, saved state, and EFI boot data
+      for the guest.
+    </para>
+
+    <para>
+      &product-name; uses the AES algorithm in various modes. The
+      selected mode depends on the encrypting component of the VM.
+      &product-name; supports 128-bit or 256-bit data encryption keys
+      (DEK). The DEK is stored encrypted in the VM configuration file
+      and is decrypted during VM startup.
+    </para>
+
+    <para>
+      Since the DEK is stored as part of the VM configuration file, it
+      is important that the file is kept safe. Losing the DEK means that
+      the data stored in the VM is lost irrecoverably. Having complete
+      and up to date backups of all data related to the VM is the
+      responsibility of the user.
+    </para>
+
+    <para>
+      The VM, even if it is encrypted, may contain media encrypted with
+      different passwords. To deal with this, the password for the VM
+      has a password identifier, in the same way as passwords for media.
+      The password ID is an arbitrary string which uniquely identifies
+      the password in the VM and its media. You can use the same
+      password and ID for both the VM and its media.
+    </para>
+
+    <sect2 id="vmencryption-limitations">
+
+      <title>Limitations of VM Encryption</title>
+
+      <para>
+        There are some limitations the user needs to be aware of when
+        using this feature:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Exporting appliances containing an encrypted VM is not
+            possible, because the OVF specification does not support
+            this. The VM is therefore decrypted during export.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            The DEK is kept in memory while the VM is running to be able
+            to encrypt and decrypt VM data. 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 VM, the password is passed
+            in clear text using the &product-name; API. This needs to be
+            kept in mind, especially when using third party API clients
+            which make use of the web service where the password might
+            be transmitted over the network. The use of HTTPS is
+            mandatory in such a case.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
+    <sect2 id="vmencryption-encryption">
+
+      <title>Encrypting a VM</title>
+
+      <para>
+        Encrypting a VM can be done either using &vbox-mgr; or the
+        <command>VBoxManage</command>. To encrypt an unencrypted VM with
+        <command>VBoxManage</command>, use:
+      </para>
+
+<screen>VBoxManage encryptvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> setencryption --new-password <replaceable>filename</replaceable>|- \
+--cipher <replaceable>cipher-ID</replaceable> --new-password-id <replaceable>ID</replaceable></screen>
+
+      <para>
+        To supply the encryption password, point
+        <command>VBoxManage</command> to the file where the password is
+        stored or specify <option>-</option> to let
+        <command>VBoxManage</command> prompt for the password on the
+        command line.
+      </para>
+
+      <para>
+        The cipher parameter specifies the cipher to use for encryption
+        and can be either <literal>AES-128</literal> or
+        <literal>AES-256</literal>. The appropriate mode of operation,
+        such as GCM, CTR, or XTS will be selected by the VM depending on
+        the encrypting component. The specified password identifier can
+        be freely chosen by the user and is used for correct
+        identification when supplying multiple passwords for the VM.
+      </para>
+
+    </sect2>
+
+    <sect2 id="vmencryption-addpassword">
+
+      <title>Opening the Encrypted VM</title>
+
+      <para>
+        When &product-name; has just started up the encrypted VM cannot
+        be opened and it stays inaccessible. Also, the encrypted VM
+        stays inaccessible if it was just registered without a password
+        or the password is incorrect. The user needs to provide the
+        password using &vbox-mgr; or with the following
+        <command>VBoxManage</command> command:
+      </para>
+
+<screen>VBoxManage encryptvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> addpassword --password <replaceable>filename</replaceable>|- --password-id <replaceable>ID</replaceable></screen>
+
+      <para>
+        To supply the encryption password point
+        <command>VBoxManage</command> to the file where the password is
+        stored or specify <option>-</option> to let
+        <command>VBoxManage</command> prompt for the password on the
+        command line.
+      </para>
+
+      <para>
+        If <replaceable>ID</replaceable> is the same as the password
+        identifier supplied when encrypting the VM it updates the
+        accessibility state.
+      </para>
+
+      <para>
+        To remove the entered password from the VM memory, use
+        <command>VBoxManage</command> as follows:
+      </para>
+
+<screen>VBoxManage encryptvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> removepassword <replaceable>ID</replaceable></screen>
+
+      <para>
+        If <replaceable>ID</replaceable> is the same as the password
+        identifier supplied when encrypting the VM it updates the
+        accessibility state.
+      </para>
+
+      <note>
+        <para>
+          If a machine becomes inaccessible all passwords are purged.
+          You have to add required passwords again, using the
+          <command>VBoxManage encryptvm
+          <replaceable>vmname</replaceable> addpassword</command>
+          command. See <xref linkend="vmencryption-addpassword" />.
+        </para>
+      </note>
+
+    </sect2>
+
+    <sect2 id="vmencryption-decryption">
+
+      <title>Decrypting Encrypted VMs</title>
+
+      <para>
+        In some circumstances it might be required to decrypt previously
+        encrypted VMs. This can be done in &vbox-mgr; or using
+        <command>VBoxManage</command> with the following command:
+      </para>
+
+<screen>VBoxManage encryptvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> setencryption --old-password <replaceable>file</replaceable>|-</screen>
+
+      <para>
+        The only required parameter is the password the VM was encrypted
+        with. The options are the same as for encrypting VMs.
+      </para>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="vboxexpertstoragemgmt">
+
+    <title>&product-name; Expert Storage Management</title>
+
+    <para>
+      In case the snapshot model of &product-name; 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 <replaceable>VM-name</replaceable> "VBoxInternal2/SilentReconfigureWhilePaused" 1</screen>
+
+    <para>
+      You can reconfigure storage attachments later while the VM is
+      paused by using the <command>VBoxManage storageattach</command>
+      command.
+    </para>
+
+  </sect1>
+
+  <sect1 id="hostpowertweaks">
+
+    <title>Handling of Host Power Management Events</title>
+
+    <para>
+      Some host power management events are handled by &product-name;.
+      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, &product-name; 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, &product-name; 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, &product-name; 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 by using the following commands:
+    </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+VBoxInternal/CPUM/IsaExts/SSE4.1 0
+$ VBoxManage setextradata <replaceable>VM-name</replaceable> \
+VBoxInternal/CPUM/IsaExts/SSE4.2 0</screen>
+
+    <para>
+      These are per-VM settings which are enabled by default.
+    </para>
+
+  </sect1>
+
+  <sect1 id="hidledssync">
+
+    <title>Support for Keyboard Indicator Synchronization</title>
+
+    <para>
+      This feature makes the host keyboard indicators (LEDs) match those
+      of the VM's emulated keyboard when the machine window is active.
+      It is currently implemented for macOS and Windows hosts. This
+      feature is enabled by default on supported host OSes. You can
+      disable this feature by running the following command:
+    </para>
+
+<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/HidLedsSync 0</screen>
+
+    <para>
+      This is a per-VM setting that is enabled by default.
+    </para>
+
+  </sect1>
+
+  <sect1 id="usbtrafficcapturing">
+
+    <title>Capturing USB Traffic for Selected Devices</title>
+
+    <para>
+      You can 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. &product-name; 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
+      <command>VBoxManage</command> using the following command:
+    </para>
+
+<screen>VBoxManage controlvm <replaceable>VM-name</replaceable> usbattach <replaceable>device uuid</replaceable>|<replaceable>address</replaceable> --capturefile <replaceable>filename</replaceable></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 <replaceable>VM-name</replaceable> \
+VBoxInternal/Devices/usb-ehci/0/LUN#0/Config/CaptureFilename <replaceable>filename</replaceable></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 <literal>usb-ehci</literal> with
+      <literal>usb-ohci</literal> or <literal>usb-xhci</literal>,
+      respectively.
+    </para>
+
+  </sect1>
+
+  <sect1 id="heartbeatservice">
+
+    <title>Configuring the Heartbeat Service</title>
+
+    <para>
+      &product-name; 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 &product-name; Guest Additions will send a heartbeat ping
+      every two seconds. The value in nanoseconds can be configured like
+      this:
+    </para>
+
+<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> \
+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 <replaceable>VM-name</replaceable> \
+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>
+      &product-name; enables you to transparently encrypt the data
+      stored in hard disk images 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 &product-name; and other
+      virtualization software.
+    </para>
+
+    <para>
+      &product-name; 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 &product-name; 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 using the &product-name; 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 &product-name;
+            version.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            The disk encryption feature can protect the content of the
+            disks configured for a VM only. It does not cover any other
+            data related to a VM, including saved state or the
+            configuration file itself.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
+    <sect2 id="diskencryption-encryption">
+
+      <title>Encrypting Disk Images</title>
+
+      <para>
+        Encrypting disk images can be done either using &vbox-mgr; or
+        the <command>VBoxManage</command>. While &vbox-mgr; is easier to
+        use, it works on a per VM basis and encrypts all disk images
+        attached to the specific VM. With <command>VBoxManage</command>
+        one can encrypt individual images, including all differencing
+        images. To encrypt an unencrypted medium with
+        <command>VBoxManage</command>, use:
+      </para>
+
+<screen>VBoxManage encryptmedium <replaceable>uuid</replaceable>|<replaceable>filename</replaceable> \
+--newpassword <replaceable>filename</replaceable>|- --cipher <replaceable>cipher-ID</replaceable> --newpasswordid "<replaceable>ID</replaceable></screen>
+
+      <para>
+        To supply the encryption password point
+        <command>VBoxManage</command> to the file where the password is
+        stored or specify <option>-</option> 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 <literal>AES-XTS128-PLAIN64</literal> or
+        <literal>AES-XTS256-PLAIN64</literal>. 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 &vbox-mgr;, 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 <command>VBoxManage</command> using the following
+        command:
+      </para>
+
+<screen>VBoxManage controlvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> addencpassword <replaceable>ID</replaceable> <replaceable>password</replaceable> [--removeonsuspend yes|no]</screen>
+
+      <para>
+        <replaceable>ID</replaceable> must be the same as the password
+        identifier supplied when encrypting the images.
+        <replaceable>password</replaceable> is the password used when
+        encrypting the images. Optionally, you can specify
+        <option>--removeonsuspend yes|no</option> 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 &vbox-mgr; for a complete
+        VM or using <command>VBoxManage</command> with the following
+        command:
+      </para>
+
+<screen>VBoxManage encryptmedium <replaceable>uuid</replaceable>|<replaceable>filename</replaceable> --oldpassword <replaceable>file</replaceable>|-</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>
+      This section covers 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"><literal>enabled</literal></emphasis>
+          </para>
+
+          <para>
+            Value: <literal>0</literal> or <literal>1</literal>
+          </para>
+
+          <para>
+            Default: <literal>0</literal>
+          </para>
+
+          <para>
+            Specify <literal>1</literal> to enable the Hyper-V debug
+            interface. If this key-value pair is not specified or the
+            value is not <literal>1</literal>, the Hyper-V debug
+            interface is disabled regardless of other key-value pairs
+            being present.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Key:
+            <emphasis role="bold"><literal>address</literal></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"><literal>port</literal></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"><literal>vendor</literal></emphasis>
+          </para>
+
+          <para>
+            Value: Hyper-V vendor signature reported by CPUID to the
+            guest
+          </para>
+
+          <para>
+            Default: When debugging is enabled: <literal>Microsoft
+            Hv</literal>, otherwise: <literal>VBoxVBoxVBox</literal>
+          </para>
+
+          <para>
+            Specify the Hyper-V vendor signature which is exposed to the
+            guest by CPUID. For debugging Microsoft Windows guests, it
+            is required the hypervisor reports the Microsoft vendor.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Key:
+            <emphasis role="bold"><literal>hypercallinterface</literal>
+            </emphasis>
+          </para>
+
+          <para>
+            Value: <literal>0</literal> or <literal>1</literal>
+          </para>
+
+          <para>
+            Default: <literal>0</literal>
+          </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"><literal>vsinterface</literal>
+            </emphasis>
+          </para>
+
+          <para>
+            Value: <literal>0</literal> or <literal>1</literal>
+          </para>
+
+          <para>
+            Default: When debugging is enabled, <literal>1</literal>,
+            otherwise <literal>0</literal>
+          </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. USB and IEEE 1394 are not applicable
+          for virtual machines, and Ethernet requires Windows 8 or
+          later. While a 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 can check the
+              effective paravirtualization provider for your VM with the
+              output of the following <command>VBoxManage</command>
+              command:
+            </para>
+
+<screen>$ VBoxManage showvminfo <replaceable>VM-name</replaceable></screen>
+          </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
+              <filename>kdvm.dll</filename> from a Windows 8.0
+              installation. This file is typically located in
+              <filename>C:\Windows\System32</filename>. 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>
+
+            <note>
+              <para>
+                Only Windows 8.0 ships <filename>kdvm.dll</filename>.
+                Windows 8.1 and newer Windows versions do not.
+              </para>
+            </note>
+          </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 with the following
+              <command>VBoxManage</command> command:
+            </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --paravirt-debug "enabled=1"</screen>
+
+            <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>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \
+--paravirt-debug "enabled=1,address=192.168.32.1,port=55000"</screen>
+
+            <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>
+
+<screen>bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4</screen>
+              </listitem>
+
+              <listitem>
+                <para>
+                  For a Windows 7 or Vista guest:
+                </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>
+                  The IP address and port in the
+                  <command>bcdedit</command> 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 <command>bcdedit</command>
+                  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, <command>bcdedit</command>
+                  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>
+                  Run one or more of the following commands to enable
+                  debugging for the appropriate phase or component of
+                  your Windows guest:
+                </para>
+
+<screen>bcdedit /set debug on</screen>
+
+<screen>bcdedit /set bootdebug on</screen>
+
+<screen>bcdedit /set {bootmgr} bootdebug on</screen>
+
+                <para>
+                  Please note that the <command>bootdebug</command>
+                  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
+                  <command>bcdedit</command> 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 <emphasis role="bold">NET</emphasis> tab, specify the
+              UDP port number you used in the
+              <literal>paravirtdebug</literal> 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 <emphasis role="bold">Key</emphasis> field, enter
+              <literal>1.2.3.4</literal> or the encryption key from the
+              <command>bcdedit</command> 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, to directly start a debug session, run
+              WinDbg from the command line as follows :
+            </para>
+
+<screen>windbg.exe -k net:port=50000,key=1.2.3.4</screen>
+
+            <para>
+              See the WinDbg documentation for the 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,
+      &product-name; 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 &product-name; 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. &product-name;
+      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 the
+      following table.
+    </para>
+
+    <table id="table-pcspeaker-config" tabstyle="oracle-all">
+      <title>PC Speaker Configuration Options</title>
+      <tgroup cols="3">
+        <thead>
+          <row>
+            <entry><para>
+                <emphasis role="bold">Code</emphasis>
+              </para></entry>
+            <entry><para>
+                <emphasis role="bold">Device</emphasis>
+              </para></entry>
+            <entry><para>
+                <emphasis role="bold">Notes</emphasis>
+              </para></entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry><para>
+                1
+              </para></entry>
+            <entry><para>
+                <filename>/dev/input/by-path/platform-pcspkr-event-spkr</filename>
+              </para></entry>
+            <entry><para>
+                Direct host PC speaker use.
+              </para></entry>
+          </row>
+          <row>
+            <entry><para>
+                2
+              </para></entry>
+            <entry><filename>/dev/tty</filename></entry>
+            <entry><para>
+                Uses the terminal association of the VM process. VM
+                needs to be started on a virtual console.
+              </para></entry>
+          </row>
+          <row>
+            <entry><para>
+                3
+              </para></entry>
+            <entry><para>
+                <filename>/dev/tty0</filename> or
+                <filename>/dev/vc/0</filename>
+              </para></entry>
+            <entry><para>
+                Can only be used by user <literal>root</literal> or
+                users with <literal>cap_sys_tty_config</literal>
+                capability.
+              </para></entry>
+          </row>
+          <row>
+            <entry><para>
+                9
+              </para></entry>
+            <entry><para>
+                A user-specified console or evdev device path.
+              </para></entry>
+            <entry><para>
+                As for codes 1 to 3, but with a custom device path.
+              </para></entry>
+          </row>
+          <row>
+            <entry><para>
+                70
+              </para></entry>
+            <entry><para>
+                <filename>/dev/tty</filename>
+              </para></entry>
+            <entry><para>
+                Standard beep only. Loses frequency and length. See code
+                2.
+              </para></entry>
+          </row>
+          <row>
+            <entry><para>
+                79
+              </para></entry>
+            <entry><para>
+                A user-specified terminal device path.
+              </para></entry>
+            <entry><para>
+                As for code 70, but with a custom device path.
+              </para></entry>
+          </row>
+          <row>
+            <entry><para>
+                100
+              </para></entry>
+            <entry><para>
+                All of the above.
+              </para></entry>
+            <entry><para>
+                Tries all the available codes.
+              </para></entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+
+    <para>
+      To enable PC speaker passthrough use the following command:
+    </para>
+
+<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" <replaceable>N</replaceable></screen>
+
+    <para>
+      Replace <replaceable>N</replaceable> with the code representing
+      the case you want to use. Changing this setting takes effect when
+      you next start the VM. 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, <filename>VBox.log</filename>, contains lines
+      with the prefix <literal>PIT: speaker:</literal> 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 &product-name; can
+      access the necessary device, because in a typical Linux install
+      most of them can only be accessed by user <literal>root</literal>.
+      You should follow the preferred way to persistently change this,
+      such as 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. For example, 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 &product-name;. The table above contains
+      some hints, but in general 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", which 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>
+      &product-name; 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 &product-name;
+      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, use the
+      following command to add the device server that exports the
+      devices:
+    </para>
+
+<screen>VBoxManage usbdevsource add <replaceable>unique-name</replaceable> --backend <replaceable>USBIP</replaceable> --address <replaceable>device-server</replaceable>[:<replaceable>port</replaceable>]</screen>
+
+    <para>
+      USB devices exported on the device server are then accessible
+      through &vbox-mgr; or <command>VBoxManage</command>, 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:
+    </para>
+
+<screen>$ VBoxManage usbdevsource remove <replaceable>unique-name</replaceable></screen>
+
+    <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 <filename>usbip-core.ko</filename> and
+        <filename>usbip-host.ko</filename> 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, use
+        the following command to install the required tools:
+      </para>
+
+<screen>$ apt-get install usbip-utils</screen>
+
+      <para>
+        To check whether the necessary tools are already installed use
+        the following command:
+      </para>
+
+<screen>
+$ usbip list -l
+      </screen>
+
+      <para>
+        This should produce output similar to that shown in the example
+        below:
+      </para>
+
+<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>
+        If everything is installed, the USB/IP server needs to be
+        started as <literal>root</literal> using the following command:
+      </para>
+
+<screen># usbipd -D</screen>
+
+      <para>
+        See 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 the
+        following command:
+      </para>
+
+<screen># usbip bind -b "bus identifier"</screen>
+
+      <para>
+        To export the multicard reader in the previous example:
+      </para>
+
+<screen># usbip bind -b 4-2</screen>
+
+    </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>
+
+  <sect1 id="hyperv-support">
+
+    <title>Using Hyper-V with &product-name;</title>
+
+    <para>
+      &product-name; can be used on a Windows host where Hyper-V is
+      running. This is an experimental feature.
+    </para>
+
+    <para>
+      No configuration is required. &product-name; detects Hyper-V
+      automatically and uses Hyper-V as the virtualization engine for
+      the host system. The CPU icon in the VM window status bar
+      indicates that Hyper-V is being used.
+    </para>
+
+    <note>
+      <para>
+        When using this feature, some host systems might experience
+        significant &product-name; performance degradation.
+      </para>
+    </note>
+
+  </sect1>
+
+  <sect1 id="nested-virt">
+
+    <title>Nested Virtualization</title>
+
+    <para>
+      &product-name; supports <emphasis>nested
+      virtualization</emphasis>. This feature enables the passthrough of
+      hardware virtualization functions to the guest VM. That means that
+      you can install a hypervisor, such as &product-name;, Oracle VM
+      Server or KVM, on an &product-name; guest. You can then create and
+      run VMs within the guest VM.
+    </para>
+
+    <para>
+      Hardware virtualization features not present on the host CPU will
+      not be exposed to the guest. In addition, some features such as
+      nested paging are not yet supported for passthrough to the guest.
+    </para>
+
+    <para>
+      You can enable the nested virtualization feature in one of the
+      following ways:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          From &vbox-mgr;, select the <emphasis role="bold">Enable
+          Nested VT-x/AMD-V</emphasis> check box on the
+          <emphasis role="bold">Processor</emphasis> tab. To disable the
+          feature, deselect the check box.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use the <option>--nested-hw-virt</option> option of the
+          <command>VBoxManage modifyvm</command> command to enable or
+          disable nested virtualization. See
+          <xref linkend="vboxmanage-modifyvm"/>.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="vboxsvc-session-0">
+
+    <title>VBoxSVC running in Windows Session 0</title>
+
+    <para>
+      &product-name; supports executing the VBoxSVC in Windows session
+      0. This allows VBoxSVC to run like a regular Windows service,
+      which in turn enables headless VMs to continue running even if the
+      user logs out.
+
+      <note>
+        <para>
+          This is currently an experimental feature.
+        </para>
+      </note>
+    </para>
+
+    <para>
+      The feature is disabled by default and can be enabled by creating
+      a REG_DWORD value <literal>ServerSession0</literal> in the key
+      <literal>HKEY_LOCAL_MACHINE\Software\Oracle\VirtualBox\VBoxSDS</literal>
+      of the Windows registry. Specify <literal>1</literal> as the
+      value's data to enable the feature, or <literal>0</literal> to
+      disable the feature. A host reboot is needed in order to make the
+      change effective.
+    </para>
+
+    <sect2 id="vboxsvc-session-0-known-issues">
+
+      <title>Known Issues</title>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Due to different Windows sessions having their own set of
+            resources, there might be some issues with accessing network
+            shares created in the interactive user session when at least
+            one of the &product-name; processes are running in session
+            0.
+          </para>
+
+          <para>
+            For accessing network shares within session 0, a possible
+            workaround is to establish permanent access to the share and
+            then restart the host.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
+  </sect1>
+
+  <xi:include href="user_isomakercmd-man.xml"    xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</chapter>