VirtualBox

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

Last change on this file since 32430 was 32331, checked in by vboxsync, 14 years ago

doc/manual: cosmetical fixes

File size: 32.4 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
4<chapter>
5 <title>Remote virtual machines</title>
6
7 <sect1>
8 <title id="vrdp">Remote display (VRDP support)</title>
9
10 <para>VirtualBox, the graphical user interface, has a built-in server for
11 the VirtualBox Remote Desktop Protocol (VRDP). This allows you to see the
12 output of a virtual machine's window remotely on any other computer and
13 control the virtual machine from there, as if the virtual machine was
14 running locally.</para>
15
16 <para>VRDP is a backwards-compatible extension to Microsoft's Remote
17 Desktop Protocol (RDP). Typically graphics updates and audio are sent from
18 the remote machine to the client, while keyboard and mouse events are sent
19 back. As a result, you can use any standard RDP client to control the
20 remote VM.</para>
21
22 <para>With <computeroutput>VirtualBox</computeroutput>, the graphical user
23 interface, the VRDP server is disabled by default, but can easily be
24 enabled on a per-VM basis either in the "Display" settings (see <xref
25 linkend="settings-display" />) or with
26 <computeroutput>VBoxManage</computeroutput>:<screen>VBoxManage modifyvm "VM name" --vrdp on</screen></para>
27
28 <para>If you use <computeroutput>VBoxHeadless</computeroutput> (described
29 further below), VRDP support will be automatically enabled since
30 VBoxHeadless has no other means of output.</para>
31
32 <sect2 id="rdp-viewers">
33 <title>Common third-party RDP viewers</title>
34
35 <para>You can use any standard RDP viewer to connect to such a remote
36 virtual machine (examples follow below). For this to work, you must
37 specify the <emphasis role="bold">IP address</emphasis> of your
38 <emphasis>host</emphasis> system (not of the virtual machine!) as the
39 server address to connect to, as well as the <emphasis role="bold">port
40 number</emphasis> that the RDP server is using.</para>
41
42 <para>By default, the VRDP server uses the standard RDP TCP port
43 <computeroutput>3389</computeroutput>. You will need to change the
44 default port if you run more than one VRDP server, since the port can
45 only be used by one server at a time; you might also need to change it
46 on Windows hosts since the default port might already be used by the RDP
47 server that is built into Windows itself. Ports 5000 through 5050 are
48 typically not used and might be a good choice.</para>
49
50 <para>The port can be changed either in the "Display" settings of the
51 graphical user interface or with
52 <computeroutput>--vrdpport</computeroutput> option of the
53 <computeroutput>VBoxManage modifyvm</computeroutput> command. You can
54 specify a comma-separated list of ports or ranges of ports. Use a dash
55 between two port numbers to specify a range. The VRDP server will bind
56 to <emphasis role="bold">one</emphasis> of available ports from the
57 specified list. For example, <computeroutput>VBoxManage modifyvm "VM
58 name" --vrdpport 5000,5010-5012</computeroutput> will configure the
59 server to bind to one of the ports 5000, 5010, 5011 or 5012. See <xref
60 linkend="vboxmanage-modifyvm" /> for details.</para>
61
62 <para>The actual port used by a running VM can be either queried with
63 <computeroutput>VBoxManage showvminfo</computeroutput> command or seen
64 in the GUI on the <computeroutput>Runtime</computeroutput> tab of the
65 <computeroutput>Session Information Dialog</computeroutput>, which is
66 accessible via the <computeroutput>Machine</computeroutput> menu of the
67 VM window.</para>
68
69 <para>Here follow examples for the most common RDP viewers:<itemizedlist>
70 <listitem>
71 <para>On Windows, you can use the Microsoft Terminal Services
72 Connector (<computeroutput>mstsc.exe</computeroutput>) that ships
73 with Windows. You can start it by bringing up the "Run" dialog
74 (press the Windows key and "R") and typing "mstsc". You can also
75 find it under "Start" -&gt; "All Programs" -&gt; "Accessories"
76 -&gt; "Remote Desktop Connection". If you use the "Run" dialog,
77 you can type in options directly:<screen>mstsc 1.2.3.4[:3389]</screen></para>
78
79 <para>Replace "1.2.3.4" with the host IP address, and 3389 with a
80 different port if necessary.</para>
81
82 <note><para>When connecting to localhost in order to test the connection,
83 the addresses <computeroutput>localhost</computeroutput> and
84 <computeroutput>127.0.0.1</computeroutput> might not work using
85 <computeroutput>mstsc.exe</computeroutput>. Instead, the address
86 <computeroutput>127.0.0.2[:3389]</computeroutput> has to be used.</para></note>
87 </listitem>
88
89 <listitem>
90 <para>On other systems, you can use the standard open-source
91 <computeroutput>rdesktop</computeroutput> program. This ships with
92 most Linux distributions, but VirtualBox also comes with a
93 modified variant of rdesktop for remote USB support (see <xref
94 linkend="usb-over-rdp" /> below).</para>
95
96 <para>With rdesktop, use a command line such as the
97 following:<screen>rdesktop -a 16 -N 1.2.3.4:3389</screen></para>
98
99 <para>As said for the Microsoft viewer above, replace "1.2.3.4"
100 with the host IP address, and 3389 with a different port if
101 necessary. The <computeroutput>-a 16</computeroutput> option
102 requests a color depth of 16 bits per pixel, which we recommend.
103 (For best performance, after installation of the guest operating
104 system, you should set its display color depth to the same value).
105 The <computeroutput>-N</computeroutput> option enables use of the
106 NumPad keys.</para>
107 </listitem>
108
109 <listitem>
110 <para>If you run the KDE desktop, you might prefer
111 <computeroutput>krdc</computeroutput>, the KDE RDP viewer. The
112 command line would look like this:<screen>krdc --window --high-quality rdp:/1.2.3.4[:3389]</screen></para>
113
114 <para>Again, replace "1.2.3.4" with the host IP address, and 3389
115 with a different port if necessary. The "rdp:/" bit is required
116 with krdc to switch it into RDP mode.</para>
117 </listitem>
118 </itemizedlist></para>
119 </sect2>
120
121 <sect2 id="vboxheadless">
122 <title>VBoxHeadless, the VRDP-only server</title>
123
124 <para>While the VRDP server that is built into the
125 <computeroutput>VirtualBox</computeroutput> GUI is perfectly capable of
126 running virtual machines remotely, it is not convenient to have to run
127 <computeroutput>VirtualBox</computeroutput> if you never want to have
128 VMs displayed locally in the first place. In particular, if you are
129 running servers whose only purpose is to host VMs, and all your VMs are
130 supposed to run remotely over VRDP, then it is pointless to have a
131 graphical user interface on the server at all -- especially since, on a
132 Linux or Solaris host, <computeroutput>VirtualBox</computeroutput> comes
133 with dependencies on the Qt and SDL libraries, which is inconvenient if
134 you would rather not have the X Window system on your server at
135 all.</para>
136
137 <para>VirtualBox therefore comes with yet another front-end called
138 <computeroutput>VBoxHeadless</computeroutput>, which produces no visible
139 output on the host at all, but instead only delivers VRDP data.<footnote>
140 <para>Before VirtualBox 1.6, the headless server was called
141 <computeroutput>VBoxVRDP</computeroutput>. For the sake of backwards
142 compatibility, the VirtualBox installation still installs an
143 executable with that name as well.</para>
144 </footnote></para>
145
146 <para>To start a virtual machine with VBoxHeadless, you have two
147 options:</para>
148
149 <itemizedlist>
150 <listitem>
151 <para>You can use <screen>VBoxManage startvm "VM name" --type vrdp</screen>
152 The extra <computeroutput>--type</computeroutput> option causes the
153 VirtualBox core to use <computeroutput>VBoxHeadless</computeroutput>
154 as the front-end to the internal virtualization engine.</para>
155 </listitem>
156
157 <listitem>
158 <para>The alternative is to use
159 <computeroutput>VBoxHeadless</computeroutput> directly, as
160 follows:<screen>VBoxHeadless --startvm &lt;uuid|name&gt;</screen></para>
161
162 <para>This way of starting the VM has the advantage that you can see
163 more detailed error messages, especially for early failures before
164 the VM execution is started. If you have trouble with
165 <computeroutput>VBoxManage startvm</computeroutput>, it can help
166 greatly to start <computeroutput>VBoxHeadless</computeroutput>
167 directly to diagnose the problem cause.</para>
168 </listitem>
169 </itemizedlist>
170
171 <para>Note that when you use
172 <computeroutput>VBoxHeadless</computeroutput> to start a VM, since the
173 headless server has no other means of output, the built-in VRDP server
174 will <emphasis>always</emphasis> be enabled, regardless of whether you
175 have enabled the VRDP server in the VM's settings. If this is
176 undesirable (for example because you want to access the VM via
177 <computeroutput>ssh</computeroutput> only), start the VM like
178 this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrdp=off</screen>To
179 have the VRDP server use the setting from the VM configuration, as the
180 other front-ends would, use this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrdp=config</screen></para>
181 </sect2>
182
183 <sect2>
184 <title>Step by step: creating a virtual machine on a headless
185 server</title>
186
187 <para>The following instructions may give you an idea how to create a
188 virtual machine on a headless server over a network connection. We will
189 create a virtual machine, establish a VRDP connection and install a
190 guest operating system -- all without having to touch the headless
191 server. All you need is the following:</para>
192
193 <para><orderedlist>
194 <listitem>
195 <para>VirtualBox on a server machine with a supported host
196 operating system; for the following example, we will assume a
197 Linux server;</para>
198 </listitem>
199
200 <listitem>
201 <para>an ISO file on the server, containing the installation data
202 for the guest operating system to install (we will assume Windows
203 XP in the following example);</para>
204 </listitem>
205
206 <listitem>
207 <para>a terminal connection to that host over which you can access
208 a command line (e.g. via <computeroutput>telnet</computeroutput>
209 or <computeroutput>ssh</computeroutput>);</para>
210 </listitem>
211
212 <listitem>
213 <para>an RDP viewer on the remote client; see <xref
214 linkend="rdp-viewers" /> above for examples.</para>
215 </listitem>
216 </orderedlist>Note again that on the server machine, since we will
217 only use the headless server, neither Qt nor SDL nor the X Window system
218 will be needed.</para>
219
220 <para><orderedlist>
221 <listitem>
222 <para>On the headless server, create a new virtual machine:</para>
223
224 <screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen>
225
226 <para>Note that if you do not specify
227 <computeroutput>--register</computeroutput>, you will have to
228 manually use the registervm command later.</para>
229
230 <para>Note further that you do not need to specify
231 <computeroutput>--ostype</computeroutput> but doing so selects
232 some sane default values for certain VM parameters, for example
233 the RAM size and the type of the virtual network device. To get a
234 complete list of supported operating systems you can use</para>
235
236 <screen>VBoxManage list ostypes</screen>
237 </listitem>
238
239 <listitem>
240 <para>Make sure the settings for this VM are appropriate for the
241 guest operating system that we will install. For example:<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen></para>
242 </listitem>
243
244 <listitem>
245 <para>Create a virtual hard disk for the VM (in this case, 10GB in
246 size) and register it with VirtualBox:<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000 --remember</screen></para>
247 </listitem>
248
249 <listitem>
250 <para>Add an IDE Controller to the new VM:<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller"
251 --add ide --controller PIIX4</screen></para>
252 </listitem>
253
254 <listitem>
255 <para>Set this newly created VDI file as the first virtual hard
256 disk of the new VM:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
257 --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen></para>
258 </listitem>
259
260 <listitem>
261 <para>Register the ISO file that contains the operating system
262 installation that you want to install later:<screen>VBoxManage openmedium dvd /full/path/to/iso.iso</screen></para>
263 </listitem>
264
265 <listitem>
266 <para>Attach this ISO to the virtual machine, so it can boot from
267 it:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
268 --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen></para>
269 </listitem>
270
271 <listitem>
272 <para>Start the virtual machine using VBoxHeadless:<screen>VBoxHeadless --startvm "Windows XP"</screen></para>
273
274 <para>If everything worked, you should see a copyright notice. If,
275 instead, you are returned to the command line, then something went
276 wrong.</para>
277 </listitem>
278
279 <listitem>
280 <para>On the client machine, fire up the RDP viewer and try to
281 connect to the server (see <xref linkend="rdp-viewers" /> above
282 for how to use various common RDP viewers).</para>
283
284 <para>You should now be seeing the installation routine of your
285 guest operating system in the RDP viewer.</para>
286 </listitem>
287 </orderedlist></para>
288 </sect2>
289
290 <sect2 id="usb-over-rdp">
291 <title>Remote USB</title>
292
293 <para>As a special feature on top of the VRDP support, VirtualBox
294 supports remote USB devices over the wire as well. That is, the
295 VirtualBox guest that runs on one computer can access the USB devices of
296 the remote computer on which the RDP data is being displayed the same
297 way as USB devices that are connected to the actual host. This allows
298 for running virtual machines on a VirtualBox host that acts as a server,
299 where a client can connect from elsewhere that needs only a network
300 adapter and a display capable of running an RDP viewer. When USB devices
301 are plugged into the client, the remote VirtualBox server can access
302 them.</para>
303
304 <para>For these remote USB devices, the same filter rules apply as for
305 other USB devices, as described with <xref linkend="settings-usb" />.
306 All you have to do is specify "Remote" (or "Any") when setting up these
307 rules.</para>
308
309 <para>Accessing remote USB devices is only possible if the RDP client
310 supports this extension. On Linux and Solaris hosts, the VirtualBox
311 installation provides a suitable RDP client called
312 <computeroutput>rdesktop-vrdp</computeroutput>. RDP clients for other
313 platforms will be provided in future VirtualBox versions.</para>
314
315 <para>To make a remote USB device available to a VM, rdesktop-vrdp
316 should be started as follows:<screen>rdesktop-vrdp -r usb -a 16 -N my.host.address</screen>Note
317 that <computeroutput>rdesktop-vrdp</computeroutput> can access USB
318 devices only through <computeroutput>/proc/bus/usb</computeroutput>.
319 Please refer to <xref linkend="usb_linux" /> for further details on how
320 to properly set up the permissions. Furthermore it is advisable to
321 disable automatic loading of any host driver on the remote host which
322 might work on USB devices to ensure that the devices are accessible by
323 the RDP client. If the setup was properly done on the remote host,
324 plug/unplug events are visible on the VBox.log file of the VM.</para>
325 </sect2>
326
327 <sect2 id="vrdp-auth">
328 <title>RDP authentication</title>
329
330 <para>For each virtual machine that is remotely accessible via RDP, you
331 can individually determine if and how RDP connections are
332 authenticated.</para>
333
334 <para>For this, use <computeroutput>VBoxManage modifyvm</computeroutput>
335 command with the <computeroutput>--vrdpauthtype</computeroutput> option;
336 see <xref linkend="vboxmanage-modifyvm" /> for a general introduction.
337 Three methods of authentication are available:<itemizedlist>
338 <listitem>
339 <para>The "null" method means that there is no authentication at
340 all; any client can connect to the VRDP server and thus the
341 virtual machine. This is, of course, very insecure and only to be
342 recommended for private networks.</para>
343 </listitem>
344
345 <listitem>
346 <para>The "external" method provides external authentication
347 through a special authentication library.</para>
348
349 <para>VirtualBox comes with three default libraries for external
350 authentication:<itemizedlist>
351 <listitem>
352 <para>On Linux hosts,
353 <computeroutput>VRDPAuth.so</computeroutput> authenticates
354 users against the host's PAM system.</para>
355 </listitem>
356
357 <listitem>
358 <para>On Windows hosts,
359 <computeroutput>VRDPAuth.dll</computeroutput> authenticates
360 users against the host's WinLogon system.</para>
361 </listitem>
362
363 <listitem>
364 <para>On Mac OS X hosts,
365 <computeroutput>VRDPAuth.dylib</computeroutput>
366 authenticates users against the host's directory
367 service.<footnote>
368 <para>Support for Mac OS X was added in version
369 3.2.</para>
370 </footnote></para>
371 </listitem>
372 </itemizedlist></para>
373
374 <para>In other words, the "external" method per default performs
375 authentication with the user accounts that exist on the host
376 system. Any user with valid authentication credentials is
377 accepted, i.e. the username does not have to correspond to the
378 user running the VM.</para>
379 </listitem>
380
381 <listitem>
382 <para>An additional library called
383 <computeroutput>VRDPAuthSimple</computeroutput> performs authentication
384 against credentials configured in the VM's extra data section. This is
385 probably the simplest way to get authentication that does not depend
386 on a running and supported guest (see below). In order to enable
387 VRDPAuthSimple, issue
388 <computeroutput>VBoxManage setproperty vrdpauthlibrary "VRDPAuthSimple"</computeroutput>.
389 To enable the library for a VM, switch authentication to external using
390 <computeroutput>VBoxManage modifyvm "VM name" --vrdpauthtype external</computeroutput>.
391 Last but not least, you have to configure users and passwords. Here is an example
392 for the user "john" with the password "secret":
393 <computeroutput>VBoxManage setextradata "VM name" "VRDPAuthSimple/users/john" "secret"</computeroutput>
394 To specify an empty password, use the special reserved value
395 <computeroutput>[NULL]</computeroutput>.
396 </para>
397 </listitem>
398
399 <listitem>
400 <para>Finally, the "guest" authentication method performs
401 authentication with a special component that comes with the Guest
402 Additions; as a result, authentication is not performed with the
403 host users, but with the guest user accounts. This method is
404 currently still in testing and not yet supported.</para>
405 </listitem>
406 </itemizedlist></para>
407
408 <para>In addition to the methods described above, you can replace the
409 default "external authentication module with any other module. For this,
410 VirtualBox provides a well-defined interface that allows you to write your
411 own authentication module; see <xref
412 linkend="vrdp-authenticate-sdk" /> for details.</para>
413 </sect2>
414
415 <sect2 id="vrdp-crypt">
416 <title>RDP encryption</title>
417
418 <para>RDP features data stream encryption, which is based on the RC4
419 symmetric cipher (with keys up to 128bit). The RC4 keys are being
420 replaced in regular intervals (every 4096 packets).</para>
421
422 <para>RDP provides three different authentication methods:<orderedlist>
423 <listitem>
424 <para>Historically, RDP4 authentication was used, with which the
425 RDP client does not perform any checks in order to verify the
426 identity of the server it connects to. Since user credentials can
427 be obtained using a man in the middle (MITM) attack, RDP4
428 authentication is insecure and should generally not be
429 used.</para>
430 </listitem>
431
432 <listitem>
433 <para>RDP5.1 authentication employs a server certificate for which
434 the client possesses the public key. This way it is guaranteed
435 that the server possess the corresponding private key. However, as
436 this hard-coded private key became public some years ago, RDP5.1
437 authentication is also insecure and cannot be recommended.</para>
438 </listitem>
439
440 <listitem>
441 <para>RDP5.2 authentication is based on TLS 1.0 with
442 customer-supplied certificates. The server supplies a certificate
443 to the client which must be signed by a certificate authority (CA)
444 that the client trusts (for the Microsoft RDP Client 5.2, the CA
445 has to be added to the Windows Trusted Root Certificate
446 Authorities database). VirtualBox allows you to supply your own CA
447 and server certificate and uses OpenSSL for encryption.</para>
448 </listitem>
449 </orderedlist></para>
450
451 <para>While VirtualBox supports all of the above, only RDP5.2
452 authentication should be used in environments where security is a
453 concern. As the client that connects to the server determines what type
454 of encryption will be used, with rdesktop, the Linux RDP viewer, use the
455 <computeroutput>-4</computeroutput> or
456 <computeroutput>-5</computeroutput> options.</para>
457 </sect2>
458
459 <sect2 id="vrdp-multiconnection">
460 <title>Multiple VRDP connections</title>
461
462 <para>The built-in RDP server of VirtualBox supports simultaneous
463 connections to the same running VM from different clients. All connected
464 clients see the same screen output and share a mouse pointer and
465 keyboard focus. This is similar to several people using the same
466 computer at the same time, taking turns at the keyboard.</para>
467
468 <para>The following command enables multiple connection mode: <screen>VBoxManage modifyvm "VM name" --vrdpmulticon on</screen></para>
469 </sect2>
470
471 <sect2 id="vrdp-multimonitor">
472 <title>Multiple remote monitors</title>
473
474 <para>
475 To access two or more remote VM displays you have to enable the
476 VRDP multiconnection mode (see <xref linkend="vrdp-multiconnection" />).</para>
477
478 <para>The RDP client can select the virtual monitor number to connect to
479 using the <computeroutput>domain</computeroutput> logon parameter
480 (<computeroutput>-d</computeroutput>). If
481 the parameter ends with <computeroutput>@</computeroutput> followed by a
482 number, the VirtualBox RDP server interprets this number as the screen index.
483 The primary guest screen is selected with
484 <computeroutput>@1</computeroutput>, the first secondary screen is
485 <computeroutput>@2</computeroutput>, etc.</para>
486
487 <para>The MS RDP6 client does not let you specify a separate domain
488 name. Instead, use <computeroutput>domain\username</computeroutput> in
489 the <computeroutput>Username:</computeroutput> field -- for example,
490 <computeroutput>@2\name</computeroutput>.
491 <computeroutput>name</computeroutput> must be supplied, and must be the
492 name used to log in if the VRDP server is set up to require credentials.
493 If it is not, you may use any text as the username.</para>
494 </sect2>
495
496 <sect2 id="vrdp-videochannel">
497 <title>VRDP video redirection</title>
498
499 <para>Starting with VirtualBox 3.2, the VRDP server can redirect video
500 streams from the guest to the RDP client. Video frames are compressed
501 using the JPEG algorithm allowing a higher compression ratio than
502 standard RDP bitmap compression methods. It is possible to increase the
503 compression ratio by lowering the video quality.</para>
504
505 <para>Video streams in a guest are detected by the VRDP server
506 automatically as frequently updated rectangular areas. Therefore, this
507 method works with any guest operating system without having to install
508 additional software in the guest.</para>
509
510 <para>On the client side, however, currently only the Windows 7 Remote
511 Desktop Connection client supports this feature. If a client does not
512 support video redirection, the VRDP server uses regular bitmap
513 updates.</para>
514
515 <para>The following command enables video redirection: <screen>VBoxManage modifyvm "VM name" --vrdpvideochannel on</screen></para>
516
517 <para>The quality of the video is defined as a value from 10 to 100
518 percent, as is common with JPEG compression. The quality can be changed
519 using the following command: <screen>VBoxManage modifyvm "VM name" --vrdpvideochannelquality 75</screen></para>
520 </sect2>
521
522 <sect2 id="vrdp-customization">
523 <title>VRDP customization</title>
524
525 <para>Starting with VirtualBox 3.2.10, it is possible to disable display output,
526 mouse and keyboard input, audio, remote USB or clipboard in the VRDP server.</para>
527
528 <para>The following commands change corresponding server settings:</para>
529
530 <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay" 1
531VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableInput" 1
532VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableUSB" 1
533VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableAudio" 1
534VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableClipboard" 1</screen>
535
536 <para>To reenable a feature use a similar command without the trailing 1. For example:
537 <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay"</screen></para>
538 </sect2>
539 </sect1>
540
541 <sect1 id="teleporting">
542 <title>Teleporting</title>
543
544 <para>Starting with version 3.1, VirtualBox supports "teleporting" -- that
545 is, moving a virtual machine over a network from one VirtualBox host to
546 another, while the virtual machine is running. This works regardless of
547 the host operating system that is running on the hosts: you can teleport
548 virtual machines between Solaris and Mac hosts, for example.</para>
549
550 <para>Teleporting requires that a machine be currently running on one
551 host, which is then called the <emphasis role="bold">"source"</emphasis>.
552 The host to which the virtual machine will be teleported will then be
553 called the <emphasis role="bold">"target"</emphasis>; the machine on the
554 target is then configured to wait for the source to contact the target.
555 The machine's running state will then be transferred from the source to
556 the target with minimal downtime.</para>
557
558 <para>Teleporting happens over any TCP/IP network; the source and the
559 target only need to agree on a TCP/IP port which is specified in the
560 teleporting settings.</para>
561
562 <para>At this time, there are a few prerequisites for this to work,
563 however:<orderedlist>
564 <listitem>
565 <para>On the target host, you must configure a virtual machine in
566 VirtualBox with exactly the same hardware settings as the machine on
567 the source that you want to teleport. This does not apply to
568 settings which are merely descriptive, such as the VM name, but
569 obviously for teleporting to work, the target machine must have the
570 same amount of memory and other hardware settings. Otherwise
571 teleporting will fail with an error message.</para>
572 </listitem>
573
574 <listitem>
575 <para>The two virtual machines on the source and the target must
576 share the same storage (hard disks as well as floppy and CD/DVD
577 images). This means that they either use the same iSCSI targets or
578 that the storage resides somewhere on the network and both hosts
579 have access to it via NFS or SMB/CIFS.</para>
580
581 <para>This also means that neither the source nor the target machine
582 can have any snapshots.</para>
583 </listitem>
584 </orderedlist></para>
585
586 <para>Then perform the following steps:<orderedlist>
587 <listitem>
588 <para>On the <emphasis>target</emphasis> host, configure the virtual
589 machine to wait for a teleport request to arrive when it is started,
590 instead of actually attempting to start the machine. This is done
591 with the following VBoxManage command:<screen>VBoxManage modifyvm &lt;targetvmname&gt; --teleporter on --teleporterport &lt;port&gt;</screen></para>
592
593 <para>where <computeroutput>&lt;targetvmname&gt;</computeroutput> is
594 the name of the virtual machine on the target host and
595 <computeroutput>&lt;port&gt;</computeroutput> is a TCP/IP port
596 number to be used on both the source and the target hosts. For
597 example, use 6000. For details, see <xref
598 linkend="vboxmanage-modifyvm-teleport" />.</para>
599 </listitem>
600
601 <listitem>
602 <para>Start the VM on the target host. You will see that instead of
603 actually running, it will show a progress dialog. indicating that it
604 is waiting for a teleport request to arrive.</para>
605 </listitem>
606
607 <listitem>
608 <para>Start the machine on the <emphasis>source</emphasis> host as
609 usual. When it is running and you want it to be teleported, issue
610 the following command on the source host:<screen>VBoxManage controlvm &lt;sourcevmname&gt; teleport --host &lt;targethost&gt; --port &lt;port&gt;</screen></para>
611
612 <para>where <computeroutput>&lt;sourcevmname&gt;</computeroutput> is
613 the name of the virtual machine on the source host (the machine that
614 is currently running),
615 <computeroutput>&lt;targethost&gt;</computeroutput> is the host or
616 IP name of the target host on which the machine is waiting for the
617 teleport request, and <computeroutput>&lt;port&gt;</computeroutput>
618 must be the same number as specified in the command on the target
619 host. For details, see <xref
620 linkend="vboxmanage-controlvm" />.</para>
621 </listitem>
622 </orderedlist></para>
623
624 <para>For testing, you can also teleport machines on the same host; in
625 that case, use "localhost" as the hostname on both the source and the
626 target host.<note>
627 <para>In rare cases, if the CPUs of the source and the target are very
628 different, teleporting can fail with an error message, or the target
629 may hang. This may happen especially if the VM is running application
630 software that is highly optimized to run on a particular CPU without
631 correctly checking that certain CPU features are actually present.
632 VirtualBox filters what CPU capabilities are presented to the guest
633 operating system. Advanced users can attempt to restrict these virtual
634 CPU capabilities with the <computeroutput>VBoxManage --modifyvm
635 --cpuid</computeroutput> command; see <xref
636 linkend="vboxmanage-modifyvm-teleport" />.</para>
637 </note></para>
638 </sect1>
639</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