diff options
Diffstat (limited to 'doc/manual/en_US/user_Frontends.xml')
| -rw-r--r-- | doc/manual/en_US/user_Frontends.xml | 799 |
1 files changed, 799 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..ffecc955 --- /dev/null +++ b/doc/manual/en_US/user_Frontends.xml @@ -0,0 +1,799 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" +"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> +<chapter> + <title>Remote virtual machines</title> + + <sect1> + <title id="vrde">Remote display (VRDP support)</title> + + <para>VirtualBox can display virtual machines remotely, meaning that a + virtual machine can execute on one machine 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, starting with VirtualBox 4.0, VirtualBox + implements remote machine display through a generic extension interface, + the VirtualBox Remote Desktop Extension (VRDE). The base open-source + VirtualBox package only provides this interface, while implementations can + be supplied by third parties with VirtualBox extension packages, which + must be installed separately from the base package. See <xref + linkend="intro-installing" /> for more information.</para> + + <para>Oracle provides support for the <emphasis role="bold">VirtualBox + Remote Display Protocol (VRDP)</emphasis> in such a VirtualBox extension + package. When this package is installed, VirtualBox versions 4.0 and later + support VRDP the same way as binary (non-open-source) versions of + VirtualBox before 4.0 did.</para> + + <para>VRDP is a backwards-compatible extension to Microsoft's Remote + Desktop Protocol (RDP). Typically graphics updates and audio are sent from + the remote machine to the client, while keyboard and mouse events are sent + back. 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 "Display" settings (see <xref + linkend="settings-display" />) or with + <computeroutput>VBoxManage</computeroutput>:<screen>VBoxManage modifyvm "VM name" --vrde on</screen></para> + + <para>If you use <computeroutput>VBoxHeadless</computeroutput> (described + further below), VRDP support will be automatically enabled since + VBoxHeadless has no other means of output.</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 + (examples follow below). For this to work, you must specify the + <emphasis role="bold">IP address</emphasis> of your + <emphasis>host</emphasis> system (not of the virtual machine!) as the + server address to connect to, as well as the <emphasis role="bold">port + number</emphasis> that the RDP server is using.</para> + + <para>By default, VRDP 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 "Display" settings of the + graphical user interface or with + <computeroutput>--vrdeport</computeroutput> option of the + <computeroutput>VBoxManage modifyvm</computeroutput> 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 role="bold">one</emphasis> of 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" /> for details.</para> + + <para>The actual port used by a running VM can be either queried with + <computeroutput>VBoxManage showvminfo</computeroutput> command or seen + in the GUI on the "Runtime" tab of the "Session Information Dialog", + which is accessible via the "Machine" menu of the VM window.</para> + + <para>Here follow examples for the most common RDP viewers:<itemizedlist> + <listitem> + <para>On Windows, you can use the Microsoft Terminal Services + Connector (<computeroutput>mstsc.exe</computeroutput>) that ships + with Windows. You can start it by bringing up the "Run" dialog + (press the Windows key and "R") and typing "mstsc". You can also + find it under "Start" -> "All Programs" -> "Accessories" + -> "Remote Desktop Connection". If you use the "Run" dialog, + you can type in options directly:<screen>mstsc 1.2.3.4[:3389]</screen></para> + + <para>Replace "1.2.3.4" with the host IP address, and 3389 with a + different port if necessary.</para> + + <note> + <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 + <computeroutput>mstsc.exe</computeroutput>. Instead, the address + <computeroutput>127.0.0.2[:3389]</computeroutput> has to be + used.</para> + </note> + </listitem> + + <listitem> + <para>On other systems, you can use the standard open-source + <computeroutput>rdesktop</computeroutput> program. This ships with + most Linux distributions, but VirtualBox also comes with a + modified variant of rdesktop for remote USB support (see <xref + linkend="usb-over-rdp" /> below).</para> + + <para>With rdesktop, use a command line such as the + following:<screen>rdesktop -a 16 -N 1.2.3.4:3389</screen></para> + + <para>As said for the Microsoft viewer above, replace "1.2.3.4" + with the host IP address, and 3389 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>If you run the KDE desktop, you might prefer + <computeroutput>krdc</computeroutput>, the KDE RDP viewer. The + command line would look like this:<screen>krdc --window --high-quality rdp:/1.2.3.4[:3389]</screen></para> + + <para>Again, replace "1.2.3.4" with the host IP address, and 3389 + with a different port if necessary. The "rdp:/" bit is required + with krdc to switch it into RDP mode.</para> + </listitem> + + <listitem> + <para>With Sun Ray thin clients you can use + <computeroutput>uttsc</computeroutput>, which is part of the + Sun Ray Windows Connector package. See the corresponding + documentation for details.</para> + </listitem> + </itemizedlist></para> + </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 -- especially since, on a Linux or + Solaris host, 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>VirtualBox therefore comes with yet another front-end called + <computeroutput>VBoxHeadless</computeroutput>, which produces no visible + output on the host at all, but instead only delivers VRDP data. This + front-end has no dependencies on the X Window system on Linux and + Solaris hosts.<footnote> + <para>Before VirtualBox 1.6, the headless server was called + <computeroutput>VBoxVRDP</computeroutput>. For the sake of backwards + compatibility, the VirtualBox installation still installs an + executable with that name as well.</para> + </footnote></para> + + <para>To start a virtual machine with + <computeroutput>VBoxHeadless</computeroutput>, you have two + options:</para> + + <itemizedlist> + <listitem> + <para>You can use <screen>VBoxManage startvm "VM name" --type headless</screen>The + extra <computeroutput>--type</computeroutput> option causes + VirtualBox to use <computeroutput>VBoxHeadless</computeroutput> as + the front-end to the internal virtualization engine instead of the + Qt front-end.</para> + </listitem> + + <listitem> + <para>The alternative is to use + <computeroutput>VBoxHeadless</computeroutput> directly, as + follows:<screen>VBoxHeadless --startvm <uuid|name></screen></para> + + <para>This way of starting the VM helps troubleshooting problems + reported by <computeroutput>VBoxManage startvm ...</computeroutput> + because you can see sometimes more detailed error messages, + especially for early failures before the VM execution is started. + In normal situations <computeroutput>VBoxManage startvm</computeroutput> + is preferred since it runs the VM directly as a background process + which has to be done explicitly when directly starting + <computeroutput>VBoxHeadless</computeroutput>.</para> + </listitem> + </itemizedlist> + + <para>Note that when you use + <computeroutput>VBoxHeadless</computeroutput> to start a VM, since the + headless server has no other means of output, the VRDP server will + <emphasis>always</emphasis> be enabled, regardless of whether you had + enabled the VRDP server in the VM's settings. If this is undesirable + (for example because you want to access the VM via + <computeroutput>ssh</computeroutput> only), start the VM like + this:<screen>VBoxHeadless --startvm <uuid|name> --vrde off</screen>To + have the VRDP server enabled depending on the VM configuration, as the + other front-ends would, use this:<screen>VBoxHeadless --startvm <uuid|name> --vrde config</screen></para> + + <para>If you start the VM with <computeroutput>VBoxManage startvm ...</computeroutput> + then the configuration settings of the VM are always used.</para> + </sect2> + + <sect2> + <title>Step by step: creating a virtual machine on a headless + server</title> + + <para>The following instructions may give you an idea how to create a + virtual machine on a headless server over a network connection. We will + create a virtual machine, establish an RDP connection and install a + guest operating system -- all without having to touch the headless + server. All you need is the following:</para> + + <para><orderedlist> + <listitem> + <para>VirtualBox on a server machine with a supported host + operating system. The VirtualBox extension pack for the VRDP + server must be installed (see the previous section). For the + following example, we will assume a Linux server.</para> + </listitem> + + <listitem> + <para>An ISO file accessible from the server, containing the + installation data for the guest operating system to install (we + will assume Windows XP in the following example).</para> + </listitem> + + <listitem> + <para>A terminal connection to that host through which you can + access a command line (e.g. via + <computeroutput>ssh</computeroutput>).</para> + </listitem> + + <listitem> + <para>An RDP viewer on the remote client; see <xref + linkend="rdp-viewers" /> above for examples.</para> + </listitem> + </orderedlist>Note again that on the server machine, since we will + only use the headless server, neither Qt nor SDL nor the X Window system + will be needed.</para> + + <para><orderedlist> + <listitem> + <para>On the headless server, create a new virtual machine:</para> + + <screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen> + + <para>Note that if you do not specify + <computeroutput>--register</computeroutput>, you will have to + manually use the <computeroutput>registervm</computeroutput> + command later.</para> + + <para>Note further that you do not need to specify + <computeroutput>--ostype</computeroutput>, but doing so selects + some sane 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</para> + + <screen>VBoxManage list ostypes</screen> + </listitem> + + <listitem> + <para>Make sure the settings for this VM are appropriate for the + guest operating system that we will install. For example:<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen></para> + </listitem> + + <listitem> + <para>Create a virtual hard disk for the VM (in this case, 10GB in + size):<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000</screen></para> + </listitem> + + <listitem> + <para>Add an IDE Controller to the new VM:<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller" + --add ide --controller PIIX4</screen></para> + </listitem> + + <listitem> + <para>Set the VDI file created above as the first virtual hard + disk of the new VM:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller" + --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen></para> + </listitem> + + <listitem> + <para>Attach the ISO file that contains the operating system + installation that you want to install later to the virtual + machine, so the machine can boot from it:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller" + --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen></para> + </listitem> + + <listitem> + <para>Start the virtual machine using VBoxHeadless:<screen>VBoxHeadless --startvm "Windows XP"</screen></para> + + <para>If everything worked, you should see a copyright notice. If, + instead, you are returned to the command line, then something went + wrong.</para> + </listitem> + + <listitem> + <para>On the client machine, fire up the RDP viewer and try to + connect to the server (see <xref linkend="rdp-viewers" /> above + for how to use various common RDP viewers).</para> + + <para>You should now be seeing the installation routine of your + guest operating system remotely in the RDP viewer.</para> + </listitem> + </orderedlist></para> + </sect2> + + <sect2 id="usb-over-rdp"> + <title>Remote USB</title> + + <para>As a special feature on top of the VRDP support, VirtualBox + supports remote USB devices over the wire as well. That is, the + VirtualBox 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 allows + for running virtual machines on a VirtualBox 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 VirtualBox server can access + them.</para> + + <para>For these remote USB devices, the same filter rules apply as for + other USB devices, as described with <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 Solaris hosts, the VirtualBox + installation provides a suitable VRDP client called + <computeroutput>rdesktop-vrdp</computeroutput>. Recent versions of + <computeroutput>uttsc</computeroutput>, 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 VirtualBox + versions.</para> + + <para>To make a remote USB device available to a VM, + <computeroutput>rdesktop-vrdp</computeroutput> should be started as + follows:<screen>rdesktop-vrdp -r usb -a 16 -N my.host.address</screen>Note + that <computeroutput>rdesktop-vrdp</computeroutput> can access USB + devices only through <computeroutput>/proc/bus/usb</computeroutput>. + Please refer to <xref linkend="ts_usb-linux" /> for further details on how + to properly set up the permissions. 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/unplug events are visible on 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 via RDP, you + can individually determine if and how client connections are + authenticated. For this, use <computeroutput>VBoxManage + modifyvm</computeroutput> command with the + <computeroutput>--vrdeauthtype</computeroutput> option; see <xref + linkend="vboxmanage-modifyvm" /> for a general introduction. Three + methods of authentication are available:<itemizedlist> + <listitem> + <para>The "null" method means that there is no authentication at + all; any client can connect to the VRDP server and thus the + virtual machine. This is, of course, very insecure and only to be + recommended for private networks.</para> + </listitem> + + <listitem> + <para>The "external" method provides external authentication + through a special authentication library. VirtualBox ships with + two such authentication libraries:<orderedlist> + <listitem> + <para>The default authentication library, + <computeroutput>VBoxAuth</computeroutput>, authenticates + against user credentials of the hosts. Depending on the host + platform, this means:<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.<footnote> + <para>Support for Mac OS X was added in version + 3.2.</para> + </footnote></para> + </listitem> + </itemizedlist></para> + + <para>In other words, the "external" method per default + performs authentication with the user accounts that exist on + the host system. Any user with valid authentication + credentials is accepted, i.e. 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 (see below). The following steps are + required:<orderedlist> + <listitem> + <para>Enable + <computeroutput>VBoxAuthSimple</computeroutput> with + the following command:</para> + + <para><screen>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</screen></para> + </listitem> + + <listitem> + <para>To enable the library for a particular VM, you + must then switch authentication to external:<screen>VBoxManage modifyvm <vm> --vrdeauthtype external</screen></para> + + <para>Replace + <computeroutput><vm></computeroutput> with the + VM name or UUID.</para> + </listitem> + + <listitem> + <para>You will then need to configure users and + passwords by writing items into the machine's + extradata. Since the XML machine settings file, into + whose "extradata" section the password needs to be + written, is a plain text file, VirtualBox uses hashes + to encrypt passwords. The following command must be + used:<screen>VBoxManage setextradata <vm> "VBoxAuthSimple/users/<user>" <hash></screen></para> + + <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 "secret", you can use the + following command:<screen>VBoxManage internalcommands passwordhash "secret"</screen></para> + + <para>This will print + <screen>2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen> + You can then use VBoxManage setextradata to store this + value in the machine's "extradata" section.</para> + + <para>As example, combined together, to set the + password for the user "john" and the machine "My VM" + to "secret", use this command:<screen>VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john" + 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen></para> + </listitem> + </orderedlist></para> + </listitem> + </orderedlist></para> + </listitem> + + <listitem> + <para>Finally, the "guest" 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 <emphasis>guest</emphasis> user + accounts.</para> + + <para>This method is currently still in testing and not yet + supported.</para> + </listitem> + </itemizedlist></para> + + <para>In addition to the methods described above, you can replace the + default "external" authentication module with any other module. For + this, VirtualBox provides a well-defined interface that allows you to + write your own authentication module. This is described in detail in the + VirtualBox Software Development Kit (SDK) reference; please see <xref + linkend="VirtualBoxAPI" /> for details.</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 128bit). The RC4 keys are being + replaced in regular intervals (every 4096 packets).</para> + + <para>RDP provides different authentication methods:<orderedlist> + <listitem> + <para>Historically, RDP4 authentication was used, with which 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>RDP5.1 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>RDP5.2 authentication uses the 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:<itemizedlist> + <listitem> + <para> + <computeroutput>Negotiate</computeroutput> - 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> + <computeroutput>RDP</computeroutput> - only Standard RDP Security + is accepted.</para> + </listitem> + + <listitem> + <para> + <computeroutput>TLS</computeroutput> - only Enhanced RDP Security + is accepted. The client must support TLS.</para> + </listitem> + </itemizedlist> + For example the following command allows a client to use either Standard + or Enhanced RDP Security connection: + <screen>vboxmanage modifyvm "VM name" --vrdeproperty "Security/Method=negotiate"</screen> + </para> + + <para>If the <computeroutput>Security/Method</computeroutput> property is + set to either <computeroutput>Negotiate</computeroutput> or + <computeroutput>TLS</computeroutput>, 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.<orderedlist> + <listitem> + Create a CA self signed certificate: + <screen>openssl req -new -x509 -days 365 -extensions v3_ca \ + -keyout ca_key_private.pem -out ca_cert.pem</screen> + </listitem> + + <listitem> + Generate a server private key and a request for signing: + <screen>openssl genrsa -out server_key_private.pem +openssl req -new -key server_key_private.pem -out server_req.pem</screen> + </listitem> + + <listitem> + Generate the server certificate: + <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> + The server must be configured to access the required files: + <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> + </para> + </listitem> + </orderedlist></para> + + <para>As the client that connects to the server determines what type + of encryption will be used, with rdesktop, 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 VirtualBox 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: <screen>VBoxManage modifyvm "VM name" --vrdemulticon on</screen></para> + </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> logon parameter + (<computeroutput>-d</computeroutput>). If the parameter ends with + <computeroutput>@</computeroutput> followed by a number, VirtualBox + 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>, etc.</para> + + <para>The Microsoft RDP6 client does not let you specify a separate + domain name. Instead, use + <computeroutput>domain\username</computeroutput> in the + <computeroutput>Username:</computeroutput> 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>Starting with VirtualBox 3.2, 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: <screen>VBoxManage modifyvm "VM name" --vrdevideochannel on</screen></para> + + <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: <screen>VBoxManage modifyvm "VM name" --vrdevideochannelquality 75</screen></para> + </sect2> + + <sect2 id="vrde-customization"> + <title>VRDP customization</title> + + <para>With VirtualBox 4.0 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 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: <screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=</screen></para> + + <para>These properties were introduced with VirtualBox 3.2.10. However, + in the 3.2.x series, it was necessary to use the following commands to + alter these settings instead:</para> + + <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay" 1 +VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableInput" 1 +VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableUSB" 1 +VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableAudio" 1 +VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableClipboard" 1</screen> + + <para>To reenable a feature use a similar command without the trailing + 1. For example: <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay"</screen></para> + </sect2> + </sect1> + + <sect1 id="teleporting"> + <title>Teleporting</title> + + <para>Starting with version 3.1, VirtualBox supports "teleporting" -- that + is, moving a virtual machine over a network from one VirtualBox 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 Solaris and Mac hosts, for example.</para> + + <para>Teleporting requires that a machine be currently running on one + host, which is then called the <emphasis role="bold">"source"</emphasis>. + The host to which the virtual machine will be teleported will then be + called the <emphasis role="bold">"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, + however:<orderedlist> + <listitem> + <para>On the target host, you must configure a virtual machine in + VirtualBox 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 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 via NFS or SMB/CIFS.</para> + + <para>This also means that neither the source nor the target machine + can have any snapshots.</para> + </listitem> + </orderedlist></para> + + <para>Then perform the following steps:<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 VBoxManage command:<screen>VBoxManage modifyvm <targetvmname> --teleporter on --teleporterport <port></screen></para> + + <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. For details, see <xref + linkend="vboxmanage-modifyvm-teleport" />.</para> + </listitem> + + <listitem> + <para>Start the VM on the target host. You will see that instead of + actually running, it will show a progress dialog. indicating that it + is waiting for a teleport request to arrive.</para> + </listitem> + + <listitem> + <para>Start the machine 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:<screen>VBoxManage controlvm <sourcevmname> teleport --host <targethost> --port <port></screen></para> + + <para>where <computeroutput><sourcevmname></computeroutput> is + the name of the virtual machine on the source host (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. For details, see <xref + linkend="vboxmanage-controlvm" />.</para> + </listitem> + </orderedlist></para> + + <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.<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. + VirtualBox 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></para> + </sect1> +</chapter> |