VirtualBox

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

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

doc/manual: Move all id=... attributes from the title tags up one level, as otherwise the DocBook converters create inconsistent HTML filesi with lots of dangling links. The LaTeX converter now acts as a guard dog against reintroducing such bugs, it will take those attributes only from the correct tag and incorrect attribute use will thus lead to "undefined references" when creating the PDF manual.

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