horok/virtualbox
1
0
Fork 0
Code Activity
virtualbox/doc/manual/en_US/user_AdvancedTopics.xml
Daniel Baumann df1bda4fe9
Adding upstream version 7.0.20-dfsg. 
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
2025-06-22 09:56:04 +02:00

7676 lines
247 KiB
XML
Raw Permalink Blame History

<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (C) 2006-2023 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>
View git blame Copy permalink