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