VirtualBox

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

Last change on this file since 83876 was 82350, checked in by vboxsync, 5 years ago

manual: integrate 6.1 drop #10 with minimal manual adjustments (frontmatter for preface and eliminated trailing whitespace)

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 43.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
4<!ENTITY % all.entities SYSTEM "all-entities.ent">
5%all.entities;
6]>
7<chapter id="remotevm">
8
9 <title>Remote Virtual Machines</title>
10
11 <sect1 id="vrde">
12
13 <title>Remote Display (VRDP Support)</title>
14
15 <para>
16 &product-name; can display virtual machines remotely, meaning that
17 a virtual machine can execute on one computer even though the
18 machine will be displayed on a second computer, and the machine
19 will be controlled from there as well, as if the virtual machine
20 was running on that second computer.
21 </para>
22
23 <para>
24 For maximum flexibility, &product-name; implements remote machine
25 display through a generic extension interface called the
26 VirtualBox Remote Desktop Extension (VRDE). The base open source
27 &product-name; package only provides this interface, while
28 implementations can be supplied by third parties with
29 &product-name; extension packages, which must be installed
30 separately from the base package. See
31 <xref linkend="intro-installing" />.
32 </para>
33
34 <para>
35 Oracle provides support for the VirtualBox Remote Display Protocol
36 (VRDP) in such an &product-name; extension package.
37 </para>
38
39 <para>
40 VRDP is a backwards-compatible extension to Microsoft's Remote
41 Desktop Protocol (RDP). As a result, you can use any standard RDP
42 client to control the remote VM.
43 </para>
44
45 <para>
46 Even when the extension is installed, the VRDP server is disabled
47 by default. It can easily be enabled on a per-VM basis either in
48 the VirtualBox Manager in the
49 <emphasis role="bold">Display</emphasis> settings, see
50 <xref linkend="settings-display" />, or with the
51 <command>VBoxManage</command> command, as follows:
52 </para>
53
54<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde on</screen>
55
56 <para>
57 By default, the VRDP server uses TCP port <literal>3389</literal>.
58 You will need to change the default port if you run more than one
59 VRDP server, since the port can only be used by one server at a
60 time. You might also need to change it on Windows hosts since the
61 default port might already be used by the RDP server that is built
62 into Windows itself. Ports 5000 through 5050 are typically not
63 used and might be a good choice.
64 </para>
65
66 <para>
67 The port can be changed either in the
68 <emphasis role="bold">Display</emphasis> settings of the graphical
69 user interface or with the <option>--vrdeport</option> option of
70 the <command>VBoxManage modifyvm</command> command. You can
71 specify a comma-separated list of ports or ranges of ports. Use a
72 dash between two port numbers to specify a range. The VRDP server
73 will bind to <emphasis>one</emphasis> of the available ports from
74 the specified list. For example, <command>VBoxManage modifyvm
75 <replaceable>VM-name</replaceable> --vrdeport
76 5000,5010-5012</command> configures the server to bind to one of
77 the ports 5000, 5010, 5011, or 5012. See
78 <xref linkend="vboxmanage-modifyvm" />.
79 </para>
80
81 <para>
82 The actual port used by a running VM can be either queried with
83 the <command>VBoxManage showvminfo</command> command or seen in
84 the GUI on the <emphasis role="bold">Runtime</emphasis> tab of the
85 <emphasis role="bold">Session Information</emphasis> dialog, which
86 is accessible from the <emphasis role="bold">Machine</emphasis>
87 menu of the VM window.
88 </para>
89
90 <para>
91 &product-name; supports IPv6. If the host OS supports IPv6 the
92 VRDP server will automatically listen for IPv6 connections in
93 addition to IPv4.
94 </para>
95
96 <sect2 id="rdp-viewers">
97
98 <title>Common Third-Party RDP Viewers</title>
99
100 <para>
101 Since VRDP is backwards-compatible to RDP, you can use any
102 standard RDP viewer to connect to such a remote virtual machine.
103 For this to work, you must specify the IP address of your
104 <emphasis>host</emphasis> system, not of the virtual machine, as
105 the server address to connect to. You must also specify the port
106 number that the VRDP server is using.
107 </para>
108
109 <para>
110 The following examples are for the most common RDP viewers:
111 </para>
112
113 <itemizedlist>
114
115 <listitem>
116 <para>
117 On Windows, you can use the Microsoft Terminal Services
118 Connector, <command>mstsc.exe</command>, that is included
119 with Windows. Press the Windows key + R, to display the
120 <emphasis role="bold">Run</emphasis> dialog. Enter
121 <command>mstsc</command> to start the program. You can also
122 find the program in <emphasis role="bold">Start</emphasis>,
123 <emphasis role="bold">All Programs</emphasis>,
124 <emphasis role="bold">Accessories</emphasis>,
125 <emphasis role="bold">Remote Desktop Connection</emphasis>.
126 If you use the <emphasis role="bold">Run</emphasis> dialog,
127 you can enter options directly. For example:
128 </para>
129
130<screen>mstsc 1.2.3.4:3389</screen>
131
132 <para>
133 Replace <literal>1.2.3.4</literal> with the host IP address,
134 and <literal>3389</literal> with a different port, if
135 necessary.
136 </para>
137
138 <note>
139 <itemizedlist>
140
141 <listitem>
142 <para>
143 IPv6 addresses must be enclosed in square brackets to
144 specify a port. For example: <literal>mstsc
145 [fe80::1:2:3:4]:3389</literal>
146 </para>
147 </listitem>
148
149 <listitem>
150 <para>
151 When connecting to localhost in order to test the
152 connection, the addresses <literal>localhost</literal>
153 and <literal>127.0.0.1</literal> might not work using
154 <command>mstsc.exe</command>. Instead, the address
155 <literal>127.0.0.2[:3389]</literal> has to be used.
156 </para>
157 </listitem>
158
159 </itemizedlist>
160 </note>
161 </listitem>
162
163 <listitem>
164 <para>
165 On other systems, you can use the standard open source
166 <command>rdesktop</command> program. This ships with most
167 Linux distributions, but &product-name; also comes with a
168 modified variant of <command>rdesktop</command> for remote
169 USB support. See <xref linkend="usb-over-rdp" />.
170 </para>
171
172 <para>
173 With <command>rdesktop</command>, use a command line such as
174 the following:
175 </para>
176
177<screen>$ rdesktop -a 16 -N 1.2.3.4:3389</screen>
178
179 <para>
180 Replace <literal>1.2.3.4</literal> with the host IP address,
181 and <literal>3389</literal> with a different port, if
182 necessary. The <option>-a 16</option> option requests a
183 color depth of 16 bits per pixel, which we recommend. For
184 best performance, after installation of the guest operating
185 system, you should set its display color depth to the same
186 value. The <option>-N</option> option enables use of the
187 NumPad keys.
188 </para>
189 </listitem>
190
191 <listitem>
192 <para>
193 You can use the Remmina remote desktop client with VRDP.
194 This application is included with some Linux distributions,
195 such as Debian and Ubuntu.
196 </para>
197 </listitem>
198
199 <listitem>
200 <para>
201 If you run the KDE desktop, you can use
202 <command>krdc</command>, the KDE RDP viewer. A typical
203 command line is as follows:
204 </para>
205
206<screen>$ krdc rdp://1.2.3.4:3389</screen>
207
208 <para>
209 Replace <literal>1.2.3.4</literal> with the host IP address,
210 and <literal>3389</literal> with a different port, if
211 necessary. The <literal>rdp:// </literal> prefix is required
212 with <command>krdc</command> to switch it into RDP mode.
213 </para>
214 </listitem>
215
216 <listitem>
217 <para>
218 With Sun Ray thin clients you can use
219 <command>uttsc</command>, which is part of the Sun Ray
220 Windows Connector package. See the Sun Ray documentation for
221 details.
222 </para>
223 </listitem>
224
225 </itemizedlist>
226
227 </sect2>
228
229 <sect2 id="vboxheadless">
230
231 <title>VBoxHeadless, the Remote Desktop Server</title>
232
233 <para>
234 While any VM started from the VirtualBox Manager is capable of
235 running virtual machines remotely, it is not convenient to have
236 to run the full GUI if you never want to have VMs displayed
237 locally in the first place. In particular, if you are running
238 server hardware whose only purpose is to host VMs, and all your
239 VMs are supposed to run remotely over VRDP, then it is pointless
240 to have a graphical user interface on the server at all. This is
241 especially true for Linux or Oracle Solaris hosts, as the
242 VirtualBox Manager comes with dependencies on the Qt and SDL
243 libraries. This is inconvenient if you would rather not have the
244 X Window system on your server at all.
245 </para>
246
247 <para>
248 &product-name; therefore comes with a front-end called
249 <command>VBoxHeadless</command>, which produces no visible
250 output on the host at all, but still can optionally deliver VRDP
251 data. This front-end has no dependencies on the X Window system
252 on Linux and Oracle Solaris hosts.
253 </para>
254
255 <note>
256 <para>
257 In legacy releases of &product-name;, the headless server was
258 called <command>VBoxVRDP</command>. For backwards
259 compatibility, the &product-name; installation still includes
260 an executable with that name.
261 </para>
262 </note>
263
264 <para>
265 To start a virtual machine with <command>VBoxHeadless</command>,
266 you have the following options:
267 </para>
268
269 <itemizedlist>
270
271 <listitem>
272 <para>
273 Use the <command>VBoxManage</command> command, as follows:
274 </para>
275
276<screen>$ VBoxManage startvm <replaceable>VM-name</replaceable> --type headless</screen>
277
278 <para>
279 The <option>--type</option> option causes &product-name; to
280 use <command>VBoxHeadless</command> as the front-end to the
281 internal virtualization engine, instead of the Qt front-end.
282 </para>
283 </listitem>
284
285 <listitem>
286 <para>
287 Use the <command>VBoxHeadless</command> command, as follows:
288 </para>
289
290<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></screen>
291
292 <para>
293 This way of starting the VM helps troubleshooting problems
294 reported by <command>VBoxManage startvm</command>, because
295 you can sometimes see more detailed error messages,
296 especially for early failures before the VM execution is
297 started. In normal situations <command>VBoxManage
298 startvm</command> is preferred, since it runs the VM
299 directly as a background process which has to be done
300 explicitly when directly starting with
301 <command>VBoxHeadless</command>. The full documentation of
302 the command is in <xref linkend="man_vboxheadless"/>.
303 </para>
304 </listitem>
305
306 <listitem>
307 <para>
308 Start <command>VBoxHeadless</command> from the VirtualBox
309 Manager GUI, by pressing the Shift key when starting a
310 virtual machine or by selecting
311 <emphasis role="bold">Headless Start</emphasis> from the
312 <emphasis role="bold">Machine</emphasis> menu.
313 </para>
314 </listitem>
315
316 </itemizedlist>
317
318 <para>
319 When you use the <command>VBoxHeadless</command> command to
320 start a VM, the VRDP server will be enabled according to the VM
321 configuration. You can override the VM's setting using
322 <option>--vrde</option> command line parameter. To enable the
323 VRDP server, start the VM as follows:
324 </para>
325
326<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> --vrde on</screen>
327
328 <para>
329 To disable the VRDP server:
330 </para>
331
332<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> --vrde off</screen>
333
334 <para>
335 To have the VRDP server enabled depending on the VM
336 configuration, as for other front-ends:
337 </para>
338
339<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> --vrde config</screen>
340
341 <para>
342 This command is the same as the following:
343 </para>
344
345<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></screen>
346
347 <para>
348 If you start the VM with <command>VBoxManage startvm</command>
349 then the configuration settings of the VM are always used.
350 </para>
351
352 </sect2>
353
354 <sect2 id="headless-vm-steps">
355
356 <title>Step by Step: Creating a Virtual Machine on a Headless Server</title>
357
358 <para>
359 The following instructions describe how to create a virtual
360 machine on a headless server over a network connection. This
361 example creates a virtual machine, establishes an RDP connection
362 and installs a guest operating system. All of these tasks are
363 done without having to touch the headless server. You need the
364 following prerequisites:
365 </para>
366
367 <itemizedlist>
368
369 <listitem>
370 <para>
371 &product-name; on a server machine with a supported host
372 operating system. The &product-name; Extension Pack for the
373 VRDP server must be installed, see <xref linkend="vrde"/>.
374 The procedures assume a Linux server is used.
375 </para>
376 </listitem>
377
378 <listitem>
379 <para>
380 An ISO file accessible from the server, containing the
381 installation data for the guest operating system to install.
382 Windows XP is used in the example.
383 </para>
384 </listitem>
385
386 <listitem>
387 <para>
388 A terminal connection to that host through which you can
389 access a command line, such as <command>ssh</command>.
390 </para>
391 </listitem>
392
393 <listitem>
394 <para>
395 An RDP viewer on the remote client. See
396 <xref linkend="rdp-viewers" /> for examples.
397 </para>
398 </listitem>
399
400 </itemizedlist>
401
402 <para>
403 Note that on the server machine, since we will only use the
404 headless server, Qt and the X Window system are not required.
405 </para>
406
407 <orderedlist>
408
409 <listitem>
410 <para>
411 On the headless server, create a new virtual machine. For
412 example:
413 </para>
414
415<screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen>
416
417 <para>
418 If you do not specify <option>--register</option>, you will
419 have to manually use the <command>registervm</command>
420 command later.
421 </para>
422
423 <para>
424 You do not need to specify <option>--ostype</option>, but
425 doing so selects some sensible default values for certain VM
426 parameters. For example, the RAM size and the type of the
427 virtual network device. To get a complete list of supported
428 operating systems you can use the following command:
429 </para>
430
431<screen>VBoxManage list ostypes</screen>
432 </listitem>
433
434 <listitem>
435 <para>
436 Make sure the settings for the VM are appropriate for the
437 guest operating system that we will install. For example:
438 </para>
439
440<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen>
441 </listitem>
442
443 <listitem>
444 <para>
445 Create a virtual hard disk for the VM. For example, to
446 create a 10 GB virtual hard disk:
447 </para>
448
449<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000</screen>
450 </listitem>
451
452 <listitem>
453 <para>
454 Add an IDE Controller to the new VM. For example:
455 </para>
456
457<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller"
458 --add ide --controller PIIX4</screen>
459 </listitem>
460
461 <listitem>
462 <para>
463 Set the VDI file you created as the first virtual hard disk
464 of the new VM. For example:
465 </para>
466
467<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
468 --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen>
469 </listitem>
470
471 <listitem>
472 <para>
473 Attach the ISO file that contains the operating system
474 installation that you want to install later to the virtual
475 machine. This is done so that the VM can boot from it.
476 </para>
477
478<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
479 --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen>
480 </listitem>
481
482 <listitem>
483 <para>
484 Enable the VirtualBox Remote Desktop Extension, the VRDP
485 server, as follows:
486 </para>
487
488<screen>VBoxManage modifyvm "Windows XP" --vrde on</screen>
489 </listitem>
490
491 <listitem>
492 <para>
493 Start the virtual machine using the
494 <command>VBoxHeadless</command> command:
495 </para>
496
497<screen>VBoxHeadless --startvm "Windows XP"</screen>
498
499 <para>
500 If the configuration steps worked, you should see a
501 copyright notice. If you are returned to the command line,
502 then something did not work correctly.
503 </para>
504 </listitem>
505
506 <listitem>
507 <para>
508 On the client machine, start the RDP viewer and connect to
509 the server. See <xref linkend="rdp-viewers" /> for details
510 of how to use various common RDP viewers.
511 </para>
512
513 <para>
514 The installation routine of your guest operating system
515 should be displayed in the RDP viewer.
516 </para>
517 </listitem>
518
519 </orderedlist>
520
521 </sect2>
522
523 <sect2 id="usb-over-rdp">
524
525 <title>Remote USB</title>
526
527 <para>
528 As a special feature additional to the VRDP support,
529 &product-name; also supports remote USB devices over the wire.
530 That is, an &product-name; guest that runs on one computer can
531 access the USB devices of the remote computer on which the VRDP
532 data is being displayed the same way as USB devices that are
533 connected to the actual host. This enables running of virtual
534 machines on an &product-name; host that acts as a server, where
535 a client can connect from elsewhere that needs only a network
536 adapter and a display capable of running an RDP viewer. When USB
537 devices are plugged into the client, the remote &product-name;
538 server can access them.
539 </para>
540
541 <para>
542 For these remote USB devices, the same filter rules apply as for
543 other USB devices. See <xref linkend="settings-usb" />. All you
544 have to do is specify Remote, or Any, when setting up these
545 rules.
546 </para>
547
548 <para>
549 Accessing remote USB devices is only possible if the RDP client
550 supports this extension. On Linux and Oracle Solaris hosts, the
551 &product-name; installation provides a suitable VRDP client
552 called <command>rdesktop-vrdp</command>. Some versions of
553 <command>uttsc</command>, a client tailored for the use with Sun
554 Ray thin clients, also support accessing remote USB devices. RDP
555 clients for other platforms will be provided in future
556 &product-name; versions.
557 </para>
558
559 <para>
560 To make a remote USB device available to a VM,
561 <command>rdesktop-vrdp</command> should be started as follows:
562 </para>
563
564<screen>rdesktop-vrdp -r usb -a 16 -N my.host.address</screen>
565
566 <para>
567 See <xref linkend="ts_usb-linux" /> for further details on how
568 to properly set up the permissions for USB devices. Furthermore
569 it is advisable to disable automatic loading of any host driver
570 on the remote host which might work on USB devices to ensure
571 that the devices are accessible by the RDP client. If the setup
572 was properly done on the remote host, plug and unplug events are
573 visible in the VBox.log file of the VM.
574 </para>
575
576 </sect2>
577
578 <sect2 id="vbox-auth">
579
580 <title>RDP Authentication</title>
581
582 <para>
583 For each virtual machine that is remotely accessible using RDP,
584 you can individually determine if and how client connections are
585 authenticated. For this, use the <command>VBoxManage
586 modifyvm</command> command with the
587 <option>--vrdeauthtype</option> option. See
588 <xref linkend="vboxmanage-modifyvm" />. The following methods of
589 authentication are available:
590 </para>
591
592 <itemizedlist>
593
594 <listitem>
595 <para>
596 The <emphasis role="bold">null</emphasis> method means that
597 there is no authentication at all. Any client can connect to
598 the VRDP server and thus the virtual machine. This is very
599 insecure and only to be recommended for private networks.
600 </para>
601 </listitem>
602
603 <listitem>
604 <para>
605 The <emphasis role="bold">external</emphasis> method
606 provides external authentication through a special
607 authentication library. &product-name; ships with two
608 special authentication libraries:
609 </para>
610
611 <orderedlist>
612
613 <listitem>
614 <para>
615 The default authentication library,
616 <command>VBoxAuth</command>, authenticates against user
617 credentials of the hosts. Depending on the host
618 platform, this means the following:
619 </para>
620
621 <itemizedlist>
622
623 <listitem>
624 <para>
625 On Linux hosts, <command>VBoxAuth.so</command>
626 authenticates users against the host's PAM system.
627 </para>
628 </listitem>
629
630 <listitem>
631 <para>
632 On Windows hosts, <command>VBoxAuth.dll</command>
633 authenticates users against the host's WinLogon
634 system.
635 </para>
636 </listitem>
637
638 <listitem>
639 <para>
640 On Mac OS X hosts, <command>VBoxAuth.dylib</command>
641 authenticates users against the host's directory
642 service.
643 </para>
644 </listitem>
645
646 </itemizedlist>
647
648 <para>
649 In other words, the external method by default performs
650 authentication with the user accounts that exist on the
651 host system. Any user with valid authentication
652 credentials is accepted. For example, the username does
653 not have to correspond to the user running the VM.
654 </para>
655 </listitem>
656
657 <listitem>
658 <para>
659 An additional library called
660 <command>VBoxAuthSimple</command> performs
661 authentication against credentials configured in the
662 <literal>extradata</literal> section of a virtual
663 machine's XML settings file. This is probably the
664 simplest way to get authentication that does not depend
665 on a running and supported guest. The following steps
666 are required:
667 </para>
668
669 <orderedlist>
670
671 <listitem>
672 <para>
673 Enable <command>VBoxAuthSimple</command> with the
674 following command:
675 </para>
676
677<screen>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</screen>
678 </listitem>
679
680 <listitem>
681 <para>
682 To enable the library for a particular VM, you must
683 switch authentication to external, as follows:
684 </para>
685
686<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrdeauthtype external</screen>
687
688 <para>
689 Replace <replaceable>VM-name</replaceable> with the
690 VM name or UUID.
691 </para>
692 </listitem>
693
694 <listitem>
695 <para>
696 You then need to configure users and passwords by
697 writing items into the machine's extradata. Since
698 the XML machine settings file, into whose
699 <literal>extradata</literal> section the password
700 needs to be written, is a plain text file,
701 &product-name; uses hashes to encrypt passwords. The
702 following command must be used:
703 </para>
704
705<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxAuthSimple/users/<replaceable>user</replaceable>" <replaceable>hash</replaceable></screen>
706
707 <para>
708 Replace <replaceable>VM-name</replaceable> with the
709 VM name or UUID, <replaceable>user</replaceable>
710 with the user name who should be allowed to log in
711 and <replaceable>hash</replaceable> with the
712 encrypted password. The following command example
713 obtains the hash value for the password
714 <literal>secret</literal>:
715 </para>
716
717<screen>$ VBoxManage internalcommands passwordhash "secret"
7182bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen>
719
720 <para>
721 You then use <command>VBoxManage
722 setextradata</command> to store this value in the
723 machine's <literal>extradata</literal> section.
724 </para>
725
726 <para>
727 As a combined example, to set the password for the
728 user <literal>john</literal> and the machine
729 <literal>My VM</literal> to
730 <literal>secret</literal>, use this command:
731 </para>
732
733<screen>VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john"
734 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen>
735 </listitem>
736
737 </orderedlist>
738 </listitem>
739
740 </orderedlist>
741 </listitem>
742
743 <listitem>
744 <para>
745 The <emphasis role="bold">guest</emphasis> authentication
746 method performs authentication with a special component that
747 comes with the Guest Additions. As a result, authentication
748 is not performed on the host, but with the guest user
749 accounts.
750 </para>
751
752 <para>
753 This method is currently still in testing and not yet
754 supported.
755 </para>
756 </listitem>
757
758 </itemizedlist>
759
760 <para>
761 In addition to the methods described above, you can replace the
762 default external authentication module with any other module.
763 For this, &product-name; provides a well-defined interface that
764 enables you to write your own authentication module. This is
765 described in detail in the &product-name; Software Development
766 Kit (SDK) reference. See <xref linkend="VirtualBoxAPI" />.
767 </para>
768
769 </sect2>
770
771 <sect2 id="vrde-crypt">
772
773 <title>RDP Encryption</title>
774
775 <para>
776 RDP features data stream encryption, which is based on the RC4
777 symmetric cipher, with keys up to 128-bit. The RC4 keys are
778 replaced at regular intervals, every 4096 packets.
779 </para>
780
781 <para>
782 RDP provides the following different authentication methods:
783 </para>
784
785 <itemizedlist>
786
787 <listitem>
788 <para>
789 <emphasis role="bold">RDP 4</emphasis> authentication was
790 used historically. With RDP 4, the RDP client does not
791 perform any checks in order to verify the identity of the
792 server it connects to. Since user credentials can be
793 obtained using a man in the middle (MITM) attack, RDP4
794 authentication is insecure and should generally not be used.
795 </para>
796 </listitem>
797
798 <listitem>
799 <para>
800 <emphasis role="bold">RDP 5.1</emphasis> authentication
801 employs a server certificate for which the client possesses
802 the public key. This way it is guaranteed that the server
803 possess the corresponding private key. However, as this
804 hard-coded private key became public some years ago, RDP 5.1
805 authentication is also insecure.
806 </para>
807 </listitem>
808
809 <listitem>
810 <para>
811 <emphasis role="bold">RDP 5.2 or later</emphasis>
812 authentication uses Enhanced RDP Security, which means that
813 an external security protocol is used to secure the
814 connection. RDP 4 and RDP 5.1 use Standard RDP Security. The
815 VRDP server supports Enhanced RDP Security with TLS protocol
816 and, as a part of the TLS handshake, sends the server
817 certificate to the client.
818 </para>
819
820 <para>
821 The <literal>Security/Method</literal> VRDE property sets
822 the desired security method, which is used for a connection.
823 Valid values are as follows:
824 </para>
825
826 <itemizedlist>
827
828 <listitem>
829 <para>
830 <emphasis role="bold">Negotiate.</emphasis> Both
831 Enhanced (TLS) and Standard RDP Security connections are
832 allowed. The security method is negotiated with the
833 client. This is the default setting.
834 </para>
835 </listitem>
836
837 <listitem>
838 <para>
839 <emphasis role="bold">RDP.</emphasis> Only Standard RDP
840 Security is accepted.
841 </para>
842 </listitem>
843
844 <listitem>
845 <para>
846 <emphasis role="bold">TLS.</emphasis> Only Enhanced RDP
847 Security is accepted. The client must support TLS.
848 </para>
849
850 <para>
851 The version of OpenSSL used by &product-name; supports
852 TLS versions 1.0, 1.1, 1.2, and 1.3.
853 </para>
854 </listitem>
855
856 </itemizedlist>
857
858 <para>
859 For example, the following command enables a client to use
860 either Standard or Enhanced RDP Security connection:
861 </para>
862
863<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> --vrdeproperty "Security/Method=negotiate"</screen>
864
865 <para>
866 If the <literal>Security/Method</literal> property is set to
867 either Negotiate or TLS, the TLS protocol will be
868 automatically used by the server, if the client supports
869 TLS. However, in order to use TLS the server must possess
870 the Server Certificate, the Server Private Key and the
871 Certificate Authority (CA) Certificate. The following
872 example shows how to generate a server certificate.
873 </para>
874
875 <orderedlist>
876
877 <listitem>
878 <para>
879 Create a CA self signed certificate.
880 </para>
881
882<screen>openssl req -new -x509 -days 365 -extensions v3_ca \
883 -keyout ca_key_private.pem -out ca_cert.pem</screen>
884 </listitem>
885
886 <listitem>
887 <para>
888 Generate a server private key and a request for signing.
889 </para>
890
891<screen>openssl genrsa -out server_key_private.pem
892openssl req -new -key server_key_private.pem -out server_req.pem</screen>
893 </listitem>
894
895 <listitem>
896 <para>
897 Generate the server certificate.
898 </para>
899
900<screen>openssl x509 -req -days 365 -in server_req.pem \
901 -CA ca_cert.pem -CAkey ca_key_private.pem -set_serial 01 -out server_cert.pem</screen>
902 </listitem>
903
904 </orderedlist>
905
906 <para>
907 The server must be configured to access the required files.
908 For example:
909 </para>
910
911<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> \
912 --vrdeproperty "Security/CACertificate=path/ca_cert.pem"</screen>
913
914<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> \
915 --vrdeproperty "Security/ServerCertificate=path/server_cert.pem"</screen>
916
917<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> \
918 --vrdeproperty "Security/ServerPrivateKey=path/server_key_private.pem"</screen>
919 </listitem>
920
921 </itemizedlist>
922
923 <para>
924 As the client that connects to the server determines what type
925 of encryption will be used, with <command>rdesktop</command>,
926 the Linux RDP viewer, use the <option>-4</option> or
927 <option>-5</option> options.
928 </para>
929
930 </sect2>
931
932 <sect2 id="vrde-multiconnection">
933
934 <title>Multiple Connections to the VRDP Server</title>
935
936 <para>
937 The VRDP server of &product-name; supports multiple simultaneous
938 connections to the same running VM from different clients. All
939 connected clients see the same screen output and share a mouse
940 pointer and keyboard focus. This is similar to several people
941 using the same computer at the same time, taking turns at the
942 keyboard.
943 </para>
944
945 <para>
946 The following command enables multiple connection mode:
947 </para>
948
949<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrdemulticon on</screen>
950
951 </sect2>
952
953 <sect2 id="vrde-multimonitor">
954
955 <title>Multiple Remote Monitors</title>
956
957 <para>
958 To access two or more remote VM displays you have to enable the
959 VRDP multiconnection mode. See
960 <xref linkend="vrde-multiconnection"/>.
961 </para>
962
963 <para>
964 The RDP client can select the virtual monitor number to connect
965 to using the <literal>domain</literal> login parameter
966 (<option>-d</option>). If the parameter ends with
967 <literal>@</literal> followed by a number, &product-name;
968 interprets this number as the screen index. The primary guest
969 screen is selected with <literal>@1</literal>, the first
970 secondary screen is <literal>@2</literal>, and so on.
971 </para>
972
973 <para>
974 The Microsoft RDP 6 client does not let you specify a separate
975 domain name. Instead, enter
976 <literal><replaceable>domain</replaceable>\<replaceable>username</replaceable></literal>
977 in the <emphasis role="bold">Username</emphasis> field. For
978 example, <literal>@2\<replaceable>name</replaceable></literal>.
979 <replaceable>name</replaceable> must be supplied, and must be
980 the name used to log in if the VRDP server is set up to require
981 credentials. If it is not, you may use any text as the username.
982 </para>
983
984 </sect2>
985
986 <sect2 id="vrde-videochannel">
987
988 <title>VRDP Video Redirection</title>
989
990 <para>
991 The VRDP server can redirect video streams from the guest to the
992 RDP client. Video frames are compressed using the JPEG algorithm
993 allowing a higher compression ratio than standard RDP bitmap
994 compression methods. It is possible to increase the compression
995 ratio by lowering the video quality.
996 </para>
997
998 <para>
999 The VRDP server automatically detects video streams in a guest
1000 as frequently updated rectangular areas. As a result, this
1001 method works with any guest operating system without having to
1002 install additional software in the guest. In particular, the
1003 Guest Additions are not required.
1004 </para>
1005
1006 <para>
1007 On the client side, however, currently only the Windows 7 Remote
1008 Desktop Connection client supports this feature. If a client
1009 does not support video redirection, the VRDP server falls back
1010 to regular bitmap updates.
1011 </para>
1012
1013 <para>
1014 The following command enables video redirection:
1015 </para>
1016
1017<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrdevideochannel on</screen>
1018
1019 <para>
1020 The quality of the video is defined as a value from 10 to 100
1021 percent, representing a JPEG compression level, where lower
1022 numbers mean lower quality but higher compression. The quality
1023 can be changed using the following command:
1024 </para>
1025
1026<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrdevideochannelquality 75</screen>
1027
1028 </sect2>
1029
1030 <sect2 id="vrde-customization">
1031
1032 <title>VRDP Customization</title>
1033
1034 <para>
1035 You can disable display output, mouse and keyboard input, audio,
1036 remote USB, or clipboard individually in the VRDP server.
1037 </para>
1038
1039 <para>
1040 The following commands change the corresponding server settings:
1041 </para>
1042
1043<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrdeproperty Client/DisableDisplay=1
1044$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrdeproperty Client/DisableInput=1
1045$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrdeproperty Client/DisableUSB=1
1046$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrdeproperty Client/DisableAudio=1
1047$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrdeproperty Client/DisableClipboard=1
1048$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrdeproperty Client/DisableUpstreamAudio=1</screen>
1049
1050 <para>
1051 To reenable a feature, use a similar command without the
1052 trailing 1. For example:
1053 </para>
1054
1055<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrdeproperty Client/DisableDisplay=</screen>
1056
1057 </sect2>
1058
1059 </sect1>
1060
1061 <sect1 id="teleporting">
1062
1063 <title>Teleporting</title>
1064
1065 <para>
1066 &product-name; supports <emphasis>teleporting</emphasis>.
1067 Teleporting is moving a virtual machine over a network from one
1068 &product-name; host to another, while the virtual machine is
1069 running. This works regardless of the host operating system that
1070 is running on the hosts. You can teleport virtual machines between
1071 Oracle Solaris and Mac OS X hosts, for example.
1072 </para>
1073
1074 <para>
1075 Teleporting requires that a machine be currently running on one
1076 host, which is called the <emphasis>source</emphasis>. The host to
1077 which the virtual machine will be teleported is called the
1078 <emphasis>target</emphasis>. The machine on the target is then
1079 configured to wait for the source to contact the target. The
1080 machine's running state will then be transferred from the source
1081 to the target with minimal downtime.
1082 </para>
1083
1084 <para>
1085 Teleporting happens over any TCP/IP network. The source and the
1086 target only need to agree on a TCP/IP port which is specified in
1087 the teleporting settings.
1088 </para>
1089
1090 <para>
1091 At this time, there are a few prerequisites for this to work, as
1092 follows:
1093 </para>
1094
1095 <itemizedlist>
1096
1097 <listitem>
1098 <para>
1099 On the target host, you must configure a virtual machine in
1100 &product-name; with exactly the same hardware settings as the
1101 machine on the source that you want to teleport. This does not
1102 apply to settings which are merely descriptive, such as the VM
1103 name, but obviously for teleporting to work, the target
1104 machine must have the same amount of memory and other hardware
1105 settings. Otherwise teleporting will fail with an error
1106 message.
1107 </para>
1108 </listitem>
1109
1110 <listitem>
1111 <para>
1112 The two virtual machines on the source and the target must
1113 share the same storage, hard disks as well as floppy disks and
1114 CD/DVD images. This means that they either use the same iSCSI
1115 targets or that the storage resides somewhere on the network
1116 and both hosts have access to it using NFS or SMB/CIFS.
1117 </para>
1118
1119 <para>
1120 This also means that neither the source nor the target machine
1121 can have any snapshots.
1122 </para>
1123 </listitem>
1124
1125 </itemizedlist>
1126
1127 <para>
1128 To configure teleporting, perform the following steps:
1129 </para>
1130
1131 <orderedlist>
1132
1133 <listitem>
1134 <para>
1135 On the <emphasis>target</emphasis> host, configure the virtual
1136 machine to wait for a teleport request to arrive when it is
1137 started, instead of actually attempting to start the machine.
1138 This is done with the following <command>VBoxManage</command>
1139 command:
1140 </para>
1141
1142<screen>VBoxManage modifyvm <replaceable>targetvmname</replaceable> --teleporter on --teleporterport <replaceable>port</replaceable></screen>
1143
1144 <para>
1145 <replaceable>targetvmname</replaceable> is the name of the
1146 virtual machine on the target host and
1147 <replaceable>port</replaceable> is a TCP/IP port number to be
1148 used on both the source and the target hosts. For example, use
1149 6000. See <xref linkend="vboxmanage-modifyvm" />.
1150 </para>
1151 </listitem>
1152
1153 <listitem>
1154 <para>
1155 Start the VM on the target host. Instead of running, the VM
1156 shows a progress dialog, indicating that it is waiting for a
1157 teleport request to arrive.
1158 </para>
1159 </listitem>
1160
1161 <listitem>
1162 <para>
1163 Start the VM on the <emphasis>source</emphasis> host as usual.
1164 When it is running and you want it to be teleported, issue the
1165 following command on the source host:
1166 </para>
1167
1168<screen>VBoxManage controlvm <replaceable>sourcevmname</replaceable> teleport --host <replaceable>targethost</replaceable> --port <replaceable>port</replaceable></screen>
1169
1170 <para>
1171 where <replaceable>sourcevmname</replaceable> is the name of
1172 the virtual machine on the source host, which is the machine
1173 that is currently running.
1174 <replaceable>targethost</replaceable> is the host or IP name
1175 of the target host on which the machine is waiting for the
1176 teleport request, and <replaceable>port</replaceable> must be
1177 the same number as specified in the command on the target
1178 host. See <xref linkend="vboxmanage-controlvm" />.
1179 </para>
1180 </listitem>
1181
1182 </orderedlist>
1183
1184 <para>
1185 For testing, you can also teleport machines on the same host. In
1186 that case, use localhost as the hostname on both the source and
1187 the target host.
1188 </para>
1189
1190 <note>
1191 <para>
1192 In rare cases, if the CPUs of the source and the target are very
1193 different, teleporting can fail with an error message, or the
1194 target may hang. This may happen especially if the VM is running
1195 application software that is highly optimized to run on a
1196 particular CPU without correctly checking that certain CPU
1197 features are actually present. &product-name; filters what CPU
1198 capabilities are presented to the guest operating system.
1199 Advanced users can attempt to restrict these virtual CPU
1200 capabilities with the <command>VBoxManage modifyvm
1201 --cpuid</command> command. See
1202 <xref linkend="vboxmanage-modifyvm" />.
1203 </para>
1204 </note>
1205
1206 </sect1>
1207
1208 <xi:include href="user_man_VBoxHeadless.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1209
1210</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