summaryrefslogtreecommitdiffstats
path: root/doc/manual/en_US/user_AdvancedTopics.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual/en_US/user_AdvancedTopics.xml')
-rw-r--r--doc/manual/en_US/user_AdvancedTopics.xml7676
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>