diff options
Diffstat (limited to 'doc/manual/en_US/user_AdvancedTopics.xml')
| -rw-r--r-- | doc/manual/en_US/user_AdvancedTopics.xml | 7676 |
1 files changed, 7676 insertions, 0 deletions
diff --git a/doc/manual/en_US/user_AdvancedTopics.xml b/doc/manual/en_US/user_AdvancedTopics.xml new file mode 100644 index 00000000..3069578c --- /dev/null +++ b/doc/manual/en_US/user_AdvancedTopics.xml @@ -0,0 +1,7676 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2022 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="AdvancedTopics"> + + <title>Advanced Topics</title> + + <sect1 id="autologon"> + + <title>Automated Guest Logins</title> + + <para> + &product-name; provides Guest Addition modules for Windows, Linux, + and Oracle Solaris to enable automated logins on the guest. + </para> + + <para> + When a guest operating system is running in a virtual machine, it + might be desirable to perform coordinated and automated logins + using credentials passed from the host. Credentials are user name, + password, and domain name, where each value might be empty. + </para> + + <sect2 id="autologon_win"> + + <title>Automated Windows Guest Logins</title> + + <para> + Windows provides a modular system login subsystem, called + Winlogon, which can be customized and extended by means of + so-called GINA (Graphical Identification and Authentication) + modules. In Windows Vista and later releases, the GINA modules + were replaced with a new mechanism called credential providers. + The &product-name; Guest Additions for Windows come with both, a + GINA and a credential provider module, and therefore enable any + Windows guest to perform automated logins. + </para> + + <para> + To activate the &product-name; GINA or credential provider + module, install the Guest Additions using the command line + switch <option>/with_autologon</option>. All the following + manual steps required for installing these modules will be then + done by the installer. + </para> + + <para> + To manually install the &product-name; GINA module, extract the + Guest Additions as shown in + <xref linkend="windows-guest-file-extraction" />, and copy the + <filename>VBoxGINA.dll</filename> file to the Windows + <filename>SYSTEM32</filename> directory. In the registry, create + the following key with a value of + <filename>VBoxGINA.dll</filename>: + </para> + +<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen> + + <note> + <para> + The &product-name; GINA module is implemented as a wrapper + around the <filename>MSGINA.DLL</filename> standard Windows + GINA module. As a result, it might not work correctly with + third-party GINA modules. + </para> + </note> + + <para> + To manually install the &product-name; credential provider + module, extract the Guest Additions as shown in + <xref linkend="windows-guest-file-extraction" /> and copy the + <filename>VBoxCredProv.dll</filename> file to the Windows + <filename>SYSTEM32</filename> directory. In the registry, create + the following keys: + </para> + +<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\ +Authentication\Credential Providers\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B} + +HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B} + +HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32</screen> + + <para> + All default values, the key named <literal>Default</literal>, + must be set to <literal>VBoxCredProv</literal>. + </para> + + <para> + Create the following string and assign it a value of + <literal>Apartment</literal>. + </para> + +<screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen> + + <para> + To set credentials, use the following command on a + <emphasis>running</emphasis> VM: + </para> + +<screen>$ VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</screen> + + <para> + While the VM is running, the credentials can be queried by the + &product-name; login modules, GINA or credential provider, using + the &product-name; Guest Additions device driver. When Windows + is in <emphasis>logged out</emphasis> mode, the login modules + will constantly poll for credentials and if they are present, a + login will be attempted. After retrieving the credentials, the + login modules will erase them so that the above command will + have to be repeated for subsequent logins. + </para> + + <para> + For security reasons, credentials are not stored in any + persistent manner and will be lost when the VM is reset. Also, + the credentials are write-only. There is no way to retrieve the + credentials from the host side. Credentials can be reset from + the host side by setting empty values. + </para> + + <para> + Depending on the Windows guest version, the following + restrictions apply: + </para> + + <itemizedlist> + + <listitem> + <para> + For <emphasis role="bold">Windows XP guests.</emphasis> The + login subsystem needs to be configured to use the classic + login dialog, as the &product-name; GINA module does not + support the Windows XP-style welcome dialog. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Windows Vista, Windows 7, Windows 8, + and Windows 10 guests.</emphasis> The login subsystem does + not support the so-called Secure Attention Sequence, + <literal>Ctrl+Alt+Del</literal>. As a result, the guest's + group policy settings need to be changed to not use the + Secure Attention Sequence. Also, the user name given is only + compared to the true user name, not the user friendly name. + This means that when you rename a user, you still have to + supply the original user name as Windows never renames user + accounts internally. + </para> + </listitem> + + <listitem> + <para> + Automatic login handling of the built-in + <emphasis role="bold">Windows Remote Desktop + Service</emphasis>, formerly known as Terminal Services, is + disabled by default. To enable it, create the following + registry key with a <literal>DWORD</literal> value of + <literal>1</literal>. + </para> + +<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen> + </listitem> + + </itemizedlist> + + <para> + The following command forces &product-name; to keep the + credentials after they were read by the guest and on VM reset: + </para> + +<screen>$ VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</screen> + + <para> + Note that this is a potential security risk, as a malicious + application running on the guest could request this information + using the proper interface. + </para> + + </sect2> + + <sect2 id="autologon_unix"> + + <title>Automated Linux and UNIX Guest Logins</title> + + <para> + &product-name; provides a custom PAM module (Pluggable + Authentication Module) which can be used to perform automated + guest logins on platforms which support this framework. + Virtually all modern Linux and UNIX distributions rely on PAM. + </para> + + <para> + For automated logins on Ubuntu, or Ubuntu-derived, distributions + using LightDM as the display manager. See + <xref linkend="autologon_unix_lightdm" />. + </para> + + <para> + The <filename>pam_vbox.so</filename> module itself + <emphasis>does not</emphasis> do an actual verification of the + credentials passed to the guest OS. Instead it relies on other + modules such as <filename>pam_unix.so</filename> or + <filename>pam_unix2.so</filename> down in the PAM stack to do + the actual validation using the credentials retrieved by + <filename>pam_vbox.so</filename>. Therefore + <filename>pam_vbox.so</filename> has to be on top of the + authentication PAM service list. + </para> + + <note> + <para> + The <filename>pam_vbox.so</filename> module only supports the + <literal>auth</literal> primitive. Other primitives such as + <literal>account</literal>, <literal>session</literal>, or + <literal>password</literal> are not supported. + </para> + </note> + + <para> + The <filename>pam_vbox.so</filename> module is shipped as part + of the Guest Additions but it is not installed and/or activated + on the guest OS by default. In order to install it, it has to be + copied from + <filename>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/other/</filename> + to the security modules directory. This is usually + <filename>/lib/security/</filename> on 32-bit Linux guests or + <filename>/lib64/security/</filename> on 64-bit Linux guests. + Please refer to your guest OS documentation for the correct PAM + module directory. + </para> + + <para> + For example, to use <filename>pam_vbox.so</filename> with a + Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM) to log + in users automatically with the credentials passed by the host, + configure the guest OS as follows: + </para> + + <orderedlist> + + <listitem> + <para> + Copy the <filename>pam_vbox.so</filename> module to the + security modules directory. In this case, + <filename>/lib/security</filename>. + </para> + </listitem> + + <listitem> + <para> + Edit the PAM configuration file for GDM, found at + <filename>/etc/pam.d/gdm</filename>. Add the line + <literal>auth requisite pam_vbox.so</literal> at the top. + Additionally, in most Linux distributions there is a file + called <filename>/etc/pam.d/common-auth</filename>. This + file is included in many other services, like the GDM file + mentioned above. There you also have to add the line + <literal>auth requisite pam_vbox.so</literal>. + </para> + </listitem> + + <listitem> + <para> + If authentication against the shadow database using + <filename>pam_unix.so</filename> or + <filename>pam_unix2.so</filename> is desired, the argument + <literal>try_first_pass</literal> for + <filename>pam_unix.so</filename> or + <literal>use_first_pass</literal> for + <filename>pam_unix2.so</filename> is needed in order to pass + the credentials from the &product-name; module to the shadow + database authentication module. For Ubuntu, this needs to be + added to <filename>/etc/pam.d/common-auth</filename>, to the + end of the line referencing + <filename>pam_unix.so</filename>. This argument tells the + PAM module to use credentials already present in the stack, + such as the ones provided by the &product-name; PAM module. + </para> + </listitem> + + </orderedlist> + + <warning> + <para> + An incorrectly configured PAM stack can effectively prevent + you from logging into your guest system. + </para> + </warning> + + <para> + To make deployment easier, you can pass the argument + <literal>debug</literal> right after the + <filename>pam_vbox.so</filename> statement. Debug log output + will then be recorded using syslog. + </para> + + <note> + <para> + By default, <command>pam_vbox</command> does not wait for + credentials to arrive from the host. When a login prompt is + shown, for example by GDM/KDM or the text console, and + <command>pam_vbox</command> does not yet have credentials it + does not wait until they arrive. Instead the next module in + the PAM stack, depending on the PAM configuration, will have + the chance for authentication. + </para> + </note> + + <para> + <command>pam_vbox</command> supports various guest property + parameters that are located in + <filename>/VirtualBox/GuestAdd/PAM/</filename>. These parameters + allow <command>pam_vbox</command> to wait for credentials to be + provided by the host and optionally can show a message while + waiting for those. The following guest properties can be set: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>CredsWait</literal>: Set to 1 if + <command>pam_vbox</command> should start waiting until + credentials arrive from the host. Until then no other + authentication methods such as manually logging in will be + available. If this property is empty or gets deleted no + waiting for credentials will be performed and + <command>pam_vbox</command> will act like before. This + property must be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>CredsWaitAbort</literal>: Aborts waiting for + credentials when set to any value. Can be set from host and + the guest. + </para> + </listitem> + + <listitem> + <para> + <literal>CredsWaitTimeout</literal>: Timeout, in seconds, to + let <command>pam_vbox</command> wait for credentials to + arrive. When no credentials arrive within this timeout, + authentication of <command>pam_vbox</command> will be set to + failed and the next PAM module in chain will be asked. If + this property is not specified, set to 0 or an invalid + value, an infinite timeout will be used. This property must + be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + </itemizedlist> + + <para> + To customize <command>pam_vbox</command> further there are the + following guest properties: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>CredsMsgWaiting</literal>: Custom message showed + while pam_vbox is waiting for credentials from the host. + This property must be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>CredsMsgWaitTimeout</literal>: Custom message + showed when waiting for credentials by + <command>pam_vbox</command> has timed out. For example, they + did not arrive within time. This property must be set + read-only for the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + If a <command>pam_vbox</command> guest property does not have + the correct flag set (<literal>RDONLYGUEST</literal>) the + property is ignored and, depending on the property, a default + value will be used. This can result in pam_vbox not waiting + for credentials. Consult the appropriate syslog file for more + information and use the <literal>debug</literal> option. + </para> + </note> + + <sect3 id="autologon_unix_lightdm"> + + <title>&product-name; Greeter for Ubuntu/LightDM</title> + + <para> + &product-name; comes with a greeter module, named + <command>vbox-greeter</command>, that can be used with + LightDM. LightDM is the default display manager for Ubuntu + Linux and therefore can also be used for automated guest + logins. + </para> + + <para> + <command>vbox-greeter</command> does not need the + <command>pam_vbox</command> module described in + <xref linkend="autologon_unix"/>in order to function. It comes + with its own authentication mechanism provided by LightDM. + However, to provide maximum flexibility both modules can be + used together on the same guest. + </para> + + <para> + As with the <command>pam_vbox</command> module, + <command>vbox-greeter</command> is shipped as part of the + Guest Additions but it is not installed or activated on the + guest OS by default. To install + <command>vbox-greeter</command> automatically upon Guest + Additions installation, use the + <option>--with-autologon</option> option when starting the + <command>VBoxLinuxAdditions.run</command> file: + </para> + +<screen># ./VBoxLinuxAdditions.run -- --with-autologon</screen> + + <para> + For manual or postponed installation, copy the + <filename>vbox-greeter.desktop</filename> file from + <filename>/opt/VBoxGuestAdditions-<version>/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 + "<width>x<height>" 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 > /sys/devices/system/cpu/cpu<id>/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>"<EMPTY>"</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 <Size in MB></screen> + + <para> + Using a per-VM basis extradata value, as follows: + </para> + +<screen>VBoxManage setextradata <VM-Name> VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></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 <Size in MB></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB <Size in MB></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 <Size in MB></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB <Size in MB></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 <Size in MB></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB <Size in MB></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=<string[,stringN]></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups <string[,stringN]></screen> + + <para> + Set the host isolation timeout using the following command line: + </para> + +<screen>--apimon-isln-timeout=<ms></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS <ms></screen> + + <para> + Set the actual host isolation response using the following + command line: + </para> + +<screen>--apimon-isln-response=<cmd></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse <cmd></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> |