VirtualBox

source: vbox/trunk/doc/manual/en_US/user_Frontends.xml@ 43970

Last change on this file since 43970 was 43970, checked in by vboxsync, 12 years ago

Mods to user manual reflecting mds in 4.2.x 6417

File size: 40.7 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
4<chapter>
5 <title>Remote virtual machines</title>
6
7 <sect1>
8 <title id="vrde">Remote display (VRDP support)</title>
9
10 <para>VirtualBox can display virtual machines remotely, meaning that a
11 virtual machine can execute on one machine even though the machine will be
12 displayed on a second computer, and the machine will be controlled from
13 there as well, as if the virtual machine was running on that second
14 computer.</para>
15
16 <para>For maximum flexibility, starting with VirtualBox 4.0, VirtualBox
17 implements remote machine display through a generic extension interface,
18 the VirtualBox Remote Desktop Extension (VRDE). The base open-source
19 VirtualBox package only provides this interface, while implementations can
20 be supplied by third parties with VirtualBox extension packages, which
21 must be installed separately from the base package. See <xref
22 linkend="intro-installing" /> for more information.</para>
23
24 <para>Oracle provides support for the <emphasis role="bold">VirtualBox
25 Remote Display Protocol (VRDP)</emphasis> in such a VirtualBox extension
26 package. When this package is installed, VirtualBox versions 4.0 and later
27 support VRDP the same way as binary (non-open-source) versions of
28 VirtualBox before 4.0 did.</para>
29
30 <para>VRDP is a backwards-compatible extension to Microsoft's Remote
31 Desktop Protocol (RDP). Typically graphics updates and audio are sent from
32 the remote machine to the client, while keyboard and mouse events are sent
33 back. As a result, you can use any standard RDP client to control the
34 remote VM.</para>
35
36 <para>Even when the extension is installed, the VRDP server is disabled by
37 default. It can easily be enabled on a per-VM basis either in the
38 VirtualBox Manager in the "Display" settings (see <xref
39 linkend="settings-display" />) or with
40 <computeroutput>VBoxManage</computeroutput>:<screen>VBoxManage modifyvm "VM name" --vrde on</screen></para>
41
42 <para>If you use <computeroutput>VBoxHeadless</computeroutput> (described
43 further below), VRDP support will be automatically enabled since
44 VBoxHeadless has no other means of output.</para>
45
46 <sect2 id="rdp-viewers">
47 <title>Common third-party RDP viewers</title>
48
49 <para>Since VRDP is backwards-compatible to RDP, you can use any
50 standard RDP viewer to connect to such a remote virtual machine
51 (examples follow below). For this to work, you must specify the
52 <emphasis role="bold">IP address</emphasis> of your
53 <emphasis>host</emphasis> system (not of the virtual machine!) as the
54 server address to connect to, as well as the <emphasis role="bold">port
55 number</emphasis> that the RDP server is using.</para>
56
57 <para>By default, VRDP uses TCP port
58 <computeroutput>3389</computeroutput>. You will need to change the
59 default port if you run more than one VRDP server, since the port can
60 only be used by one server at a time; you might also need to change it
61 on Windows hosts since the default port might already be used by the RDP
62 server that is built into Windows itself. Ports 5000 through 5050 are
63 typically not used and might be a good choice.</para>
64
65 <para>The port can be changed either in the "Display" settings of the
66 graphical user interface or with
67 <computeroutput>--vrdeport</computeroutput> option of the
68 <computeroutput>VBoxManage modifyvm</computeroutput> command. You can
69 specify a comma-separated list of ports or ranges of ports. Use a dash
70 between two port numbers to specify a range. The VRDP server will bind
71 to <emphasis role="bold">one</emphasis> of available ports from the
72 specified list. For example, <computeroutput>VBoxManage modifyvm "VM
73 name" --vrdeport 5000,5010-5012</computeroutput> will configure the
74 server to bind to one of the ports 5000, 5010, 5011 or 5012. See <xref
75 linkend="vboxmanage-modifyvm" /> for details.</para>
76
77 <para>The actual port used by a running VM can be either queried with
78 <computeroutput>VBoxManage showvminfo</computeroutput> command or seen
79 in the GUI on the "Runtime" tab of the "Session Information Dialog",
80 which is accessible via the "Machine" menu of the VM window.</para>
81
82 <para>Here follow examples for the most common RDP viewers:<itemizedlist>
83 <listitem>
84 <para>On Windows, you can use the Microsoft Terminal Services
85 Connector (<computeroutput>mstsc.exe</computeroutput>) that ships
86 with Windows. You can start it by bringing up the "Run" dialog
87 (press the Windows key and "R") and typing "mstsc". You can also
88 find it under "Start" -&gt; "All Programs" -&gt; "Accessories"
89 -&gt; "Remote Desktop Connection". If you use the "Run" dialog,
90 you can type in options directly:<screen>mstsc 1.2.3.4[:3389]</screen></para>
91
92 <para>Replace "1.2.3.4" with the host IP address, and 3389 with a
93 different port if necessary.</para>
94
95 <note>
96 <para>When connecting to localhost in order to test the
97 connection, the addresses
98 <computeroutput>localhost</computeroutput> and
99 <computeroutput>127.0.0.1</computeroutput> might not work using
100 <computeroutput>mstsc.exe</computeroutput>. Instead, the address
101 <computeroutput>127.0.0.2[:3389]</computeroutput> has to be
102 used.</para>
103 </note>
104 </listitem>
105
106 <listitem>
107 <para>On other systems, you can use the standard open-source
108 <computeroutput>rdesktop</computeroutput> program. This ships with
109 most Linux distributions, but VirtualBox also comes with a
110 modified variant of rdesktop for remote USB support (see <xref
111 linkend="usb-over-rdp" /> below).</para>
112
113 <para>With rdesktop, use a command line such as the
114 following:<screen>rdesktop -a 16 -N 1.2.3.4:3389</screen></para>
115
116 <para>As said for the Microsoft viewer above, replace "1.2.3.4"
117 with the host IP address, and 3389 with a different port if
118 necessary. The <computeroutput>-a 16</computeroutput> option
119 requests a color depth of 16 bits per pixel, which we recommend.
120 (For best performance, after installation of the guest operating
121 system, you should set its display color depth to the same value).
122 The <computeroutput>-N</computeroutput> option enables use of the
123 NumPad keys.</para>
124 </listitem>
125
126 <listitem>
127 <para>If you run the KDE desktop, you might prefer
128 <computeroutput>krdc</computeroutput>, the KDE RDP viewer. The
129 command line would look like this:<screen>krdc --window --high-quality rdp:/1.2.3.4[:3389]</screen></para>
130
131 <para>Again, replace "1.2.3.4" with the host IP address, and 3389
132 with a different port if necessary. The "rdp:/" bit is required
133 with krdc to switch it into RDP mode.</para>
134 </listitem>
135
136 <listitem>
137 <para>With Sun Ray thin clients you can use
138 <computeroutput>uttsc</computeroutput>, which is part of the
139 Sun Ray Windows Connector package. See the corresponding
140 documentation for details.</para>
141 </listitem>
142 </itemizedlist></para>
143 </sect2>
144
145 <sect2 id="vboxheadless">
146 <title>VBoxHeadless, the remote desktop server</title>
147
148 <para>While any VM started from the VirtualBox Manager is capable of
149 running virtual machines remotely, it is not convenient to have to run
150 the full-fledged GUI if you never want to have VMs displayed locally in
151 the first place. In particular, if you are running server hardware whose
152 only purpose is to host VMs, and all your VMs are supposed to run
153 remotely over VRDP, then it is pointless to have a graphical user
154 interface on the server at all -- especially since, on a Linux or
155 Solaris host, the VirtualBox manager comes with dependencies on the Qt
156 and SDL libraries. This is inconvenient if you would rather not have the
157 X Window system on your server at all.</para>
158
159 <para>VirtualBox therefore comes with yet another front-end called
160 <computeroutput>VBoxHeadless</computeroutput>, which produces no visible
161 output on the host at all, but instead only delivers VRDP data. This
162 front-end has no dependencies on the X Window system on Linux and
163 Solaris hosts.<footnote>
164 <para>Before VirtualBox 1.6, the headless server was called
165 <computeroutput>VBoxVRDP</computeroutput>. For the sake of backwards
166 compatibility, the VirtualBox installation still installs an
167 executable with that name as well.</para>
168 </footnote></para>
169
170 <para>To start a virtual machine with
171 <computeroutput>VBoxHeadless</computeroutput>, you have three
172 options:</para>
173
174 <itemizedlist>
175 <listitem>
176 <para>You can use <screen>VBoxManage startvm "VM name" --type headless</screen>The
177 extra <computeroutput>--type</computeroutput> option causes
178 VirtualBox to use <computeroutput>VBoxHeadless</computeroutput> as
179 the front-end to the internal virtualization engine instead of the
180 Qt front-end.</para>
181 </listitem>
182
183 <listitem>
184 <para>One alternative is to use
185 <computeroutput>VBoxHeadless</computeroutput> directly, as
186 follows:<screen>VBoxHeadless --startvm &lt;uuid|name&gt;</screen></para>
187
188 <para>This way of starting the VM helps troubleshooting problems
189 reported by <computeroutput>VBoxManage startvm ...</computeroutput>
190 because you can see sometimes more detailed error messages,
191 especially for early failures before the VM execution is started.
192 In normal situations <computeroutput>VBoxManage startvm</computeroutput>
193 is preferred since it runs the VM directly as a background process
194 which has to be done explicitly when directly starting
195 <computeroutput>VBoxHeadless</computeroutput>.</para>
196 </listitem>
197
198 <listitem>
199 <para>The other alternative is to start <computeroutput>VBoxHeadless</computeroutput> from the VirtualBox Manager GUI.
200 </para>
201 </listitem>
202
203 </itemizedlist>
204
205 <para>Note that when you use
206 <computeroutput>VBoxHeadless</computeroutput> to start a VM, since the
207 headless server has no other means of output, the VRDP server will
208 <emphasis>always</emphasis> be enabled, regardless of whether you had
209 enabled the VRDP server in the VM's settings. If this is undesirable
210 (for example because you want to access the VM via
211 <computeroutput>ssh</computeroutput> only), start the VM like
212 this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrde off</screen>To
213 have the VRDP server enabled depending on the VM configuration, as the
214 other front-ends would, use this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrde config</screen></para>
215
216 <para>If you start the VM with <computeroutput>VBoxManage startvm ...</computeroutput>
217 then the configuration settings of the VM are always used.</para>
218 </sect2>
219
220 <sect2>
221 <title>Step by step: creating a virtual machine on a headless
222 server</title>
223
224 <para>The following instructions may give you an idea how to create a
225 virtual machine on a headless server over a network connection. We will
226 create a virtual machine, establish an RDP connection and install a
227 guest operating system -- all without having to touch the headless
228 server. All you need is the following:</para>
229
230 <para><orderedlist>
231 <listitem>
232 <para>VirtualBox on a server machine with a supported host
233 operating system. The VirtualBox extension pack for the VRDP
234 server must be installed (see the previous section). For the
235 following example, we will assume a Linux server.</para>
236 </listitem>
237
238 <listitem>
239 <para>An ISO file accessible from the server, containing the
240 installation data for the guest operating system to install (we
241 will assume Windows XP in the following example).</para>
242 </listitem>
243
244 <listitem>
245 <para>A terminal connection to that host through which you can
246 access a command line (e.g. via
247 <computeroutput>ssh</computeroutput>).</para>
248 </listitem>
249
250 <listitem>
251 <para>An RDP viewer on the remote client; see <xref
252 linkend="rdp-viewers" /> above for examples.</para>
253 </listitem>
254 </orderedlist>Note again that on the server machine, since we will
255 only use the headless server, neither Qt nor SDL nor the X Window system
256 will be needed.</para>
257
258 <para><orderedlist>
259 <listitem>
260 <para>On the headless server, create a new virtual machine:</para>
261
262 <screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen>
263
264 <para>Note that if you do not specify
265 <computeroutput>--register</computeroutput>, you will have to
266 manually use the <computeroutput>registervm</computeroutput>
267 command later.</para>
268
269 <para>Note further that you do not need to specify
270 <computeroutput>--ostype</computeroutput>, but doing so selects
271 some sane default values for certain VM parameters, for example
272 the RAM size and the type of the virtual network device. To get a
273 complete list of supported operating systems you can use</para>
274
275 <screen>VBoxManage list ostypes</screen>
276 </listitem>
277
278 <listitem>
279 <para>Make sure the settings for this VM are appropriate for the
280 guest operating system that we will install. For example:<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen></para>
281 </listitem>
282
283 <listitem>
284 <para>Create a virtual hard disk for the VM (in this case, 10GB in
285 size):<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000</screen></para>
286 </listitem>
287
288 <listitem>
289 <para>Add an IDE Controller to the new VM:<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller"
290 --add ide --controller PIIX4</screen></para>
291 </listitem>
292
293 <listitem>
294 <para>Set the VDI file created above as the first virtual hard
295 disk of the new VM:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
296 --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen></para>
297 </listitem>
298
299 <listitem>
300 <para>Attach the ISO file that contains the operating system
301 installation that you want to install later to the virtual
302 machine, so the machine can boot from it:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
303 --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen></para>
304 </listitem>
305
306 <listitem>
307 <para>Start the virtual machine using VBoxHeadless:<screen>VBoxHeadless --startvm "Windows XP"</screen></para>
308
309 <para>If everything worked, you should see a copyright notice. If,
310 instead, you are returned to the command line, then something went
311 wrong.</para>
312 </listitem>
313
314 <listitem>
315 <para>On the client machine, fire up the RDP viewer and try to
316 connect to the server (see <xref linkend="rdp-viewers" /> above
317 for how to use various common RDP viewers).</para>
318
319 <para>You should now be seeing the installation routine of your
320 guest operating system remotely in the RDP viewer.</para>
321 </listitem>
322 </orderedlist></para>
323 </sect2>
324
325 <sect2 id="usb-over-rdp">
326 <title>Remote USB</title>
327
328 <para>As a special feature on top of the VRDP support, VirtualBox
329 supports remote USB devices over the wire as well. That is, the
330 VirtualBox guest that runs on one computer can access the USB devices of
331 the remote computer on which the VRDP data is being displayed the same
332 way as USB devices that are connected to the actual host. This allows
333 for running virtual machines on a VirtualBox host that acts as a server,
334 where a client can connect from elsewhere that needs only a network
335 adapter and a display capable of running an RDP viewer. When USB devices
336 are plugged into the client, the remote VirtualBox server can access
337 them.</para>
338
339 <para>For these remote USB devices, the same filter rules apply as for
340 other USB devices, as described with <xref linkend="settings-usb" />.
341 All you have to do is specify "Remote" (or "Any") when setting up these
342 rules.</para>
343
344 <para>Accessing remote USB devices is only possible if the RDP client
345 supports this extension. On Linux and Solaris hosts, the VirtualBox
346 installation provides a suitable VRDP client called
347 <computeroutput>rdesktop-vrdp</computeroutput>. Recent versions of
348 <computeroutput>uttsc</computeroutput>, a client tailored for the use
349 with Sun Ray thin clients, also support accessing remote USB devices.
350 RDP clients for other platforms will be provided in future VirtualBox
351 versions.</para>
352
353 <para>To make a remote USB device available to a VM,
354 <computeroutput>rdesktop-vrdp</computeroutput> should be started as
355 follows:<screen>rdesktop-vrdp -r usb -a 16 -N my.host.address</screen>Note
356 that <computeroutput>rdesktop-vrdp</computeroutput> can access USB
357 devices only through <computeroutput>/proc/bus/usb</computeroutput>.
358 Please refer to <xref linkend="ts_usb-linux" /> for further details on how
359 to properly set up the permissions. Furthermore it is advisable to
360 disable automatic loading of any host driver on the remote host which
361 might work on USB devices to ensure that the devices are accessible by
362 the RDP client. If the setup was properly done on the remote host,
363 plug/unplug events are visible on the VBox.log file of the VM.</para>
364 </sect2>
365
366 <sect2 id="vbox-auth">
367 <title>RDP authentication</title>
368
369 <para>For each virtual machine that is remotely accessible via RDP, you
370 can individually determine if and how client connections are
371 authenticated. For this, use <computeroutput>VBoxManage
372 modifyvm</computeroutput> command with the
373 <computeroutput>--vrdeauthtype</computeroutput> option; see <xref
374 linkend="vboxmanage-modifyvm" /> for a general introduction. Three
375 methods of authentication are available:<itemizedlist>
376 <listitem>
377 <para>The "null" method means that there is no authentication at
378 all; any client can connect to the VRDP server and thus the
379 virtual machine. This is, of course, very insecure and only to be
380 recommended for private networks.</para>
381 </listitem>
382
383 <listitem>
384 <para>The "external" method provides external authentication
385 through a special authentication library. VirtualBox ships with
386 two such authentication libraries:<orderedlist>
387 <listitem>
388 <para>The default authentication library,
389 <computeroutput>VBoxAuth</computeroutput>, authenticates
390 against user credentials of the hosts. Depending on the host
391 platform, this means:<itemizedlist>
392 <listitem>
393 <para>On Linux hosts,
394 <computeroutput>VBoxAuth.so</computeroutput>
395 authenticates users against the host's PAM
396 system.</para>
397 </listitem>
398
399 <listitem>
400 <para>On Windows hosts,
401 <computeroutput>VBoxAuth.dll</computeroutput>
402 authenticates users against the host's WinLogon
403 system.</para>
404 </listitem>
405
406 <listitem>
407 <para>On Mac OS X hosts,
408 <computeroutput>VBoxAuth.dylib</computeroutput>
409 authenticates users against the host's directory
410 service.<footnote>
411 <para>Support for Mac OS X was added in version
412 3.2.</para>
413 </footnote></para>
414 </listitem>
415 </itemizedlist></para>
416
417 <para>In other words, the "external" method per default
418 performs authentication with the user accounts that exist on
419 the host system. Any user with valid authentication
420 credentials is accepted, i.e. the username does not have to
421 correspond to the user running the VM.</para>
422 </listitem>
423
424 <listitem>
425 <para>An additional library called
426 <computeroutput>VBoxAuthSimple</computeroutput> performs
427 authentication against credentials configured in the
428 "extradata" section of a virtual machine's XML settings
429 file. This is probably the simplest way to get
430 authentication that does not depend on a running and
431 supported guest (see below). The following steps are
432 required:<orderedlist>
433 <listitem>
434 <para>Enable
435 <computeroutput>VBoxAuthSimple</computeroutput> with
436 the following command:</para>
437
438 <para><screen>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</screen></para>
439 </listitem>
440
441 <listitem>
442 <para>To enable the library for a particular VM, you
443 must then switch authentication to external:<screen>VBoxManage modifyvm &lt;vm&gt; --vrdeauthtype external</screen></para>
444
445 <para>Replace
446 <computeroutput>&lt;vm&gt;</computeroutput> with the
447 VM name or UUID.</para>
448 </listitem>
449
450 <listitem>
451 <para>You will then need to configure users and
452 passwords by writing items into the machine's
453 extradata. Since the XML machine settings file, into
454 whose "extradata" section the password needs to be
455 written, is a plain text file, VirtualBox uses hashes
456 to encrypt passwords. The following command must be
457 used:<screen>VBoxManage setextradata &lt;vm&gt; "VBoxAuthSimple/users/&lt;user&gt;" &lt;hash&gt;</screen></para>
458
459 <para>Replace
460 <computeroutput>&lt;vm&gt;</computeroutput> with the
461 VM name or UUID,
462 <computeroutput>&lt;user&gt;</computeroutput> with the
463 user name who should be allowed to log in and
464 <computeroutput>&lt;hash&gt;</computeroutput> with the
465 encrypted password. As an example, to obtain the hash
466 value for the password "secret", you can use the
467 following command:<screen>VBoxManage internalcommands passwordhash "secret"</screen></para>
468
469 <para>This will print
470 <screen>2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen>
471 You can then use VBoxManage setextradata to store this
472 value in the machine's "extradata" section.</para>
473
474 <para>As example, combined together, to set the
475 password for the user "john" and the machine "My VM"
476 to "secret", use this command:<screen>VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john"
477 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen></para>
478 </listitem>
479 </orderedlist></para>
480 </listitem>
481 </orderedlist></para>
482 </listitem>
483
484 <listitem>
485 <para>Finally, the "guest" authentication method performs
486 authentication with a special component that comes with the Guest
487 Additions; as a result, authentication is not performed on the
488 host, but with the <emphasis>guest</emphasis> user
489 accounts.</para>
490
491 <para>This method is currently still in testing and not yet
492 supported.</para>
493 </listitem>
494 </itemizedlist></para>
495
496 <para>In addition to the methods described above, you can replace the
497 default "external" authentication module with any other module. For
498 this, VirtualBox provides a well-defined interface that allows you to
499 write your own authentication module. This is described in detail in the
500 VirtualBox Software Development Kit (SDK) reference; please see <xref
501 linkend="VirtualBoxAPI" /> for details.</para>
502 </sect2>
503
504 <sect2 id="vrde-crypt">
505 <title>RDP encryption</title>
506
507 <para>RDP features data stream encryption, which is based on the RC4
508 symmetric cipher (with keys up to 128bit). The RC4 keys are being
509 replaced in regular intervals (every 4096 packets).</para>
510
511 <para>RDP provides different authentication methods:<orderedlist>
512 <listitem>
513 <para>Historically, RDP4 authentication was used, with which the
514 RDP client does not perform any checks in order to verify the
515 identity of the server it connects to. Since user credentials can
516 be obtained using a "man in the middle" (MITM) attack, RDP4
517 authentication is insecure and should generally not be
518 used.</para>
519 </listitem>
520
521 <listitem>
522 <para>RDP5.1 authentication employs a server certificate for which
523 the client possesses the public key. This way it is guaranteed
524 that the server possess the corresponding private key. However, as
525 this hard-coded private key became public some years ago, RDP5.1
526 authentication is also insecure.</para>
527 </listitem>
528
529 <listitem>
530 <para>RDP5.2 authentication uses the Enhanced RDP Security, which
531 means that an external security protocol is used to secure the
532 connection. RDP4 and RDP5.1 use Standard RDP Security.
533 The VRDP server supports Enhanced RDP Security with TLS protocol and,
534 as a part of TLS handshake, sends the server certificate to the
535 client.</para>
536
537 <para>The <computeroutput>Security/Method</computeroutput> VRDE
538 property sets the desired security method, which is used for a
539 connection. Valid values are:<itemizedlist>
540 <listitem>
541 <para>
542 <computeroutput>Negotiate</computeroutput> - both Enhanced (TLS)
543 and Standard RDP Security connections are allowed. The security
544 method is negotiated with the client. This is the default setting.
545 </para>
546 </listitem>
547
548 <listitem>
549 <para>
550 <computeroutput>RDP</computeroutput> - only Standard RDP Security
551 is accepted.</para>
552 </listitem>
553
554 <listitem>
555 <para>
556 <computeroutput>TLS</computeroutput> - only Enhanced RDP Security
557 is accepted. The client must support TLS.</para>
558 </listitem>
559 </itemizedlist>
560 For example the following command allows a client to use either Standard
561 or Enhanced RDP Security connection:
562 <screen>vboxmanage modifyvm "VM name" --vrdeproperty "Security/Method=negotiate"</screen>
563 </para>
564
565 <para>If the <computeroutput>Security/Method</computeroutput> property is
566 set to either <computeroutput>Negotiate</computeroutput> or
567 <computeroutput>TLS</computeroutput>, the TLS protocol will be automatically
568 used by the server, if the client supports TLS. However, in order to use TLS
569 the server must possess the Server Certificate, the Server Private Key and the
570 Certificate Authority (CA) Certificate. The following example shows how to
571 generate a server certificate.<orderedlist>
572 <listitem>
573 Create a CA self signed certificate:
574 <screen>openssl req -new -x509 -days 365 -extensions v3_ca \
575 -keyout ca_key_private.pem -out ca_cert.pem</screen>
576 </listitem>
577
578 <listitem>
579 Generate a server private key and a request for signing:
580 <screen>openssl genrsa -out server_key_private.pem
581openssl req -new -key server_key_private.pem -out server_req.pem</screen>
582 </listitem>
583
584 <listitem>
585 Generate the server certificate:
586 <screen>openssl x509 -req -days 365 -in server_req.pem \
587 -CA ca_cert.pem -CAkey ca_key_private.pem -set_serial 01 -out server_cert.pem</screen>
588 </listitem>
589 </orderedlist>
590 The server must be configured to access the required files:
591 <screen>vboxmanage modifyvm "VM name" \
592 --vrdeproperty "Security/CACertificate=path/ca_cert.pem"</screen>
593 <screen>vboxmanage modifyvm "VM name" \
594 --vrdeproperty "Security/ServerCertificate=path/server_cert.pem"</screen>
595 <screen>vboxmanage modifyvm "VM name" \
596 --vrdeproperty "Security/ServerPrivateKey=path/server_key_private.pem"</screen>
597 </para>
598 </listitem>
599 </orderedlist></para>
600
601 <para>As the client that connects to the server determines what type
602 of encryption will be used, with rdesktop, the Linux RDP viewer, use the
603 <computeroutput>-4</computeroutput> or
604 <computeroutput>-5</computeroutput> options.</para>
605 </sect2>
606
607 <sect2 id="vrde-multiconnection">
608 <title>Multiple connections to the VRDP server</title>
609
610 <para>The VRDP server of VirtualBox supports multiple simultaneous
611 connections to the same running VM from different clients. All connected
612 clients see the same screen output and share a mouse pointer and
613 keyboard focus. This is similar to several people using the same
614 computer at the same time, taking turns at the keyboard.</para>
615
616 <para>The following command enables multiple connection mode: <screen>VBoxManage modifyvm "VM name" --vrdemulticon on</screen></para>
617 </sect2>
618
619 <sect2 id="vrde-multimonitor">
620 <title>Multiple remote monitors</title>
621
622 <para>To access two or more remote VM displays you have to enable the
623 VRDP multiconnection mode (see <xref
624 linkend="vrde-multiconnection" />).</para>
625
626 <para>The RDP client can select the virtual monitor number to connect to
627 using the <computeroutput>domain</computeroutput> logon parameter
628 (<computeroutput>-d</computeroutput>). If the parameter ends with
629 <computeroutput>@</computeroutput> followed by a number, VirtualBox
630 interprets this number as the screen index. The primary guest screen is
631 selected with <computeroutput>@1</computeroutput>, the first secondary
632 screen is <computeroutput>@2</computeroutput>, etc.</para>
633
634 <para>The Microsoft RDP6 client does not let you specify a separate
635 domain name. Instead, use
636 <computeroutput>domain\username</computeroutput> in the
637 <computeroutput>Username:</computeroutput> field -- for example,
638 <computeroutput>@2\name</computeroutput>.
639 <computeroutput>name</computeroutput> must be supplied, and must be the
640 name used to log in if the VRDP server is set up to require credentials.
641 If it is not, you may use any text as the username.</para>
642 </sect2>
643
644 <sect2 id="vrde-videochannel">
645 <title>VRDP video redirection</title>
646
647 <para>Starting with VirtualBox 3.2, the VRDP server can redirect video
648 streams from the guest to the RDP client. Video frames are compressed
649 using the JPEG algorithm allowing a higher compression ratio than
650 standard RDP bitmap compression methods. It is possible to increase the
651 compression ratio by lowering the video quality.</para>
652
653 <para>The VRDP server automatically detects video streams in a guest as
654 frequently updated rectangular areas. As a result, this method works
655 with any guest operating system without having to install additional
656 software in the guest; in particular, the Guest Additions are not
657 required.</para>
658
659 <para>On the client side, however, currently only the Windows 7 Remote
660 Desktop Connection client supports this feature. If a client does not
661 support video redirection, the VRDP server falls back to regular bitmap
662 updates.</para>
663
664 <para>The following command enables video redirection: <screen>VBoxManage modifyvm "VM name" --vrdevideochannel on</screen></para>
665
666 <para>The quality of the video is defined as a value from 10 to 100
667 percent, representing a JPEG compression level (where lower numbers mean
668 lower quality but higher compression). The quality can be changed using
669 the following command: <screen>VBoxManage modifyvm "VM name" --vrdevideochannelquality 75</screen></para>
670 </sect2>
671
672 <sect2 id="vrde-customization">
673 <title>VRDP customization</title>
674
675 <para>With VirtualBox 4.0 it is possible to disable display output,
676 mouse and keyboard input, audio, remote USB or clipboard individually in
677 the VRDP server.</para>
678
679 <para>The following commands change corresponding server
680 settings:</para>
681
682 <screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=1
683VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableInput=1
684VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUSB=1
685VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableAudio=1
686VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableClipboard=1
687VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUpstreamAudio=1</screen>
688
689 <para>To reenable a feature use a similar command without the trailing
690 1. For example: <screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=</screen></para>
691
692 <para>These properties were introduced with VirtualBox 3.2.10. However,
693 in the 3.2.x series, it was necessary to use the following commands to
694 alter these settings instead:</para>
695
696 <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay" 1
697VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableInput" 1
698VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableUSB" 1
699VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableAudio" 1
700VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableClipboard" 1</screen>
701
702 <para>To reenable a feature use a similar command without the trailing
703 1. For example: <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay"</screen></para>
704 </sect2>
705 </sect1>
706
707 <sect1 id="teleporting">
708 <title>Teleporting</title>
709
710 <para>Starting with version 3.1, VirtualBox supports "teleporting" -- that
711 is, moving a virtual machine over a network from one VirtualBox host to
712 another, while the virtual machine is running. This works regardless of
713 the host operating system that is running on the hosts: you can teleport
714 virtual machines between Solaris and Mac hosts, for example.</para>
715
716 <para>Teleporting requires that a machine be currently running on one
717 host, which is then called the <emphasis role="bold">"source"</emphasis>.
718 The host to which the virtual machine will be teleported will then be
719 called the <emphasis role="bold">"target"</emphasis>; the machine on the
720 target is then configured to wait for the source to contact the target.
721 The machine's running state will then be transferred from the source to
722 the target with minimal downtime.</para>
723
724 <para>Teleporting happens over any TCP/IP network; the source and the
725 target only need to agree on a TCP/IP port which is specified in the
726 teleporting settings.</para>
727
728 <para>At this time, there are a few prerequisites for this to work,
729 however:<orderedlist>
730 <listitem>
731 <para>On the target host, you must configure a virtual machine in
732 VirtualBox with exactly the same hardware settings as the machine on
733 the source that you want to teleport. This does not apply to
734 settings which are merely descriptive, such as the VM name, but
735 obviously for teleporting to work, the target machine must have the
736 same amount of memory and other hardware settings. Otherwise
737 teleporting will fail with an error message.</para>
738 </listitem>
739
740 <listitem>
741 <para>The two virtual machines on the source and the target must
742 share the same storage (hard disks as well as floppy and CD/DVD
743 images). This means that they either use the same iSCSI targets or
744 that the storage resides somewhere on the network and both hosts
745 have access to it via NFS or SMB/CIFS.</para>
746
747 <para>This also means that neither the source nor the target machine
748 can have any snapshots.</para>
749 </listitem>
750 </orderedlist></para>
751
752 <para>Then perform the following steps:<orderedlist>
753 <listitem>
754 <para>On the <emphasis>target</emphasis> host, configure the virtual
755 machine to wait for a teleport request to arrive when it is started,
756 instead of actually attempting to start the machine. This is done
757 with the following VBoxManage command:<screen>VBoxManage modifyvm &lt;targetvmname&gt; --teleporter on --teleporterport &lt;port&gt;</screen></para>
758
759 <para>where <computeroutput>&lt;targetvmname&gt;</computeroutput> is
760 the name of the virtual machine on the target host and
761 <computeroutput>&lt;port&gt;</computeroutput> is a TCP/IP port
762 number to be used on both the source and the target hosts. For
763 example, use 6000. For details, see <xref
764 linkend="vboxmanage-modifyvm-teleport" />.</para>
765 </listitem>
766
767 <listitem>
768 <para>Start the VM on the target host. You will see that instead of
769 actually running, it will show a progress dialog. indicating that it
770 is waiting for a teleport request to arrive.</para>
771 </listitem>
772
773 <listitem>
774 <para>Start the machine on the <emphasis>source</emphasis> host as
775 usual. When it is running and you want it to be teleported, issue
776 the following command on the source host:<screen>VBoxManage controlvm &lt;sourcevmname&gt; teleport --host &lt;targethost&gt; --port &lt;port&gt;</screen></para>
777
778 <para>where <computeroutput>&lt;sourcevmname&gt;</computeroutput> is
779 the name of the virtual machine on the source host (the machine that
780 is currently running),
781 <computeroutput>&lt;targethost&gt;</computeroutput> is the host or
782 IP name of the target host on which the machine is waiting for the
783 teleport request, and <computeroutput>&lt;port&gt;</computeroutput>
784 must be the same number as specified in the command on the target
785 host. For details, see <xref
786 linkend="vboxmanage-controlvm" />.</para>
787 </listitem>
788 </orderedlist></para>
789
790 <para>For testing, you can also teleport machines on the same host; in
791 that case, use "localhost" as the hostname on both the source and the
792 target host.<note>
793 <para>In rare cases, if the CPUs of the source and the target are very
794 different, teleporting can fail with an error message, or the target
795 may hang. This may happen especially if the VM is running application
796 software that is highly optimized to run on a particular CPU without
797 correctly checking that certain CPU features are actually present.
798 VirtualBox filters what CPU capabilities are presented to the guest
799 operating system. Advanced users can attempt to restrict these virtual
800 CPU capabilities with the <computeroutput>VBoxManage --modifyvm
801 --cpuid</computeroutput> command; see <xref
802 linkend="vboxmanage-modifyvm-teleport" />.</para>
803 </note></para>
804 </sect1>
805</chapter>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette