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

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

1 files changed, 1208 insertions, 0 deletions

diff --git a/doc/manual/en_US/user_Frontends.xml b/doc/manual/en_US/user_Frontends.xml
new file mode 100644
index 00000000..1a507966
--- /dev/null
+++ b/doc/manual/en_US/user_Frontends.xml
@@ -0,0 +1,1208 @@
+<?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="remotevm">
+
+  <title>Remote Virtual Machines</title>
+
+  <sect1 id="vrde">
+
+    <title>Remote Display (VRDP Support)</title>
+
+    <para>
+      &product-name; can display virtual machines remotely, meaning that
+      a virtual machine can execute on one computer even though the
+      machine will be displayed on a second computer, and the machine
+      will be controlled from there as well, as if the virtual machine
+      was running on that second computer.
+    </para>
+
+    <para>
+      For maximum flexibility, &product-name; implements remote machine
+      display through a generic extension interface called the
+      VirtualBox Remote Desktop Extension (VRDE). The base open source
+      &product-name; package only provides this interface, while
+      implementations can be supplied by third parties with
+      &product-name; extension packages, which must be installed
+      separately from the base package. See
+      <xref linkend="intro-installing" />.
+    </para>
+
+    <para>
+      Oracle provides support for the VirtualBox Remote Display Protocol
+      (VRDP) in such an &product-name; extension package.
+    </para>
+
+    <para>
+      VRDP is a backwards-compatible extension to Microsoft's Remote
+      Desktop Protocol (RDP). As a result, you can use any standard RDP
+      client to control the remote VM.
+    </para>
+
+    <para>
+      Even when the extension is installed, the VRDP server is disabled
+      by default. It can easily be enabled on a per-VM basis either from
+      &vbox-mgr; in the <emphasis role="bold">Display</emphasis>
+      settings, see <xref linkend="settings-display" />, or with the
+      <command>VBoxManage</command> command, as follows:
+    </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde on</screen>
+
+    <para>
+      By default, the VRDP server uses TCP port <literal>3389</literal>.
+      You will need to change the default port if you run more than one
+      VRDP server, since the port can only be used by one server at a
+      time. You might also need to change it on Windows hosts since the
+      default port might already be used by the RDP server that is built
+      into Windows itself. Ports 5000 through 5050 are typically not
+      used and might be a good choice.
+    </para>
+
+    <para>
+      The port can be changed either in the
+      <emphasis role="bold">Display</emphasis> settings of the graphical
+      user interface or with the <option>--vrde-port</option> option of
+      the <command>VBoxManage modifyvm</command> command. You can
+      specify a comma-separated list of ports or ranges of ports. Use a
+      dash between two port numbers to specify a range. The VRDP server
+      will bind to <emphasis>one</emphasis> of the available ports from
+      the specified list. For example, <command>VBoxManage modifyvm
+      <replaceable>VM-name</replaceable> --vrde-port
+      5000,5010-5012</command> configures the server to bind to one of
+      the ports 5000, 5010, 5011, or 5012. See
+      <xref linkend="vboxmanage-modifyvm" />.
+    </para>
+
+    <para>
+      The actual port used by a running VM can be either queried with
+      the <command>VBoxManage showvminfo</command> command or seen in
+      &vbox-mgr; on the <emphasis role="bold">Runtime</emphasis> tab of
+      the <emphasis role="bold">Session Information</emphasis> dialog,
+      which is accessible from the
+      <emphasis role="bold">Machine</emphasis> menu of the VM window.
+    </para>
+
+    <para>
+      &product-name; supports IPv6. If the host OS supports IPv6 the
+      VRDP server will automatically listen for IPv6 connections in
+      addition to IPv4.
+    </para>
+
+    <sect2 id="rdp-viewers">
+
+      <title>Common Third-Party RDP Viewers</title>
+
+      <para>
+        Since VRDP is backwards-compatible to RDP, you can use any
+        standard RDP viewer to connect to such a remote virtual machine.
+        For this to work, you must specify the IP address of your
+        <emphasis>host</emphasis> system, not of the virtual machine, as
+        the server address to connect to. You must also specify the port
+        number that the VRDP server is using.
+      </para>
+
+      <para>
+        The following examples are for the most common RDP viewers:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            On Windows, you can use the Microsoft Terminal Services
+            Connector, <command>mstsc.exe</command>, that is included
+            with Windows. Press the Windows key + R, to display the
+            <emphasis role="bold">Run</emphasis> dialog. Enter
+            <command>mstsc</command> to start the program. You can also
+            find the program in <emphasis role="bold">Start</emphasis>,
+            <emphasis role="bold">All Programs</emphasis>,
+            <emphasis role="bold">Accessories</emphasis>,
+            <emphasis role="bold">Remote Desktop Connection</emphasis>.
+            If you use the <emphasis role="bold">Run</emphasis> dialog,
+            you can enter options directly. For example:
+          </para>
+
+<screen>mstsc 1.2.3.4:3389</screen>
+
+          <para>
+            Replace <literal>1.2.3.4</literal> with the host IP address,
+            and <literal>3389</literal> with a different port, if
+            necessary.
+          </para>
+
+          <note>
+            <itemizedlist>
+
+              <listitem>
+                <para>
+                  IPv6 addresses must be enclosed in square brackets to
+                  specify a port. For example: <literal>mstsc
+                  [fe80::1:2:3:4]:3389</literal>
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  When connecting to localhost in order to test the
+                  connection, the addresses <literal>localhost</literal>
+                  and <literal>127.0.0.1</literal> might not work using
+                  <command>mstsc.exe</command>. Instead, the address
+                  <literal>127.0.0.2[:3389]</literal> has to be used.
+                </para>
+              </listitem>
+
+            </itemizedlist>
+          </note>
+        </listitem>
+
+        <listitem>
+          <para>
+            On other systems, you can use the standard open source
+            <command>rdesktop</command> program. This ships with most
+            Linux distributions.
+          </para>
+
+          <para>
+            With <command>rdesktop</command>, use a command line such as
+            the following:
+          </para>
+
+<screen>$ rdesktop -a 16 -N 1.2.3.4:3389</screen>
+
+          <para>
+            Replace <literal>1.2.3.4</literal> with the host IP address,
+            and <literal>3389</literal> with a different port, if
+            necessary. The <option>-a 16</option> option requests a
+            color depth of 16 bits per pixel, which we recommend. For
+            best performance, after installation of the guest operating
+            system, you should set its display color depth to the same
+            value. The <option>-N</option> option enables use of the
+            NumPad keys.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            You can use the Remmina remote desktop client with VRDP.
+            This application is included with some Linux distributions,
+            such as Debian and Ubuntu.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            If you run the KDE desktop, you can use
+            <command>krdc</command>, the KDE RDP viewer. A typical
+            command line is as follows:
+          </para>
+
+<screen>$ krdc rdp://1.2.3.4:3389</screen>
+
+          <para>
+            Replace <literal>1.2.3.4</literal> with the host IP address,
+            and <literal>3389</literal> with a different port, if
+            necessary. The <literal>rdp:// </literal> prefix is required
+            with <command>krdc</command> to switch it into RDP mode.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            With Sun Ray thin clients you can use
+            <command>uttsc</command>, which is part of the Sun Ray
+            Windows Connector package. See the Sun Ray documentation for
+            details.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
+    <sect2 id="vboxheadless">
+
+      <title>VBoxHeadless, the Remote Desktop Server</title>
+
+      <para>
+        While any VM started from &vbox-mgr; is capable of running
+        virtual machines remotely, it is not convenient to have to run
+        the full GUI if you never want to have VMs displayed locally in
+        the first place. In particular, if you are running server
+        hardware whose only purpose is to host VMs, and all your VMs are
+        supposed to run remotely over VRDP, then it is pointless to have
+        a graphical user interface on the server at all. This is
+        especially true for Linux or Oracle Solaris hosts, as the
+        &vbox-mgr; comes with dependencies on the Qt and SDL libraries.
+        This is inconvenient if you would rather not have the X Window
+        system on your server at all.
+      </para>
+
+      <para>
+        &product-name; therefore comes with a front-end called
+        <command>VBoxHeadless</command>, which produces no visible
+        output on the host at all, but still can optionally deliver VRDP
+        data. This front-end has no dependencies on the X Window system
+        on Linux and Oracle Solaris hosts.
+      </para>
+
+      <note>
+        <para>
+          In legacy releases of &product-name;, the headless server was
+          called <command>VBoxVRDP</command>. For backwards
+          compatibility, the &product-name; installation still includes
+          an executable with that name.
+        </para>
+      </note>
+
+      <para>
+        To start a virtual machine with <command>VBoxHeadless</command>,
+        you have the following options:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Use the <command>VBoxManage</command> command, as follows:
+          </para>
+
+<screen>$ VBoxManage startvm <replaceable>VM-name</replaceable> --type headless</screen>
+
+          <para>
+            The <option>--type</option> option causes &product-name; to
+            use <command>VBoxHeadless</command> as the front-end to the
+            internal virtualization engine, instead of the Qt front-end.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Use the <command>VBoxHeadless</command> command, as follows:
+          </para>
+
+<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></screen>
+
+          <para>
+            This way of starting the VM helps troubleshooting problems
+            reported by <command>VBoxManage startvm</command>, because
+            you can sometimes see more detailed error messages,
+            especially for early failures before the VM execution is
+            started. In normal situations <command>VBoxManage
+            startvm</command> is preferred, since it runs the VM
+            directly as a background process which has to be done
+            explicitly when directly starting with
+            <command>VBoxHeadless</command>. The full documentation of
+            the command is in <xref linkend="man_vboxheadless"/>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Start <command>VBoxHeadless</command> from &vbox-mgr;, by
+            pressing the Shift key when starting a virtual machine or by
+            selecting <emphasis role="bold">Headless Start</emphasis>
+            from the <emphasis role="bold">Machine</emphasis> menu.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        When you use the <command>VBoxHeadless</command> command to
+        start a VM, the VRDP server will be enabled according to the VM
+        configuration. You can override the VM's setting using
+        <option>--vrde</option> command line parameter. To enable the
+        VRDP server, start the VM as follows:
+      </para>
+
+<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> --vrde on</screen>
+
+      <para>
+        To disable the VRDP server:
+      </para>
+
+<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> --vrde off</screen>
+
+      <para>
+        To have the VRDP server enabled depending on the VM
+        configuration, as for other front-ends:
+      </para>
+
+<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> --vrde config</screen>
+
+      <para>
+        This command is the same as the following:
+      </para>
+
+<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></screen>
+
+      <para>
+        If you start the VM with <command>VBoxManage startvm</command>
+        then the configuration settings of the VM are always used.
+      </para>
+
+    </sect2>
+
+    <sect2 id="headless-vm-steps">
+
+      <title>Step by Step: Creating a Virtual Machine on a Headless Server</title>
+
+      <para>
+        The following instructions describe how to create a virtual
+        machine on a headless server over a network connection. This
+        example creates a virtual machine, establishes an RDP connection
+        and installs a guest operating system. All of these tasks are
+        done without having to touch the headless server. You need the
+        following prerequisites:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            &product-name; on a server machine with a supported host
+            operating system. The &product-name; Extension Pack for the
+            VRDP server must be installed, see <xref linkend="vrde"/>.
+            The procedures assume a Linux server is used.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            An ISO file accessible from the server, containing the
+            installation data for the guest operating system to install.
+            Windows XP is used in the example.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            A terminal connection to that host through which you can
+            access a command line, such as <command>ssh</command>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            An RDP viewer on the remote client. See
+            <xref linkend="rdp-viewers" /> for examples.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Note that on the server machine, since we will only use the
+        headless server, Qt and the X Window system are not required.
+      </para>
+
+      <orderedlist>
+
+        <listitem>
+          <para>
+            On the headless server, create a new virtual machine. For
+            example:
+          </para>
+
+<screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen>
+
+          <para>
+            If you do not specify <option>--register</option>, you will
+            have to manually use the <command>registervm</command>
+            command later.
+          </para>
+
+          <para>
+            You do not need to specify <option>--ostype</option>, but
+            doing so selects some sensible default values for certain VM
+            parameters. For example, the RAM size and the type of the
+            virtual network device. To get a complete list of supported
+            operating systems you can use the following command:
+          </para>
+
+<screen>VBoxManage list ostypes</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Make sure the settings for the VM are appropriate for the
+            guest operating system that we will install. For example:
+          </para>
+
+<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Create a virtual hard disk for the VM. For example, to
+            create a 10 GB virtual hard disk:
+          </para>
+
+<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Add an IDE Controller to the new VM. For example:
+          </para>
+
+<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller"
+  --add ide --controller PIIX4</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Set the VDI file you created as the first virtual hard disk
+            of the new VM. For example:
+          </para>
+
+<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
+ --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Attach the ISO file that contains the operating system
+            installation that you want to install later to the virtual
+            machine. This is done so that the VM can boot from it.
+          </para>
+
+<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
+ --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Enable the VirtualBox Remote Desktop Extension, the VRDP
+            server, as follows:
+          </para>
+
+<screen>VBoxManage modifyvm "Windows XP" --vrde on</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Start the virtual machine using the
+            <command>VBoxHeadless</command> command:
+          </para>
+
+<screen>VBoxHeadless --startvm "Windows XP"</screen>
+
+          <para>
+            If the configuration steps worked, you should see a
+            copyright notice. If you are returned to the command line,
+            then something did not work correctly.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            On the client machine, start the RDP viewer and connect to
+            the server. See <xref linkend="rdp-viewers" /> for details
+            of how to use various common RDP viewers.
+          </para>
+
+          <para>
+            The installation routine of your guest operating system
+            should be displayed in the RDP viewer.
+          </para>
+        </listitem>
+
+      </orderedlist>
+
+    </sect2>
+
+    <sect2 id="usb-over-rdp">
+
+      <title>Remote USB</title>
+
+      <para>
+        As a special feature additional to the VRDP support,
+        &product-name; also supports remote USB devices over the wire.
+        That is, an &product-name; guest that runs on one computer can
+        access the USB devices of the remote computer on which the VRDP
+        data is being displayed the same way as USB devices that are
+        connected to the actual host. This enables running of virtual
+        machines on an &product-name; host that acts as a server, where
+        a client can connect from elsewhere that needs only a network
+        adapter and a display capable of running an RDP viewer. When USB
+        devices are plugged into the client, the remote &product-name;
+        server can access them.
+      </para>
+
+      <para>
+        For these remote USB devices, the same filter rules apply as for
+        other USB devices. See <xref linkend="settings-usb" />. All you
+        have to do is specify Remote, or Any, when setting up these
+        rules.
+      </para>
+
+      <para>
+        Accessing remote USB devices is only possible if the RDP client
+        supports this extension. Some versions of
+        <command>uttsc</command>, a client tailored for the use with Sun
+        Ray thin clients, support accessing remote USB devices. RDP
+        clients for other platforms will be provided in future
+        &product-name; versions.
+      </para>
+
+      </sect2>
+
+    <sect2 id="vbox-auth">
+
+      <title>RDP Authentication</title>
+
+      <para>
+        For each virtual machine that is remotely accessible using RDP,
+        you can individually determine if and how client connections are
+        authenticated. For this, use the <command>VBoxManage
+        modifyvm</command> command with the
+        <option>--vrde-auth-type</option> option. See
+        <xref linkend="vboxmanage-modifyvm" />. The following methods of
+        authentication are available:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            The <emphasis role="bold">null</emphasis> method means that
+            there is no authentication at all. Any client can connect to
+            the VRDP server and thus the virtual machine. This is very
+            insecure and only to be recommended for private networks.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            The <emphasis role="bold">external</emphasis> method
+            provides external authentication through a special
+            authentication library. &product-name; ships with two
+            special authentication libraries:
+          </para>
+
+          <orderedlist>
+
+            <listitem>
+              <para>
+                The default authentication library,
+                <command>VBoxAuth</command>, authenticates against user
+                credentials of the hosts. Depending on the host
+                platform, this means the following:
+              </para>
+
+              <itemizedlist>
+
+                <listitem>
+                  <para>
+                    On Linux hosts, <command>VBoxAuth.so</command>
+                    authenticates users against the host's PAM system.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    On Windows hosts, <command>VBoxAuth.dll</command>
+                    authenticates users against the host's WinLogon
+                    system.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    On macOS hosts, <command>VBoxAuth.dylib</command>
+                    authenticates users against the host's directory
+                    service.
+                  </para>
+                </listitem>
+
+              </itemizedlist>
+
+              <para>
+                In other words, the external method by default performs
+                authentication with the user accounts that exist on the
+                host system. Any user with valid authentication
+                credentials is accepted. For example, the username does
+                not have to correspond to the user running the VM.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                An additional library called
+                <command>VBoxAuthSimple</command> performs
+                authentication against credentials configured in the
+                <literal>extradata</literal> section of a virtual
+                machine's XML settings file. This is probably the
+                simplest way to get authentication that does not depend
+                on a running and supported guest. The following steps
+                are required:
+              </para>
+
+              <orderedlist>
+
+                <listitem>
+                  <para>
+                    Enable <command>VBoxAuthSimple</command> with the
+                    following command:
+                  </para>
+
+<screen>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</screen>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    To enable the library for a particular VM, you must
+                    switch authentication to external, as follows:
+                  </para>
+
+<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-auth-type external</screen>
+
+                  <para>
+                    Replace <replaceable>VM-name</replaceable> with the
+                    VM name or UUID.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    You then need to configure users and passwords by
+                    writing items into the machine's extradata. Since
+                    the XML machine settings file, into whose
+                    <literal>extradata</literal> section the password
+                    needs to be written, is a plain text file,
+                    &product-name; uses hashes to encrypt passwords. The
+                    following command must be used:
+                  </para>
+
+<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxAuthSimple/users/<replaceable>user</replaceable>" <replaceable>hash</replaceable></screen>
+
+                  <para>
+                    Replace <replaceable>VM-name</replaceable> with the
+                    VM name or UUID, <replaceable>user</replaceable>
+                    with the user name who should be allowed to log in
+                    and <replaceable>hash</replaceable> with the
+                    encrypted password. The following command example
+                    obtains the hash value for the password
+                    <literal>secret</literal>:
+                  </para>
+
+<screen>$ VBoxManage internalcommands passwordhash "secret"
+2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen>
+
+                  <para>
+                    You then use <command>VBoxManage
+                    setextradata</command> to store this value in the
+                    machine's <literal>extradata</literal> section.
+                  </para>
+
+                  <para>
+                    As a combined example, to set the password for the
+                    user <literal>john</literal> and the machine
+                    <literal>My VM</literal> to
+                    <literal>secret</literal>, use this command:
+                  </para>
+
+<screen>VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john"
+    2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen>
+                </listitem>
+
+              </orderedlist>
+            </listitem>
+
+          </orderedlist>
+        </listitem>
+
+        <listitem>
+          <para>
+            The <emphasis role="bold">guest</emphasis> authentication
+            method performs authentication with a special component that
+            comes with the Guest Additions. As a result, authentication
+            is not performed on the host, but with the guest user
+            accounts.
+          </para>
+
+          <para>
+            This method is currently still in testing and not yet
+            supported.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        In addition to the methods described above, you can replace the
+        default external authentication module with any other module.
+        For this, &product-name; provides a well-defined interface that
+        enables you to write your own authentication module. This is
+        described in detail in the &product-name; Software Development
+        Kit (SDK) reference. See <xref linkend="VirtualBoxAPI" />.
+      </para>
+
+    </sect2>
+
+    <sect2 id="vrde-crypt">
+
+      <title>RDP Encryption</title>
+
+      <para>
+        RDP features data stream encryption, which is based on the RC4
+        symmetric cipher, with keys up to 128-bit. The RC4 keys are
+        replaced at regular intervals, every 4096 packets.
+      </para>
+
+      <para>
+        RDP provides the following different authentication methods:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">RDP 4</emphasis> authentication was
+            used historically. With RDP 4, the RDP client does not
+            perform any checks in order to verify the identity of the
+            server it connects to. Since user credentials can be
+            obtained using a man in the middle (MITM) attack, RDP4
+            authentication is insecure and should generally not be used.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">RDP 5.1</emphasis> authentication
+            employs a server certificate for which the client possesses
+            the public key. This way it is guaranteed that the server
+            possess the corresponding private key. However, as this
+            hard-coded private key became public some years ago, RDP 5.1
+            authentication is also insecure.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">RDP 5.2 or later</emphasis>
+            authentication uses Enhanced RDP Security, which means that
+            an external security protocol is used to secure the
+            connection. RDP 4 and RDP 5.1 use Standard RDP Security. The
+            VRDP server supports Enhanced RDP Security with TLS protocol
+            and, as a part of the TLS handshake, sends the server
+            certificate to the client.
+          </para>
+
+          <para>
+            The <literal>Security/Method</literal> VRDE property sets
+            the desired security method, which is used for a connection.
+            Valid values are as follows:
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <emphasis role="bold">Negotiate.</emphasis> Both
+                Enhanced (TLS) and Standard RDP Security connections are
+                allowed. The security method is negotiated with the
+                client. This is the default setting.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <emphasis role="bold">RDP.</emphasis> Only Standard RDP
+                Security is accepted.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <emphasis role="bold">TLS.</emphasis> Only Enhanced RDP
+                Security is accepted. The client must support TLS.
+              </para>
+
+              <para>
+                The version of OpenSSL used by &product-name; supports
+                TLS versions 1.0, 1.1, 1.2, and 1.3.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+
+          <para>
+            For example, the following command enables a client to use
+            either Standard or Enhanced RDP Security connection:
+          </para>
+
+<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> --vrde-property "Security/Method=negotiate"</screen>
+
+          <para>
+            If the <literal>Security/Method</literal> property is set to
+            either Negotiate or TLS, the TLS protocol will be
+            automatically used by the server, if the client supports
+            TLS. However, in order to use TLS the server must possess
+            the Server Certificate, the Server Private Key and the
+            Certificate Authority (CA) Certificate. The following
+            example shows how to generate a server certificate.
+          </para>
+
+          <orderedlist>
+
+            <listitem>
+              <para>
+                Create a CA self signed certificate.
+              </para>
+
+<screen>openssl req -new -x509 -days 365 -extensions v3_ca \
+  -keyout ca_key_private.pem -out ca_cert.pem</screen>
+            </listitem>
+
+            <listitem>
+              <para>
+                Generate a server private key and a request for signing.
+              </para>
+
+<screen>openssl genrsa -out server_key_private.pem
+openssl req -new -key server_key_private.pem -out server_req.pem</screen>
+            </listitem>
+
+            <listitem>
+              <para>
+                Generate the server certificate.
+              </para>
+
+<screen>openssl x509 -req -days 365 -in server_req.pem \
+  -CA ca_cert.pem -CAkey ca_key_private.pem -set_serial 01 -out server_cert.pem</screen>
+            </listitem>
+
+          </orderedlist>
+
+          <para>
+            The server must be configured to access the required files.
+            For example:
+          </para>
+
+<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> \
+  --vrde-property "Security/CACertificate=path/ca_cert.pem"</screen>
+
+<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> \
+  --vrde-property "Security/ServerCertificate=path/server_cert.pem"</screen>
+
+<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> \
+  --vrde-property "Security/ServerPrivateKey=path/server_key_private.pem"</screen>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        As the client that connects to the server determines what type
+        of encryption will be used, with <command>rdesktop</command>,
+        the Linux RDP viewer, use the <option>-4</option> or
+        <option>-5</option> options.
+      </para>
+
+    </sect2>
+
+    <sect2 id="vrde-multiconnection">
+
+      <title>Multiple Connections to the VRDP Server</title>
+
+      <para>
+        The VRDP server of &product-name; supports multiple simultaneous
+        connections to the same running VM from different clients. All
+        connected clients see the same screen output and share a mouse
+        pointer and keyboard focus. This is similar to several people
+        using the same computer at the same time, taking turns at the
+        keyboard.
+      </para>
+
+      <para>
+        The following command enables multiple connection mode:
+      </para>
+
+<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-multi-con on</screen>
+
+    </sect2>
+
+    <sect2 id="vrde-multimonitor">
+
+      <title>Multiple Remote Monitors</title>
+
+      <para>
+        To access two or more remote VM displays you have to enable the
+        VRDP multiconnection mode. See
+        <xref linkend="vrde-multiconnection"/>.
+      </para>
+
+      <para>
+        The RDP client can select the virtual monitor number to connect
+        to using the <literal>domain</literal> login parameter
+        (<option>-d</option>). If the parameter ends with
+        <literal>@</literal> followed by a number, &product-name;
+        interprets this number as the screen index. The primary guest
+        screen is selected with <literal>@1</literal>, the first
+        secondary screen is <literal>@2</literal>, and so on.
+      </para>
+
+      <para>
+        The Microsoft RDP 6 client does not let you specify a separate
+        domain name. Instead, enter
+        <literal><replaceable>domain</replaceable>\<replaceable>username</replaceable></literal>
+        in the <emphasis role="bold">Username</emphasis> field. For
+        example, <literal>@2\<replaceable>name</replaceable></literal>.
+        <replaceable>name</replaceable> must be supplied, and must be
+        the name used to log in if the VRDP server is set up to require
+        credentials. If it is not, you may use any text as the username.
+      </para>
+
+    </sect2>
+
+    <sect2 id="vrde-videochannel">
+
+      <title>VRDP Video Redirection</title>
+
+      <para>
+        The VRDP server can redirect video streams from the guest to the
+        RDP client. Video frames are compressed using the JPEG algorithm
+        allowing a higher compression ratio than standard RDP bitmap
+        compression methods. It is possible to increase the compression
+        ratio by lowering the video quality.
+      </para>
+
+      <para>
+        The VRDP server automatically detects video streams in a guest
+        as frequently updated rectangular areas. As a result, this
+        method works with any guest operating system without having to
+        install additional software in the guest. In particular, the
+        Guest Additions are not required.
+      </para>
+
+      <para>
+        On the client side, however, currently only the Windows 7 Remote
+        Desktop Connection client supports this feature. If a client
+        does not support video redirection, the VRDP server falls back
+        to regular bitmap updates.
+      </para>
+
+      <para>
+        The following command enables video redirection:
+      </para>
+
+<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-video-channel on</screen>
+
+      <para>
+        The quality of the video is defined as a value from 10 to 100
+        percent, representing a JPEG compression level, where lower
+        numbers mean lower quality but higher compression. The quality
+        can be changed using the following command:
+      </para>
+
+<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-video-channel-quality 75</screen>
+
+    </sect2>
+
+    <sect2 id="vrde-customization">
+
+      <title>VRDP Customization</title>
+
+      <para>
+        You can disable display output, mouse and keyboard input, audio,
+        remote USB, or clipboard individually in the VRDP server.
+      </para>
+
+      <para>
+        The following commands change the corresponding server settings:
+      </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableDisplay=1
+$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableInput=1
+$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableUSB=1
+$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableAudio=1
+$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableClipboard=1
+$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableUpstreamAudio=1</screen>
+
+      <para>
+        To reenable a feature, use a similar command without the
+        trailing 1. For example:
+      </para>
+
+<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableDisplay=</screen>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="teleporting">
+
+    <title>Teleporting</title>
+
+    <para>
+      &product-name; supports <emphasis>teleporting</emphasis>.
+      Teleporting is moving a virtual machine over a network from one
+      &product-name; host to another, while the virtual machine is
+      running. This works regardless of the host operating system that
+      is running on the hosts. You can teleport virtual machines between
+      Oracle Solaris and macOS hosts, for example.
+    </para>
+
+    <para>
+      Teleporting requires that a machine be currently running on one
+      host, which is called the <emphasis>source</emphasis>. The host to
+      which the virtual machine will be teleported is called the
+      <emphasis>target</emphasis>. The machine on the target is then
+      configured to wait for the source to contact the target. The
+      machine's running state will then be transferred from the source
+      to the target with minimal downtime.
+    </para>
+
+    <para>
+      Teleporting happens over any TCP/IP network. The source and the
+      target only need to agree on a TCP/IP port which is specified in
+      the teleporting settings.
+    </para>
+
+    <para>
+      At this time, there are a few prerequisites for this to work, as
+      follows:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          On the target host, you must configure a virtual machine in
+          &product-name; with exactly the same hardware settings as the
+          machine on the source that you want to teleport. This does not
+          apply to settings which are merely descriptive, such as the VM
+          name, but obviously for teleporting to work, the target
+          machine must have the same amount of memory and other hardware
+          settings. Otherwise teleporting will fail with an error
+          message.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The two virtual machines on the source and the target must
+          share the same storage, hard disks as well as floppy disks and
+          CD/DVD images. This means that they either use the same iSCSI
+          targets or that the storage resides somewhere on the network
+          and both hosts have access to it using NFS or SMB/CIFS.
+        </para>
+
+        <para>
+          This also means that neither the source nor the target machine
+          can have any snapshots.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      To configure teleporting, perform the following steps:
+    </para>
+
+    <orderedlist>
+
+      <listitem>
+        <para>
+          On the <emphasis>target</emphasis> host, configure the virtual
+          machine to wait for a teleport request to arrive when it is
+          started, instead of actually attempting to start the machine.
+          This is done with the following <command>VBoxManage</command>
+          command:
+        </para>
+
+<screen>VBoxManage modifyvm <replaceable>targetvmname</replaceable> --teleporter on --teleporter-port <replaceable>port</replaceable></screen>
+
+        <para>
+          <replaceable>targetvmname</replaceable> is the name of the
+          virtual machine on the target host and
+          <replaceable>port</replaceable> is a TCP/IP port number to be
+          used on both the source and the target hosts. For example, use
+          6000. See <xref linkend="vboxmanage-modifyvm" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Start the VM on the target host. Instead of running, the VM
+          shows a progress dialog, indicating that it is waiting for a
+          teleport request to arrive.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Start the VM on the <emphasis>source</emphasis> host as usual.
+          When it is running and you want it to be teleported, issue the
+          following command on the source host:
+        </para>
+
+<screen>VBoxManage controlvm <replaceable>sourcevmname</replaceable> teleport --host <replaceable>targethost</replaceable> --port <replaceable>port</replaceable></screen>
+
+        <para>
+          where <replaceable>sourcevmname</replaceable> is the name of
+          the virtual machine on the source host, which is the machine
+          that is currently running.
+          <replaceable>targethost</replaceable> is the host or IP name
+          of the target host on which the machine is waiting for the
+          teleport request, and <replaceable>port</replaceable> must be
+          the same number as specified in the command on the target
+          host. See <xref linkend="vboxmanage-controlvm" />.
+        </para>
+      </listitem>
+
+    </orderedlist>
+
+    <para>
+      For testing, you can also teleport machines on the same host. In
+      that case, use localhost as the hostname on both the source and
+      the target host.
+    </para>
+
+    <note>
+      <para>
+        In rare cases, if the CPUs of the source and the target are very
+        different, teleporting can fail with an error message, or the
+        target may hang. This may happen especially if the VM is running
+        application software that is highly optimized to run on a
+        particular CPU without correctly checking that certain CPU
+        features are actually present. &product-name; filters what CPU
+        capabilities are presented to the guest operating system.
+        Advanced users can attempt to restrict these virtual CPU
+        capabilities with the <command>VBoxManage modifyvm
+        --cpuid-portability-level</command> command. See
+        <xref linkend="vboxmanage-modifyvm" />.
+      </para>
+    </note>
+
+  </sect1>
+
+  <xi:include href="user_man_VBoxHeadless.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</chapter>