diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/manual/en_US/user_Frontends.xml | 1242 |
1 files changed, 1242 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..18bfb51d --- /dev/null +++ b/doc/manual/en_US/user_Frontends.xml @@ -0,0 +1,1242 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!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. When this + package is installed, &product-name; versions 4.0 and later + support VRDP the same way as binary, non-open source, versions of + &product-name; before 4.0 did. + </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 in + the VirtualBox Manager 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 "VM name" --vrde on</screen> + + <para> + By default, the VRDP server uses TCP port + <computeroutput>3389</computeroutput>. 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>--vrdeport</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, <computeroutput>VBoxManage + modifyvm "VM name" --vrdeport 5000,5010-5012</computeroutput> will + configure the server to bind to one of the ports 5000, 5010, 5011, + or 5012. See <xref linkend="vboxmanage-modifyvm-vrde" />. + </para> + + <para> + The actual port used by a running VM can be either queried with + the <command>VBoxManage showvminfo</command> command or seen in + the GUI 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> + Support for IPv6 has been implemented in &product-name; 4.3. 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 <computeroutput>1.2.3.4</computeroutput> with the + host IP address, and <computeroutput>3389</computeroutput> + 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: <computeroutput>mstsc + [fe80::1:2:3:4]:3389</computeroutput> + </para> + </listitem> + + <listitem> + <para> + When connecting to localhost in order to test the + connection, the addresses + <computeroutput>localhost</computeroutput> and + <computeroutput>127.0.0.1</computeroutput> might not + work using <command>mstsc.exe</command>. Instead, the + address + <computeroutput>127.0.0.2[:3389]</computeroutput> 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, but &product-name; also comes with a + modified variant of <command>rdesktop</command> for remote + USB support. See <xref linkend="usb-over-rdp" />. + </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 <computeroutput>1.2.3.4</computeroutput> with the + host IP address, and <computeroutput>3389</computeroutput> + with a different port, if necessary. The <computeroutput>-a + 16</computeroutput> 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 + <computeroutput>-N</computeroutput> 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 + <computeroutput>krdc</computeroutput>, the KDE RDP viewer. A + typical command line is as follows: + </para> + +<screen>krdc rdp://1.2.3.4:3389</screen> + + <para> + Replace <computeroutput>1.2.3.4</computeroutput> with the + host IP address, and <computeroutput>3389</computeroutput> + with a different port, if necessary. The "rdp://" prefix is + required with krdc 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 the VirtualBox Manager is capable of + running virtual machines remotely, it is not convenient to have + to run the full-fledged 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 VirtualBox Manager 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 + <computeroutput>VBoxHeadless</computeroutput>, which produces no + visible output on the host at all, but still can deliver VRDP + data. This front-end has no dependencies on the X Window system + on Linux and Oracle Solaris hosts. + </para> + + <note> + <para> + Before &product-name; 1.6, the headless server was called + <computeroutput>VBoxVRDP</computeroutput>. For the sake of + backwards compatibility, the &product-name; installation still + installs an executable with that name as well. + </para> + </note> + + <para> + To start a virtual machine with + <computeroutput>VBoxHeadless</computeroutput>, you have the + following options: + </para> + + <itemizedlist> + + <listitem> + <para> + Use the <command>VBoxManage</command> command, as follows: + </para> + +<screen>VBoxManage startvm "VM name" --type headless</screen> + + <para> + The <computeroutput>--type</computeroutput> option causes + &product-name; to use + <computeroutput>VBoxHeadless</computeroutput> 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 <uuid|name></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 + <computeroutput>VBoxHeadless</computeroutput>. + </para> + </listitem> + + <listitem> + <para> + Start <computeroutput>VBoxHeadless</computeroutput> from the + VirtualBox Manager GUI, 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 <computeroutput>VBoxHeadless</computeroutput> + command to start a VM, the VRDP server will be enabled according + to the VM configuration. You can override the VM's setting using + <computeroutput>--vrde</computeroutput> command line parameter. + To enable the VRDP server, start the VM as follows: + </para> + +<screen>VBoxHeadless --startvm <uuid|name> --vrde on</screen> + + <para> + To disable the VRDP server: + </para> + +<screen>VBoxHeadless --startvm <uuid|name> --vrde off</screen> + + <para> + To have the VRDP server enabled depending on the VM + configuration, as for other front-ends: + </para> + +<screen>VBoxHeadless --startvm <uuid|name> --vrde config</screen> + + <para> + This command is the same as the following: + </para> + +<screen>VBoxHeadless --startvm <uuid|name></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 + <computeroutput>ssh</computeroutput>. + </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 + <computeroutput>--register</computeroutput>, you will have + to manually use the <command>registervm</command> command + later. + </para> + + <para> + You do not need to specify + <computeroutput>--ostype</computeroutput>, 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. On Linux and Oracle Solaris hosts, the + &product-name; installation provides a suitable VRDP client + called <command>rdesktop-vrdp</command>. Recent versions of + <command>uttsc</command>, a client tailored for the use with Sun + Ray thin clients, also support accessing remote USB devices. RDP + clients for other platforms will be provided in future + &product-name; versions. + </para> + + <para> + To make a remote USB device available to a VM, + <command>rdesktop-vrdp</command> should be started as follows: + </para> + +<screen>rdesktop-vrdp -r usb -a 16 -N my.host.address</screen> + + <para> + See <xref linkend="ts_usb-linux" /> for further details on how + to properly set up the permissions for USB devices. Furthermore + it is advisable to disable automatic loading of any host driver + on the remote host which might work on USB devices to ensure + that the devices are accessible by the RDP client. If the setup + was properly done on the remote host, plug and unplug events are + visible in the VBox.log file of the VM. + </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>--vrdeauthtype</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, + <computeroutput>VBoxAuth</computeroutput>, authenticates + against user credentials of the hosts. Depending on the + host platform, this means the following: + </para> + + <itemizedlist> + + <listitem> + <para> + On Linux hosts, + <computeroutput>VBoxAuth.so</computeroutput> + authenticates users against the host's PAM system. + </para> + </listitem> + + <listitem> + <para> + On Windows hosts, + <computeroutput>VBoxAuth.dll</computeroutput> + authenticates users against the host's WinLogon + system. + </para> + </listitem> + + <listitem> + <para> + On Mac OS X hosts, + <computeroutput>VBoxAuth.dylib</computeroutput> + 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 + <computeroutput>VBoxAuthSimple</computeroutput> performs + authentication against credentials configured in the + "extradata" 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 + <computeroutput>VBoxAuthSimple</computeroutput> 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 "VM name" --vrdeauthtype external</screen> + + <para> + Replace <computeroutput><vm></computeroutput> + 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 + <computeroutput>extradata</computeroutput> 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 "VM name" "VBoxAuthSimple/users/<user>" <hash></screen> + + <para> + Replace <computeroutput><vm></computeroutput> + with the VM name or UUID, + <computeroutput><user></computeroutput> with + the user name who should be allowed to log in and + <computeroutput><hash></computeroutput> with + the encrypted password. As an example, to obtain the + hash value for the password + <computeroutput>secret</computeroutput>, you can use + the following command: + </para> + +<screen>VBoxManage internalcommands passwordhash "secret"</screen> + + <para> + This command will generate output similar to the + following: + </para> + +<screen>2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen> + + <para> + You then use <command>VBoxManage + setextradata</command> to store this value in the + machine's <computeroutput>extradata</computeroutput> + section. + </para> + + <para> + As a combined example, to set the password for the + user <computeroutput>john</computeroutput> and the + machine <computeroutput>My VM</computeroutput> to + <computeroutput>secret</computeroutput>, 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">RDP4</emphasis> authentication was + used historically. With RDP4, 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">RDP5.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, RDP5.1 + authentication is also insecure. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">RDP5.2</emphasis> authentication uses + Enhanced RDP Security, which means that an external security + protocol is used to secure the connection. RDP4 and RDP5.1 + use Standard RDP Security. The VRDP server supports Enhanced + RDP Security with TLS protocol and, as a part of TLS + handshake, sends the server certificate to the client. + </para> + + <para> + The <computeroutput>Security/Method</computeroutput> 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 OpenSSL library version determines which versions of + TLS are supported. The &product-name; clients include at + least Version 1.1.0 of the OpenSSL library. This library + supports TLS versions 1.0, 1.1, and 1.2. Some clients + might include newer versions of the OpenSSL library and + thus support additional TLS versions. + </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 "VM name" --vrdeproperty "Security/Method=negotiate"</screen> + + <para> + If the <computeroutput>Security/Method</computeroutput> + 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 "VM name" \ + --vrdeproperty "Security/CACertificate=path/ca_cert.pem"</screen> + +<screen>vboxmanage modifyvm "VM name" \ + --vrdeproperty "Security/ServerCertificate=path/server_cert.pem"</screen> + +<screen>vboxmanage modifyvm "VM name" \ + --vrdeproperty "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 + <computeroutput>-4</computeroutput> or + <computeroutput>-5</computeroutput> 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 "VM name" --vrdemulticon 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 <computeroutput>domain</computeroutput> login + parameter (<computeroutput>-d</computeroutput>). If the + parameter ends with <computeroutput>@</computeroutput> followed + by a number, &product-name; interprets this number as the screen + index. The primary guest screen is selected with + <computeroutput>@1</computeroutput>, the first secondary screen + is <computeroutput>@2</computeroutput>, and so on. + </para> + + <para> + The Microsoft RDP6 client does not let you specify a separate + domain name. Instead, enter + <computeroutput>domain\username</computeroutput> in the + <emphasis role="bold">Username</emphasis> field. For example, + <computeroutput>@2\name</computeroutput>. + <computeroutput>name</computeroutput> 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 "VM name" --vrdevideochannel 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 "VM name" --vrdevideochannelquality 75</screen> + + </sect2> + + <sect2 id="vrde-customization"> + + <title>VRDP Customization</title> + + <para> + With &product-name; it is possible to 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 "VM name" --vrdeproperty Client/DisableDisplay=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableInput=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUSB=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableAudio=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableClipboard=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUpstreamAudio=1</screen> + + <para> + To reenable a feature, use a similar command without the + trailing 1. For example: + </para> + +<screen>VBoxManage modifyvm "VM name" --vrdeproperty 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 Mac OS X 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 <targetvmname> --teleporter on --teleporterport <port></screen> + + <para> + where <computeroutput><targetvmname></computeroutput> is + the name of the virtual machine on the target host and + <computeroutput><port></computeroutput> 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-teleport" />. + </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 <sourcevmname> teleport --host <targethost> --port <port></screen> + + <para> + where <computeroutput><sourcevmname></computeroutput> is + the name of the virtual machine on the source host, which is + the machine that is currently running. + <computeroutput><targethost></computeroutput> is the + host or IP name of the target host on which the machine is + waiting for the teleport request, and + <computeroutput><port></computeroutput> 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 <computeroutput>VBoxManage modifyvm + --cpuid</computeroutput> command. See + <xref linkend="vboxmanage-modifyvm-teleport" />. + </para> + </note> + + </sect1> + +</chapter> |