VirtualBox

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

Last change on this file since 79829 was 76786, checked in by vboxsync, 6 years ago

manual: integrate drop #40 with minimal manual adjustments (but everything into one book, with manually applied tweaks to turn the release notes into a pure changelog again, and eliminated trailing whitespace)

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