VirtualBox

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

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

doc/manual: kdrc documentation fix

File size: 40.8 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 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
200 <computeroutput>VBoxHeadless</computeroutput> from the VirtualBox
201 Manager GUI, by holding the Shift key when starting a virtual
202 machine.
203 </para>
204 </listitem>
205 </itemizedlist>
206
207 <para>Note that when you use
208 <computeroutput>VBoxHeadless</computeroutput> to start a VM, since the
209 headless server has no other means of output, the VRDP server will
210 <emphasis>always</emphasis> be enabled, regardless of whether you had
211 enabled the VRDP server in the VM's settings. If this is undesirable
212 (for example because you want to access the VM via
213 <computeroutput>ssh</computeroutput> only), start the VM like
214 this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrde off</screen>To
215 have the VRDP server enabled depending on the VM configuration, as the
216 other front-ends would, use this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrde config</screen></para>
217
218 <para>If you start the VM with <computeroutput>VBoxManage startvm ...</computeroutput>
219 then the configuration settings of the VM are always used.</para>
220 </sect2>
221
222 <sect2>
223 <title>Step by step: creating a virtual machine on a headless
224 server</title>
225
226 <para>The following instructions may give you an idea how to create a
227 virtual machine on a headless server over a network connection. We will
228 create a virtual machine, establish an RDP connection and install a
229 guest operating system -- all without having to touch the headless
230 server. All you need is the following:</para>
231
232 <para><orderedlist>
233 <listitem>
234 <para>VirtualBox on a server machine with a supported host
235 operating system. The VirtualBox extension pack for the VRDP
236 server must be installed (see the previous section). For the
237 following example, we will assume a Linux server.</para>
238 </listitem>
239
240 <listitem>
241 <para>An ISO file accessible from the server, containing the
242 installation data for the guest operating system to install (we
243 will assume Windows XP in the following example).</para>
244 </listitem>
245
246 <listitem>
247 <para>A terminal connection to that host through which you can
248 access a command line (e.g. via
249 <computeroutput>ssh</computeroutput>).</para>
250 </listitem>
251
252 <listitem>
253 <para>An RDP viewer on the remote client; see <xref
254 linkend="rdp-viewers" /> above for examples.</para>
255 </listitem>
256 </orderedlist>Note again that on the server machine, since we will
257 only use the headless server, neither Qt nor SDL nor the X Window system
258 will be needed.</para>
259
260 <para><orderedlist>
261 <listitem>
262 <para>On the headless server, create a new virtual machine:</para>
263
264 <screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen>
265
266 <para>Note that if you do not specify
267 <computeroutput>--register</computeroutput>, you will have to
268 manually use the <computeroutput>registervm</computeroutput>
269 command later.</para>
270
271 <para>Note further that you do not need to specify
272 <computeroutput>--ostype</computeroutput>, but doing so selects
273 some sane default values for certain VM parameters, for example
274 the RAM size and the type of the virtual network device. To get a
275 complete list of supported operating systems you can use</para>
276
277 <screen>VBoxManage list ostypes</screen>
278 </listitem>
279
280 <listitem>
281 <para>Make sure the settings for this VM are appropriate for the
282 guest operating system that we will install. For example:<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen></para>
283 </listitem>
284
285 <listitem>
286 <para>Create a virtual hard disk for the VM (in this case, 10GB in
287 size):<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000</screen></para>
288 </listitem>
289
290 <listitem>
291 <para>Add an IDE Controller to the new VM:<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller"
292 --add ide --controller PIIX4</screen></para>
293 </listitem>
294
295 <listitem>
296 <para>Set the VDI file created above as the first virtual hard
297 disk of the new VM:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
298 --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen></para>
299 </listitem>
300
301 <listitem>
302 <para>Attach the ISO file that contains the operating system
303 installation that you want to install later to the virtual
304 machine, so the machine can boot from it:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
305 --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen></para>
306 </listitem>
307
308 <listitem>
309 <para>Start the virtual machine using VBoxHeadless:<screen>VBoxHeadless --startvm "Windows XP"</screen></para>
310
311 <para>If everything worked, you should see a copyright notice. If,
312 instead, you are returned to the command line, then something went
313 wrong.</para>
314 </listitem>
315
316 <listitem>
317 <para>On the client machine, fire up the RDP viewer and try to
318 connect to the server (see <xref linkend="rdp-viewers" /> above
319 for how to use various common RDP viewers).</para>
320
321 <para>You should now be seeing the installation routine of your
322 guest operating system remotely in the RDP viewer.</para>
323 </listitem>
324 </orderedlist></para>
325 </sect2>
326
327 <sect2 id="usb-over-rdp">
328 <title>Remote USB</title>
329
330 <para>As a special feature on top of the VRDP support, VirtualBox
331 supports remote USB devices over the wire as well. That is, the
332 VirtualBox guest that runs on one computer can access the USB devices of
333 the remote computer on which the VRDP data is being displayed the same
334 way as USB devices that are connected to the actual host. This allows
335 for running virtual machines on a VirtualBox host that acts as a server,
336 where a client can connect from elsewhere that needs only a network
337 adapter and a display capable of running an RDP viewer. When USB devices
338 are plugged into the client, the remote VirtualBox server can access
339 them.</para>
340
341 <para>For these remote USB devices, the same filter rules apply as for
342 other USB devices, as described with <xref linkend="settings-usb" />.
343 All you have to do is specify "Remote" (or "Any") when setting up these
344 rules.</para>
345
346 <para>Accessing remote USB devices is only possible if the RDP client
347 supports this extension. On Linux and Solaris hosts, the VirtualBox
348 installation provides a suitable VRDP client called
349 <computeroutput>rdesktop-vrdp</computeroutput>. Recent versions of
350 <computeroutput>uttsc</computeroutput>, a client tailored for the use
351 with Sun Ray thin clients, also support accessing remote USB devices.
352 RDP clients for other platforms will be provided in future VirtualBox
353 versions.</para>
354
355 <para>To make a remote USB device available to a VM,
356 <computeroutput>rdesktop-vrdp</computeroutput> should be started as
357 follows:<screen>rdesktop-vrdp -r usb -a 16 -N my.host.address</screen>Note
358 that <computeroutput>rdesktop-vrdp</computeroutput> can access USB
359 devices only through <computeroutput>/proc/bus/usb</computeroutput>.
360 Please refer to <xref linkend="ts_usb-linux" /> for further details on how
361 to properly set up the permissions. Furthermore it is advisable to
362 disable automatic loading of any host driver on the remote host which
363 might work on USB devices to ensure that the devices are accessible by
364 the RDP client. If the setup was properly done on the remote host,
365 plug/unplug events are visible on the VBox.log file of the VM.</para>
366 </sect2>
367
368 <sect2 id="vbox-auth">
369 <title>RDP authentication</title>
370
371 <para>For each virtual machine that is remotely accessible via RDP, you
372 can individually determine if and how client connections are
373 authenticated. For this, use <computeroutput>VBoxManage
374 modifyvm</computeroutput> command with the
375 <computeroutput>--vrdeauthtype</computeroutput> option; see <xref
376 linkend="vboxmanage-modifyvm" /> for a general introduction. Three
377 methods of authentication are available:<itemizedlist>
378 <listitem>
379 <para>The "null" method means that there is no authentication at
380 all; any client can connect to the VRDP server and thus the
381 virtual machine. This is, of course, very insecure and only to be
382 recommended for private networks.</para>
383 </listitem>
384
385 <listitem>
386 <para>The "external" method provides external authentication
387 through a special authentication library. VirtualBox ships with
388 two such authentication libraries:<orderedlist>
389 <listitem>
390 <para>The default authentication library,
391 <computeroutput>VBoxAuth</computeroutput>, authenticates
392 against user credentials of the hosts. Depending on the host
393 platform, this means:<itemizedlist>
394 <listitem>
395 <para>On Linux hosts,
396 <computeroutput>VBoxAuth.so</computeroutput>
397 authenticates users against the host's PAM
398 system.</para>
399 </listitem>
400
401 <listitem>
402 <para>On Windows hosts,
403 <computeroutput>VBoxAuth.dll</computeroutput>
404 authenticates users against the host's WinLogon
405 system.</para>
406 </listitem>
407
408 <listitem>
409 <para>On Mac OS X hosts,
410 <computeroutput>VBoxAuth.dylib</computeroutput>
411 authenticates users against the host's directory
412 service.<footnote>
413 <para>Support for Mac OS X was added in version
414 3.2.</para>
415 </footnote></para>
416 </listitem>
417 </itemizedlist></para>
418
419 <para>In other words, the "external" method per default
420 performs authentication with the user accounts that exist on
421 the host system. Any user with valid authentication
422 credentials is accepted, i.e. the username does not have to
423 correspond to the user running the VM.</para>
424 </listitem>
425
426 <listitem>
427 <para>An additional library called
428 <computeroutput>VBoxAuthSimple</computeroutput> performs
429 authentication against credentials configured in the
430 "extradata" section of a virtual machine's XML settings
431 file. This is probably the simplest way to get
432 authentication that does not depend on a running and
433 supported guest (see below). The following steps are
434 required:<orderedlist>
435 <listitem>
436 <para>Enable
437 <computeroutput>VBoxAuthSimple</computeroutput> with
438 the following command:</para>
439
440 <para><screen>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</screen></para>
441 </listitem>
442
443 <listitem>
444 <para>To enable the library for a particular VM, you
445 must then switch authentication to external:<screen>VBoxManage modifyvm &lt;vm&gt; --vrdeauthtype external</screen></para>
446
447 <para>Replace
448 <computeroutput>&lt;vm&gt;</computeroutput> with the
449 VM name or UUID.</para>
450 </listitem>
451
452 <listitem>
453 <para>You will then need to configure users and
454 passwords by writing items into the machine's
455 extradata. Since the XML machine settings file, into
456 whose "extradata" section the password needs to be
457 written, is a plain text file, VirtualBox uses hashes
458 to encrypt passwords. The following command must be
459 used:<screen>VBoxManage setextradata &lt;vm&gt; "VBoxAuthSimple/users/&lt;user&gt;" &lt;hash&gt;</screen></para>
460
461 <para>Replace
462 <computeroutput>&lt;vm&gt;</computeroutput> with the
463 VM name or UUID,
464 <computeroutput>&lt;user&gt;</computeroutput> with the
465 user name who should be allowed to log in and
466 <computeroutput>&lt;hash&gt;</computeroutput> with the
467 encrypted password. As an example, to obtain the hash
468 value for the password "secret", you can use the
469 following command:<screen>VBoxManage internalcommands passwordhash "secret"</screen></para>
470
471 <para>This will print
472 <screen>2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen>
473 You can then use VBoxManage setextradata to store this
474 value in the machine's "extradata" section.</para>
475
476 <para>As example, combined together, to set the
477 password for the user "john" and the machine "My VM"
478 to "secret", use this command:<screen>VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john"
479 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen></para>
480 </listitem>
481 </orderedlist></para>
482 </listitem>
483 </orderedlist></para>
484 </listitem>
485
486 <listitem>
487 <para>Finally, the "guest" authentication method performs
488 authentication with a special component that comes with the Guest
489 Additions; as a result, authentication is not performed on the
490 host, but with the <emphasis>guest</emphasis> user
491 accounts.</para>
492
493 <para>This method is currently still in testing and not yet
494 supported.</para>
495 </listitem>
496 </itemizedlist></para>
497
498 <para>In addition to the methods described above, you can replace the
499 default "external" authentication module with any other module. For
500 this, VirtualBox provides a well-defined interface that allows you to
501 write your own authentication module. This is described in detail in the
502 VirtualBox Software Development Kit (SDK) reference; please see <xref
503 linkend="VirtualBoxAPI" /> for details.</para>
504 </sect2>
505
506 <sect2 id="vrde-crypt">
507 <title>RDP encryption</title>
508
509 <para>RDP features data stream encryption, which is based on the RC4
510 symmetric cipher (with keys up to 128bit). The RC4 keys are being
511 replaced in regular intervals (every 4096 packets).</para>
512
513 <para>RDP provides different authentication methods:<orderedlist>
514 <listitem>
515 <para>Historically, RDP4 authentication was used, with which the
516 RDP client does not perform any checks in order to verify the
517 identity of the server it connects to. Since user credentials can
518 be obtained using a "man in the middle" (MITM) attack, RDP4
519 authentication is insecure and should generally not be
520 used.</para>
521 </listitem>
522
523 <listitem>
524 <para>RDP5.1 authentication employs a server certificate for which
525 the client possesses the public key. This way it is guaranteed
526 that the server possess the corresponding private key. However, as
527 this hard-coded private key became public some years ago, RDP5.1
528 authentication is also insecure.</para>
529 </listitem>
530
531 <listitem>
532 <para>RDP5.2 authentication uses the Enhanced RDP Security, which
533 means that an external security protocol is used to secure the
534 connection. RDP4 and RDP5.1 use Standard RDP Security.
535 The VRDP server supports Enhanced RDP Security with TLS protocol and,
536 as a part of TLS handshake, sends the server certificate to the
537 client.</para>
538
539 <para>The <computeroutput>Security/Method</computeroutput> VRDE
540 property sets the desired security method, which is used for a
541 connection. Valid values are:<itemizedlist>
542 <listitem>
543 <para>
544 <computeroutput>Negotiate</computeroutput> - both Enhanced (TLS)
545 and Standard RDP Security connections are allowed. The security
546 method is negotiated with the client. This is the default setting.
547 </para>
548 </listitem>
549
550 <listitem>
551 <para>
552 <computeroutput>RDP</computeroutput> - only Standard RDP Security
553 is accepted.</para>
554 </listitem>
555
556 <listitem>
557 <para>
558 <computeroutput>TLS</computeroutput> - only Enhanced RDP Security
559 is accepted. The client must support TLS.</para>
560 </listitem>
561 </itemizedlist>
562 For example the following command allows a client to use either Standard
563 or Enhanced RDP Security connection:
564 <screen>vboxmanage modifyvm "VM name" --vrdeproperty "Security/Method=negotiate"</screen>
565 </para>
566
567 <para>If the <computeroutput>Security/Method</computeroutput> property is
568 set to either <computeroutput>Negotiate</computeroutput> or
569 <computeroutput>TLS</computeroutput>, the TLS protocol will be automatically
570 used by the server, if the client supports TLS. However, in order to use TLS
571 the server must possess the Server Certificate, the Server Private Key and the
572 Certificate Authority (CA) Certificate. The following example shows how to
573 generate a server certificate.<orderedlist>
574 <listitem>
575 Create a CA self signed certificate:
576 <screen>openssl req -new -x509 -days 365 -extensions v3_ca \
577 -keyout ca_key_private.pem -out ca_cert.pem</screen>
578 </listitem>
579
580 <listitem>
581 Generate a server private key and a request for signing:
582 <screen>openssl genrsa -out server_key_private.pem
583openssl req -new -key server_key_private.pem -out server_req.pem</screen>
584 </listitem>
585
586 <listitem>
587 Generate the server certificate:
588 <screen>openssl x509 -req -days 365 -in server_req.pem \
589 -CA ca_cert.pem -CAkey ca_key_private.pem -set_serial 01 -out server_cert.pem</screen>
590 </listitem>
591 </orderedlist>
592 The server must be configured to access the required files:
593 <screen>vboxmanage modifyvm "VM name" \
594 --vrdeproperty "Security/CACertificate=path/ca_cert.pem"</screen>
595 <screen>vboxmanage modifyvm "VM name" \
596 --vrdeproperty "Security/ServerCertificate=path/server_cert.pem"</screen>
597 <screen>vboxmanage modifyvm "VM name" \
598 --vrdeproperty "Security/ServerPrivateKey=path/server_key_private.pem"</screen>
599 </para>
600 </listitem>
601 </orderedlist></para>
602
603 <para>As the client that connects to the server determines what type
604 of encryption will be used, with rdesktop, the Linux RDP viewer, use the
605 <computeroutput>-4</computeroutput> or
606 <computeroutput>-5</computeroutput> options.</para>
607 </sect2>
608
609 <sect2 id="vrde-multiconnection">
610 <title>Multiple connections to the VRDP server</title>
611
612 <para>The VRDP server of VirtualBox supports multiple simultaneous
613 connections to the same running VM from different clients. All connected
614 clients see the same screen output and share a mouse pointer and
615 keyboard focus. This is similar to several people using the same
616 computer at the same time, taking turns at the keyboard.</para>
617
618 <para>The following command enables multiple connection mode: <screen>VBoxManage modifyvm "VM name" --vrdemulticon on</screen></para>
619 </sect2>
620
621 <sect2 id="vrde-multimonitor">
622 <title>Multiple remote monitors</title>
623
624 <para>To access two or more remote VM displays you have to enable the
625 VRDP multiconnection mode (see <xref
626 linkend="vrde-multiconnection" />).</para>
627
628 <para>The RDP client can select the virtual monitor number to connect to
629 using the <computeroutput>domain</computeroutput> logon parameter
630 (<computeroutput>-d</computeroutput>). If the parameter ends with
631 <computeroutput>@</computeroutput> followed by a number, VirtualBox
632 interprets this number as the screen index. The primary guest screen is
633 selected with <computeroutput>@1</computeroutput>, the first secondary
634 screen is <computeroutput>@2</computeroutput>, etc.</para>
635
636 <para>The Microsoft RDP6 client does not let you specify a separate
637 domain name. Instead, use
638 <computeroutput>domain\username</computeroutput> in the
639 <computeroutput>Username:</computeroutput> field -- for example,
640 <computeroutput>@2\name</computeroutput>.
641 <computeroutput>name</computeroutput> must be supplied, and must be the
642 name used to log in if the VRDP server is set up to require credentials.
643 If it is not, you may use any text as the username.</para>
644 </sect2>
645
646 <sect2 id="vrde-videochannel">
647 <title>VRDP video redirection</title>
648
649 <para>Starting with VirtualBox 3.2, the VRDP server can redirect video
650 streams from the guest to the RDP client. Video frames are compressed
651 using the JPEG algorithm allowing a higher compression ratio than
652 standard RDP bitmap compression methods. It is possible to increase the
653 compression ratio by lowering the video quality.</para>
654
655 <para>The VRDP server automatically detects video streams in a guest as
656 frequently updated rectangular areas. As a result, this method works
657 with any guest operating system without having to install additional
658 software in the guest; in particular, the Guest Additions are not
659 required.</para>
660
661 <para>On the client side, however, currently only the Windows 7 Remote
662 Desktop Connection client supports this feature. If a client does not
663 support video redirection, the VRDP server falls back to regular bitmap
664 updates.</para>
665
666 <para>The following command enables video redirection: <screen>VBoxManage modifyvm "VM name" --vrdevideochannel on</screen></para>
667
668 <para>The quality of the video is defined as a value from 10 to 100
669 percent, representing a JPEG compression level (where lower numbers mean
670 lower quality but higher compression). The quality can be changed using
671 the following command: <screen>VBoxManage modifyvm "VM name" --vrdevideochannelquality 75</screen></para>
672 </sect2>
673
674 <sect2 id="vrde-customization">
675 <title>VRDP customization</title>
676
677 <para>With VirtualBox 4.0 it is possible to disable display output,
678 mouse and keyboard input, audio, remote USB or clipboard individually in
679 the VRDP server.</para>
680
681 <para>The following commands change corresponding server
682 settings:</para>
683
684 <screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=1
685VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableInput=1
686VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUSB=1
687VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableAudio=1
688VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableClipboard=1
689VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUpstreamAudio=1</screen>
690
691 <para>To reenable a feature use a similar command without the trailing
692 1. For example: <screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=</screen></para>
693
694 <para>These properties were introduced with VirtualBox 3.2.10. However,
695 in the 3.2.x series, it was necessary to use the following commands to
696 alter these settings instead:</para>
697
698 <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay" 1
699VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableInput" 1
700VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableUSB" 1
701VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableAudio" 1
702VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableClipboard" 1</screen>
703
704 <para>To reenable a feature use a similar command without the trailing
705 1. For example: <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay"</screen></para>
706 </sect2>
707 </sect1>
708
709 <sect1 id="teleporting">
710 <title>Teleporting</title>
711
712 <para>Starting with version 3.1, VirtualBox supports "teleporting" -- that
713 is, moving a virtual machine over a network from one VirtualBox host to
714 another, while the virtual machine is running. This works regardless of
715 the host operating system that is running on the hosts: you can teleport
716 virtual machines between Solaris and Mac hosts, for example.</para>
717
718 <para>Teleporting requires that a machine be currently running on one
719 host, which is then called the <emphasis role="bold">"source"</emphasis>.
720 The host to which the virtual machine will be teleported will then be
721 called the <emphasis role="bold">"target"</emphasis>; the machine on the
722 target is then configured to wait for the source to contact the target.
723 The machine's running state will then be transferred from the source to
724 the target with minimal downtime.</para>
725
726 <para>Teleporting happens over any TCP/IP network; the source and the
727 target only need to agree on a TCP/IP port which is specified in the
728 teleporting settings.</para>
729
730 <para>At this time, there are a few prerequisites for this to work,
731 however:<orderedlist>
732 <listitem>
733 <para>On the target host, you must configure a virtual machine in
734 VirtualBox with exactly the same hardware settings as the machine on
735 the source that you want to teleport. This does not apply to
736 settings which are merely descriptive, such as the VM name, but
737 obviously for teleporting to work, the target machine must have the
738 same amount of memory and other hardware settings. Otherwise
739 teleporting will fail with an error message.</para>
740 </listitem>
741
742 <listitem>
743 <para>The two virtual machines on the source and the target must
744 share the same storage (hard disks as well as floppy and CD/DVD
745 images). This means that they either use the same iSCSI targets or
746 that the storage resides somewhere on the network and both hosts
747 have access to it via NFS or SMB/CIFS.</para>
748
749 <para>This also means that neither the source nor the target machine
750 can have any snapshots.</para>
751 </listitem>
752 </orderedlist></para>
753
754 <para>Then perform the following steps:<orderedlist>
755 <listitem>
756 <para>On the <emphasis>target</emphasis> host, configure the virtual
757 machine to wait for a teleport request to arrive when it is started,
758 instead of actually attempting to start the machine. This is done
759 with the following VBoxManage command:<screen>VBoxManage modifyvm &lt;targetvmname&gt; --teleporter on --teleporterport &lt;port&gt;</screen></para>
760
761 <para>where <computeroutput>&lt;targetvmname&gt;</computeroutput> is
762 the name of the virtual machine on the target host and
763 <computeroutput>&lt;port&gt;</computeroutput> is a TCP/IP port
764 number to be used on both the source and the target hosts. For
765 example, use 6000. For details, see <xref
766 linkend="vboxmanage-modifyvm-teleport" />.</para>
767 </listitem>
768
769 <listitem>
770 <para>Start the VM on the target host. You will see that instead of
771 actually running, it will show a progress dialog. indicating that it
772 is waiting for a teleport request to arrive.</para>
773 </listitem>
774
775 <listitem>
776 <para>Start the machine on the <emphasis>source</emphasis> host as
777 usual. When it is running and you want it to be teleported, issue
778 the following command on the source host:<screen>VBoxManage controlvm &lt;sourcevmname&gt; teleport --host &lt;targethost&gt; --port &lt;port&gt;</screen></para>
779
780 <para>where <computeroutput>&lt;sourcevmname&gt;</computeroutput> is
781 the name of the virtual machine on the source host (the machine that
782 is currently running),
783 <computeroutput>&lt;targethost&gt;</computeroutput> is the host or
784 IP name of the target host on which the machine is waiting for the
785 teleport request, and <computeroutput>&lt;port&gt;</computeroutput>
786 must be the same number as specified in the command on the target
787 host. For details, see <xref
788 linkend="vboxmanage-controlvm" />.</para>
789 </listitem>
790 </orderedlist></para>
791
792 <para>For testing, you can also teleport machines on the same host; in
793 that case, use "localhost" as the hostname on both the source and the
794 target host.<note>
795 <para>In rare cases, if the CPUs of the source and the target are very
796 different, teleporting can fail with an error message, or the target
797 may hang. This may happen especially if the VM is running application
798 software that is highly optimized to run on a particular CPU without
799 correctly checking that certain CPU features are actually present.
800 VirtualBox filters what CPU capabilities are presented to the guest
801 operating system. Advanced users can attempt to restrict these virtual
802 CPU capabilities with the <computeroutput>VBoxManage --modifyvm
803 --cpuid</computeroutput> command; see <xref
804 linkend="vboxmanage-modifyvm-teleport" />.</para>
805 </note></para>
806 </sect1>
807</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