VirtualBox

source: vbox/trunk/doc/manual/en_US/user_AdvancedTopics.xml@ 80892

Last change on this file since 80892 was 80569, checked in by vboxsync, 5 years ago

Main: bugref:9341: Added VM autostart during boot support for windows host

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 232.0 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="AdvancedTopics">
8
9 <title>Advanced Topics</title>
10
11 <sect1 id="autologon">
12
13 <title>Automated Guest Logins</title>
14
15 <para>
16 &product-name; provides Guest Addition modules for Windows, Linux,
17 and Oracle Solaris to enable automated logins on the guest.
18 </para>
19
20 <para>
21 When a guest operating system is running in a virtual machine, it
22 might be desirable to perform coordinated and automated logins
23 using credentials from a master login system. Credentials are user
24 name, password, and domain name, where each value might be empty.
25 </para>
26
27 <sect2 id="autologon_win">
28
29 <title>Automated Windows Guest Logins</title>
30
31 <para>
32 Since Windows NT, Windows has provided a modular system login
33 subsystem, called Winlogon, which can be customized and extended
34 by means of so-called GINA (Graphical Identification and
35 Authentication) modules. With Windows Vista and Windows 7, the
36 GINA modules were replaced with a new mechanism called
37 credential providers. The &product-name; Guest Additions for
38 Windows come with both, a GINA and a credential provider module,
39 and therefore enable any Windows guest to perform automated
40 logins.
41 </para>
42
43 <para>
44 To activate the &product-name; GINA or credential provider
45 module, install the Guest Additions using the command line
46 switch <computeroutput>/with_autologon</computeroutput>. All the
47 following manual steps required for installing these modules
48 will be then done by the installer.
49 </para>
50
51 <para>
52 To manually install the &product-name; GINA module, extract the
53 Guest Additions as shown in
54 <xref linkend="windows-guest-file-extraction" /> and copy the
55 file <computeroutput>VBoxGINA.dll</computeroutput> to the
56 Windows <computeroutput>SYSTEM32</computeroutput> directory.
57 Then, in the registry, create the following key with a value of
58 <computeroutput>VBoxGINA.dll</computeroutput>:
59 </para>
60
61<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen>
62
63 <note>
64 <para>
65 The &product-name; GINA module is implemented as a wrapper
66 around the standard Windows GINA module,
67 <computeroutput>MSGINA.DLL</computeroutput>. As a result, it
68 may not work correctly with third party GINA modules.
69 </para>
70 </note>
71
72 <para>
73 To manually install the &product-name; credential provider
74 module, extract the Guest Additions as shown in
75 <xref
76 linkend="windows-guest-file-extraction" /> and copy
77 the file <computeroutput>VBoxCredProv.dll</computeroutput> to
78 the Windows <computeroutput>SYSTEM32</computeroutput> directory.
79 In the registry, create the following keys:
80 </para>
81
82<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
83Authentication\Credential Providers\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
84
85HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
86
87HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32</screen>
88
89 <para>
90 All default values, the key named
91 <computeroutput>Default</computeroutput>, must be set to
92 <computeroutput>VBoxCredProv</computeroutput>.
93 </para>
94
95 <para>
96 Create a new string named as follows, with a value of
97 <computeroutput>Apartment</computeroutput>.
98 </para>
99
100<screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen>
101
102 <para>
103 To set credentials, use the following command on a
104 <emphasis>running</emphasis> VM:
105 </para>
106
107<screen>VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</screen>
108
109 <para>
110 While the VM is running, the credentials can be queried by the
111 &product-name; login modules, GINA or credential provider, using
112 the &product-name; Guest Additions device driver. When Windows
113 is in <emphasis>logged out</emphasis> mode, the login modules
114 will constantly poll for credentials and if they are present, a
115 login will be attempted. After retrieving the credentials, the
116 login modules will erase them so that the above command will
117 have to be repeated for subsequent logins.
118 </para>
119
120 <para>
121 For security reasons, credentials are not stored in any
122 persistent manner and will be lost when the VM is reset. Also,
123 the credentials are write-only. There is no way to retrieve the
124 credentials from the host side. Credentials can be reset from
125 the host side by setting empty values.
126 </para>
127
128 <para>
129 Depending on the particular variant of the Windows guest, the
130 following restrictions apply:
131 </para>
132
133 <itemizedlist>
134
135 <listitem>
136 <para>
137 For <emphasis role="bold">Windows XP guests.</emphasis> The
138 login subsystem needs to be configured to use the classic
139 login dialog, as the &product-name; GINA module does not
140 support the XP-style welcome dialog.
141 </para>
142 </listitem>
143
144 <listitem>
145 <para>
146 <emphasis role="bold">Windows Vista, Windows 7, Windows 8,
147 and Windows 10 guests.</emphasis> The login subsystem does
148 not support the so-called Secure Attention Sequence,
149 <computeroutput>Ctrl+Alt+Del</computeroutput>. As a result,
150 the guest's group policy settings need to be changed to not
151 use the Secure Attention Sequence. Also, the user name given
152 is only compared to the true user name, not the user
153 friendly name. This means that when you rename a user, you
154 still have to supply the original user name as Windows never
155 renames user accounts internally.
156 </para>
157 </listitem>
158
159 <listitem>
160 <para>
161 Automatic login handling of the built-in
162 <emphasis role="bold">Windows Remote Desktop
163 Service</emphasis>, formerly known as Terminal Services, is
164 disabled by default. To enable it, create the following
165 registry key with a <computeroutput>DWORD</computeroutput>
166 value of <computeroutput>1</computeroutput>.
167 </para>
168
169<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen>
170 </listitem>
171
172 </itemizedlist>
173
174 <para>
175 The following command forces &product-name; to keep the
176 credentials after they were read by the guest and on VM reset:
177 </para>
178
179<screen>VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</screen>
180
181 <para>
182 Note that this is a potential security risk, as a malicious
183 application running on the guest could request this information
184 using the proper interface.
185 </para>
186
187 </sect2>
188
189 <sect2 id="autologon_unix">
190
191 <title>Automated Linux and UNIX Guest Logins</title>
192
193 <para>
194 &product-name; provides a custom PAM module (Pluggable
195 Authentication Module) which can be used to perform automated
196 guest logins on platforms which support this framework.
197 Virtually all modern Linux and UNIX distributions rely on PAM.
198 </para>
199
200 <para>
201 For automated logins on Ubuntu, or Ubuntu-derived, distributions
202 using LightDM as the display manager. See
203 <xref linkend="autologon_unix_lightdm" />.
204 </para>
205
206 <para>
207 The <computeroutput>pam_vbox.so</computeroutput> module itself
208 <emphasis>does not</emphasis> do an actual verification of the
209 credentials passed to the guest OS. Instead it relies on other
210 modules such as <computeroutput>pam_unix.so</computeroutput> or
211 <computeroutput>pam_unix2.so</computeroutput> down in the PAM
212 stack to do the actual validation using the credentials
213 retrieved by <computeroutput>pam_vbox.so</computeroutput>.
214 Therefore <computeroutput>pam_vbox.so</computeroutput> has to be
215 on top of the authentication PAM service list.
216 </para>
217
218 <note>
219 <para>
220 The <computeroutput>pam_vbox.so</computeroutput> module only
221 supports the <computeroutput>auth</computeroutput> primitive.
222 Other primitives such as
223 <computeroutput>account</computeroutput>,
224 <computeroutput>session</computeroutput>, or
225 <computeroutput>password</computeroutput> are not supported.
226 </para>
227 </note>
228
229 <para>
230 The <computeroutput>pam_vbox.so</computeroutput> module is
231 shipped as part of the Guest Additions but it is not installed
232 and/or activated on the guest OS by default. In order to install
233 it, it has to be copied from
234 <computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/other/</computeroutput>
235 to the security modules directory. This is usually
236 <computeroutput>/lib/security/</computeroutput> on 32-bit Linux
237 guests or <computeroutput>/lib64/security/</computeroutput> on
238 64-bit Linux guests. Please refer to your guest OS documentation
239 for the correct PAM module directory.
240 </para>
241
242 <para>
243 For example, to use <computeroutput>pam_vbox.so</computeroutput>
244 with a Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM)
245 to log in users automatically with the credentials passed by the
246 host, configure the guest OS as follows:
247 </para>
248
249 <orderedlist>
250
251 <listitem>
252 <para>
253 Copy the <computeroutput>pam_vbox.so</computeroutput> module
254 to the security modules directory. In this case,
255 <computeroutput>/lib/security</computeroutput>.
256 </para>
257 </listitem>
258
259 <listitem>
260 <para>
261 Edit the PAM configuration file for GDM, found at
262 <computeroutput>/etc/pam.d/gdm</computeroutput>. Add the
263 line <computeroutput>auth requisite
264 pam_vbox.so</computeroutput> at the top. Additionally, in
265 most Linux distributions there is a file called
266 <computeroutput>/etc/pam.d/common-auth</computeroutput>.
267 This file is included in many other services, like the GDM
268 file mentioned above. There you also have to add the line
269 <computeroutput>auth requisite pam_vbox.so</computeroutput>.
270 </para>
271 </listitem>
272
273 <listitem>
274 <para>
275 If authentication against the shadow database using
276 <computeroutput>pam_unix.so</computeroutput> or
277 <computeroutput>pam_unix2.so</computeroutput> is desired,
278 the argument <computeroutput>try_first_pass</computeroutput>
279 for <computeroutput>pam_unix.so</computeroutput> or
280 <computeroutput>use_first_pass</computeroutput> for
281 <computeroutput>pam_unix2.so</computeroutput> is needed in
282 order to pass the credentials from the &product-name; module
283 to the shadow database authentication module. For Ubuntu,
284 this needs to be added to
285 <computeroutput>/etc/pam.d/common-auth</computeroutput>, to
286 the end of the line referencing
287 <computeroutput>pam_unix.so</computeroutput>. This argument
288 tells the PAM module to use credentials already present in
289 the stack, such as the ones provided by the &product-name;
290 PAM module.
291 </para>
292 </listitem>
293
294 </orderedlist>
295
296 <warning>
297 <para>
298 An incorrectly configured PAM stack can effectively prevent
299 you from logging into your guest system.
300 </para>
301 </warning>
302
303 <para>
304 To make deployment easier, you can pass the argument
305 <computeroutput>debug</computeroutput> right after the
306 <computeroutput>pam_vbox.so</computeroutput> statement. Debug
307 log output will then be recorded using syslog.
308 </para>
309
310 <note>
311 <para>
312 By default, <computeroutput>pam_vbox</computeroutput> will not
313 wait for credentials to arrive from the host. When a login
314 prompt is shown, for example by GDM/KDM or the text console,
315 and pam_vbox does not yet have credentials it does not wait
316 until they arrive. Instead the next module in the PAM stack,
317 depending on the PAM configuration, will have the chance for
318 authentication.
319 </para>
320 </note>
321
322 <para>
323 <computeroutput>pam_vbox</computeroutput> supports various guest
324 property parameters that are located in
325 <computeroutput>/VirtualBox/GuestAdd/PAM/</computeroutput>.
326 These parameters allow pam_vbox to wait for credentials to be
327 provided by the host and optionally can show a message while
328 waiting for those. The following guest properties can be set:
329 </para>
330
331 <itemizedlist>
332
333 <listitem>
334 <para>
335 <computeroutput>CredsWait</computeroutput>: Set to 1 if
336 pam_vbox should start waiting until credentials arrive from
337 the host. Until then no other authentication methods such as
338 manually logging in will be available. If this property is
339 empty or gets deleted no waiting for credentials will be
340 performed and pam_vbox will act like before. This property
341 must be set read-only for the guest
342 (<computeroutput>RDONLYGUEST</computeroutput>).
343 </para>
344 </listitem>
345
346 <listitem>
347 <para>
348 <computeroutput>CredsWaitAbort</computeroutput>: Aborts
349 waiting for credentials when set to any value. Can be set
350 from host and the guest.
351 </para>
352 </listitem>
353
354 <listitem>
355 <para>
356 <computeroutput>CredsWaitTimeout</computeroutput>: Timeout,
357 in seconds, to let pam_vbox wait for credentials to arrive.
358 When no credentials arrive within this timeout,
359 authentication of pam_vbox will be set to failed and the
360 next PAM module in chain will be asked. If this property is
361 not specified, set to 0 or an invalid value, an infinite
362 timeout will be used. This property must be set read-only
363 for the guest
364 (<computeroutput>RDONLYGUEST</computeroutput>).
365 </para>
366 </listitem>
367
368 </itemizedlist>
369
370 <para>
371 To customize pam_vbox further there are the following guest
372 properties:
373 </para>
374
375 <itemizedlist>
376
377 <listitem>
378 <para>
379 <computeroutput>CredsMsgWaiting</computeroutput>: Custom
380 message showed while pam_vbox is waiting for credentials
381 from the host. This property must be set read-only for the
382 guest (<computeroutput>RDONLYGUEST</computeroutput>).
383 </para>
384 </listitem>
385
386 <listitem>
387 <para>
388 <computeroutput>CredsMsgWaitTimeout</computeroutput>: Custom
389 message showed when waiting for credentials by pam_vbox has
390 timed out. For example, they did not arrive within time.
391 This property must be set read-only for the guest
392 (<computeroutput>RDONLYGUEST</computeroutput>).
393 </para>
394 </listitem>
395
396 </itemizedlist>
397
398 <note>
399 <para>
400 If a pam_vbox guest property does not have the correct flag
401 set (<computeroutput>RDONLYGUEST</computeroutput>) the
402 property is ignored and, depending on the property, a default
403 value will be used. This can result in pam_vbox not waiting
404 for credentials. Consult the appropriate syslog file for more
405 information and use the <computeroutput>debug</computeroutput>
406 option.
407 </para>
408 </note>
409
410 <sect3 id="autologon_unix_lightdm">
411
412 <title>&product-name; Greeter for Ubuntu/LightDM</title>
413
414 <para>
415 &product-name; comes with an own greeter module, named
416 vbox-greeter. The module can be used with LightDM 1.0.1 or
417 later. LightDM is the default display manager since Ubuntu
418 10.11 and therefore also can be used for automated guest
419 logins.
420 </para>
421
422 <para>
423 vbox-greeter does not need the
424 <computeroutput>pam_vbox</computeroutput> module described
425 above in order to function. It comes with its own
426 authentication mechanism provided by LightDM. However, to
427 provide maximum of flexibility both modules can be used
428 together on the same guest.
429 </para>
430
431 <para>
432 As with the <computeroutput>pam_vbox</computeroutput> module,
433 vbox-greeter is shipped as part of the Guest Additions but it
434 is not installed or activated on the guest OS by default. To
435 install vbox-greeter automatically upon Guest Additions
436 installation, use the
437 <computeroutput>--with-autologon</computeroutput> switch when
438 starting the VBoxLinuxAdditions.run file:
439 </para>
440
441<screen># ./VBoxLinuxAdditions.run -- --with-autologon</screen>
442
443 <para>
444 For manual or postponed installation, the
445 <computeroutput>vbox-greeter.desktop</computeroutput> file has
446 to be copied from
447 <computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/other/</computeroutput>
448 to the <computeroutput>xgreeters</computeroutput> directory
449 This is usually
450 <computeroutput>/usr/share/xgreeters/</computeroutput>. Please
451 refer to your guest OS documentation for the correct LightDM
452 greeter directory.
453 </para>
454
455 <para>
456 The vbox-greeter module itself already was installed by the
457 &product-name; Guest Additions installer and resides in
458 <computeroutput>/usr/sbin/</computeroutput>. To enable
459 vbox-greeter as the standard greeter module, the file
460 <computeroutput>/etc/lightdm/lightdm.conf</computeroutput>
461 needs to be edited:
462 </para>
463
464<screen>[SeatDefaults]
465greeter-session=vbox-greeter</screen>
466
467 <note>
468 <itemizedlist>
469
470 <listitem>
471 <para>
472 The LightDM server needs to be fully restarted in order
473 for vbox-greeter to be used as the default greeter. As
474 root, run <computeroutput>service lightdm
475 --full-restart</computeroutput> on Ubuntu, or simply
476 restart the guest.
477 </para>
478 </listitem>
479
480 <listitem>
481 <para>
482 vbox-greeter is independent of the graphical session
483 chosen by the user, such as Gnome, KDE, or Unity.
484 However, it requires FLTK 1.3 for representing its own
485 user interface.
486 </para>
487 </listitem>
488
489 </itemizedlist>
490 </note>
491
492 <para>
493 There are numerous guest properties which can be used to
494 further customize the login experience. For automatically
495 logging in users, the same guest properties apply as for
496 pam_vbox. See <xref linkend="autologon_unix" />.
497 </para>
498
499 <para>
500 In addition to the above mentioned guest properties,
501 vbox-greeter allows further customization of its user
502 interface. These special guest properties all reside in
503 <computeroutput>/VirtualBox/GuestAdd/Greeter/</computeroutput>:
504 </para>
505
506 <itemizedlist>
507
508 <listitem>
509 <para>
510 <computeroutput>HideRestart</computeroutput>: Set to 1 if
511 vbox-greeter should hide the button to restart the guest.
512 This property must be set read-only for the guest
513 (<computeroutput>RDONLYGUEST</computeroutput>).
514 </para>
515 </listitem>
516
517 <listitem>
518 <para>
519 <computeroutput>HideShutdown</computeroutput>: Set to 1 if
520 vbox-greeter should hide the button to shutdown the guest.
521 This property must be set read-only for the guest
522 (<computeroutput>RDONLYGUEST</computeroutput>).
523 </para>
524 </listitem>
525
526 <listitem>
527 <para>
528 <computeroutput>BannerPath</computeroutput>: Path to a
529 .PNG file for using it as a banner on the top. The image
530 size must be 460 x 90 pixels, any bit depth. This property
531 must be set read-only for the guest
532 (<computeroutput>RDONLYGUEST</computeroutput>).
533 </para>
534 </listitem>
535
536 <listitem>
537 <para>
538 <computeroutput>UseTheming</computeroutput>: Set to 1 for
539 turning on the following theming options. This property
540 must be set read-only for the guest
541 (<computeroutput>RDONLYGUEST</computeroutput>).
542 </para>
543 </listitem>
544
545 <listitem>
546 <para>
547 <computeroutput>Theme/BackgroundColor</computeroutput>:
548 Hexadecimal RRGGBB color for the background. This property
549 must be set read-only for the guest
550 (<computeroutput>RDONLYGUEST</computeroutput>).
551 </para>
552 </listitem>
553
554 <listitem>
555 <para>
556 <computeroutput>Theme/LogonDialog/HeaderColor</computeroutput>:
557 Hexadecimal RRGGBB foreground color for the header text.
558 This property must be set read-only for the guest
559 (<computeroutput>RDONLYGUEST</computeroutput>).
560 </para>
561 </listitem>
562
563 <listitem>
564 <para>
565 <computeroutput>Theme/LogonDialog/BackgroundColor</computeroutput>:
566 Hexadecimal RRGGBB color for the login dialog background.
567 This property must be set read-only for the guest
568 (<computeroutput>RDONLYGUEST</computeroutput>).
569 </para>
570 </listitem>
571
572 <listitem>
573 <para>
574 <computeroutput>Theme/LogonDialog/ButtonColor</computeroutput>:
575 Hexadecimal RRGGBB background color for the login dialog
576 button. This property must be set read-only for the guest
577 (<computeroutput>RDONLYGUEST</computeroutput>).
578 </para>
579 </listitem>
580
581 </itemizedlist>
582
583 <note>
584 <para>
585 The same restrictions for the guest properties above apply
586 as for the ones specified in the pam_vbox section.
587 </para>
588 </note>
589
590 </sect3>
591
592 </sect2>
593
594 </sect1>
595
596 <sect1 id="adv-config-win-guest">
597
598 <title>Advanced Configuration for Windows Guests</title>
599
600 <sect2 id="sysprep">
601
602 <title>Automated Windows System Preparation</title>
603
604 <para>
605 Beginning with Windows NT 4.0, Microsoft offers a system
606 preparation tool called Sysprep, to prepare a Windows system for
607 deployment or redistribution. Whereas Windows 2000 and XP ship
608 with Sysprep on the installation medium, the tool also is
609 available for download on the Microsoft web site. In a standard
610 installation of Windows Vista and 7, Sysprep is already
611 included. Sysprep mainly consists of an executable called
612 <computeroutput>sysprep.exe</computeroutput> which is invoked by
613 the user to put the Windows installation into preparation mode.
614 </para>
615
616 <para>
617 The Guest Additions offer a way to launch a system preparation
618 on the guest operating system in an automated way, controlled
619 from the host system. See
620 <xref linkend="guestadd-guestcontrol" /> for details of how to
621 use this feature with the special identifier
622 <computeroutput>sysprep</computeroutput> as the program to
623 execute, along with the user name
624 <computeroutput>sysprep</computeroutput> and password
625 <computeroutput>sysprep</computeroutput> for the credentials.
626 Sysprep then gets launched with the required system rights.
627 </para>
628
629 <note>
630 <para>
631 Specifying the location of "sysprep.exe" is
632 <emphasis
633 role="bold">not possible</emphasis>. Instead
634 the following paths are used, based on the operating system:
635 </para>
636
637 <itemizedlist>
638
639 <listitem>
640 <para>
641 <computeroutput>C:\sysprep\sysprep.exe</computeroutput>
642 for Windows NT 4.0, 2000 and XP
643 </para>
644 </listitem>
645
646 <listitem>
647 <para>
648 <computeroutput>%WINDIR%\System32\Sysprep\sysprep.exe</computeroutput>
649 for Windows Vista, 2008 Server and 7
650 </para>
651 </listitem>
652
653 </itemizedlist>
654
655 <para>
656 The Guest Additions will automatically use the appropriate
657 path to execute the system preparation tool.
658 </para>
659 </note>
660
661 </sect2>
662
663 </sect1>
664
665 <sect1 id="adv-config-linux-guest">
666
667 <title>Advanced Configuration for Linux and Oracle Solaris Guests</title>
668
669 <sect2 id="linux-guest-manual-setup">
670
671 <title>Manual Setup of Selected Guest Services on Linux</title>
672
673 <para>
674 The &product-name; Guest Additions contain several different
675 drivers. If for any reason you do not wish to set them all up,
676 you can install the Guest Additions using the following command:
677 </para>
678
679<screen> sh ./VBoxLinuxAdditions.run no_setup</screen>
680
681 <para>
682 After this, you will need to at least compile the kernel modules
683 by running the command as root:
684 </para>
685
686<screen> rcvboxadd setup</screen>
687
688 <para>
689 You will need to replace <emphasis>lib</emphasis> by
690 <emphasis>lib64</emphasis> on some 64bit guests, and on older
691 guests without the udev service you will need to add the
692 <emphasis>vboxadd</emphasis> service to the default runlevel to
693 ensure that the modules get loaded.
694 </para>
695
696 <para>
697 To setup the time synchronization service, add the service
698 vboxadd-service to the default runlevel. To set up the X11 and
699 OpenGL part of the Guest Additions, run the following command:
700 </para>
701
702<screen> rcvboxadd-x11 setup</screen>
703
704 <para>
705 You do not need to enable any services for this.
706 </para>
707
708 <para>
709 To recompile the guest kernel modules, use this command:
710 </para>
711
712<screen> rcvboxadd setup</screen>
713
714 <para>
715 After compilation you should reboot your guest to ensure that
716 the new modules are actually used.
717 </para>
718
719 </sect2>
720
721 <sect2 id="guestxorgsetup">
722
723 <title>Guest Graphics and Mouse Driver Setup in Depth</title>
724
725 <para>
726 This section assumes that you are familiar with configuring the
727 X.Org server using xorg.conf and optionally the newer mechanisms
728 using hal or udev and xorg.conf.d. If not you can learn about
729 them by studying the documentation which comes with X.Org.
730 </para>
731
732 <para>
733 The &product-name; Guest Additions include the following drivers
734 for X.Org versions:
735 </para>
736
737 <itemizedlist>
738
739 <listitem>
740 <para>
741 X11R6.8/X11R6.9 and XFree86 version 4.3 (vboxvideo_drv_68.o
742 and vboxmouse_drv_68.o)
743 </para>
744 </listitem>
745
746 <listitem>
747 <para>
748 X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so)
749 </para>
750 </listitem>
751
752 <listitem>
753 <para>
754 X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so)
755 </para>
756 </listitem>
757
758 <listitem>
759 <para>
760 X.Org Server versions 1.3 and later (vboxvideo_drv_13.so
761 vboxmouse_drv_13.so, and later versions).
762 </para>
763 </listitem>
764
765 </itemizedlist>
766
767 <para>
768 By default these drivers can be found in the folowing directory:
769 </para>
770
771 <para>
772 <computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/other/</computeroutput>
773 </para>
774
775 <para>
776 The correct versions for the X server are symbolically linked
777 into the X.Org driver directories.
778 </para>
779
780 <para>
781 For graphics integration to work correctly, the X server must
782 load the vboxvideo driver. Many recent X server versions look
783 for it automatically if they see that they are running in
784 &product-name;. For an optimal user experience the guest kernel
785 drivers must be loaded and the Guest Additions tool VBoxClient
786 must be running as a client in the X session. For mouse
787 integration to work correctly, the guest kernel drivers must be
788 loaded and in addition, in X servers from X.Org X11R6.8 to
789 X11R7.1 and in XFree86 version 4.3 the right vboxmouse driver
790 must be loaded and associated with /dev/mouse or /dev/psaux. In
791 X.Org server 1.3 or later a driver for a PS/2 mouse must be
792 loaded and the right vboxmouse driver must be associated with
793 /dev/vboxguest.
794 </para>
795
796 <para>
797 The &product-name; guest graphics driver can use any graphics
798 configuration for which the virtual resolution fits into the
799 virtual video memory allocated to the virtual machine, minus a
800 small amount used by the guest driver, as described in
801 <xref
802 linkend="settings-display" />. The driver will offer
803 a range of standard modes at least up to the default guest
804 resolution for all active guest monitors. In X.Org Server 1.3
805 and later the default mode can be changed by setting the output
806 property VBOX_MODE to "&lt;width&gt;x&lt;height&gt;" for any
807 guest monitor. When VBoxClient and the kernel drivers are active
808 this is done automatically when the host requests a mode change.
809 The driver for older versions can only receive new modes by
810 querying the host for requests at regular intervals.
811 </para>
812
813 <para>
814 With X Servers before version 1.3, you can also add your own
815 modes to the X server configuration file. You simply need to add
816 them to the "Modes" list in the "Display" subsection of the
817 "Screen" section. For example, the following section has a
818 custom 2048x800 resolution mode added:
819 </para>
820
821<screen>Section "Screen"
822 Identifier "Default Screen"
823 Device "VirtualBox graphics card"
824 Monitor "Generic Monitor"
825 DefaultDepth 24
826 SubSection "Display"
827 Depth 24
828 Modes "2048x800" "800x600" "640x480"
829 EndSubSection
830EndSection</screen>
831
832 </sect2>
833
834 </sect1>
835
836 <sect1 id="cpuhotplug">
837
838 <title>CPU Hot-Plugging</title>
839
840 <para>
841 With virtual machines running modern server operating systems,
842 &product-name; supports CPU hot-plugging.
843 </para>
844
845 <para>
846 On a physical computer CPU hot-plugging would mean that a CPU can
847 be added or removed while the machine is running. &product-name;
848 supports adding and removing of virtual CPUs while a virtual
849 machine is running.
850 </para>
851
852 <para>
853 CPU hot-plugging works only with guest operating systems that
854 support the feature. So far this applies only to Linux and Windows
855 Server. Windows supports only hot-add, while Linux supports
856 hot-add and hot-remove. To use this feature with more than 8 CPUs,
857 a 64-bit Linux guest is required.
858 </para>
859
860 <para>
861 CPU hot-plugging is done using the <command>VBoxManage</command>
862 command-line interface. First, hot-plugging needs to be enabled
863 for a virtual machine:
864 </para>
865
866<screen>VBoxManage modifyvm "VM name" --cpuhotplug on</screen>
867
868 <para>
869 The <computeroutput>--cpus</computeroutput> option is used to
870 specify the maximum number of CPUs that the virtual machine can
871 have:
872 </para>
873
874<screen>VBoxManage modifyvm "VM name" --cpus 8</screen>
875
876 <para>
877 When the VM is off, you can then add and remove virtual CPUs with
878 the <computeroutput>modifyvm --plugcpu</computeroutput> and
879 <computeroutput>--unplugcpu</computeroutput> subcommands, which
880 take the number of the virtual CPU as a parameter, as follows:
881 </para>
882
883<screen>VBoxManage modifyvm "VM name" --plugcpu 3
884VBoxManage modifyvm "VM name" --unplugcpu 3</screen>
885
886 <para>
887 Note that CPU 0 can never be removed.
888 </para>
889
890 <para>
891 While the VM is running, CPUs can be added and removed with the
892 <computeroutput>controlvm plugcpu</computeroutput> and
893 <computeroutput>unplugcpu</computeroutput> commands instead, as
894 follows:
895 </para>
896
897<screen>VBoxManage controlvm "VM name" plugcpu 3
898VBoxManage controlvm "VM name" unplugcpu 3</screen>
899
900 <para>
901 See <xref linkend="vboxmanage-modifyvm" /> and
902 <xref
903 linkend="vboxmanage-controlvm" /> for details.
904 </para>
905
906 <para>
907 With Linux guests, the following applies:
908 </para>
909
910 <para>
911 To prevent ejection while the CPU is still used it has to be
912 ejected from within the guest before. The Linux Guest Additions
913 contain a service which receives hot-remove events and ejects the
914 CPU. Also, after a CPU is added to the VM it is not automatically
915 used by Linux. The Linux Guest Additions service will take care of
916 that if installed. If not a CPU can be started with the following
917 command:
918 </para>
919
920<screen>echo 1 &gt; /sys/devices/system/cpu/cpu&lt;id&gt;/online</screen>
921
922 </sect1>
923
924 <sect1 id="pcipassthrough">
925
926 <title>PCI Passthrough</title>
927
928 <para>
929 When running on Linux hosts with a kernel version later than
930 <computeroutput>2.6.31</computeroutput>, experimental host PCI
931 devices passthrough is available.
932 </para>
933
934 <note>
935 <para>
936 The PCI passthrough module is shipped as a &product-name;
937 extension package, which must be installed separately. See
938 <xref
939 linkend="intro-installing" />.
940 </para>
941 </note>
942
943 <para>
944 This feature enables a guest to directly use physical PCI devices
945 on the host, even if host does not have drivers for this
946 particular device. Both, regular PCI and some PCI Express cards,
947 are supported. AGP and certain PCI Express cards are not supported
948 at the moment if they rely on Graphics Address Remapping Table
949 (GART) unit programming for texture management as it does rather
950 non-trivial operations with pages remapping interfering with
951 IOMMU. This limitation may be lifted in future releases.
952 </para>
953
954 <para>
955 To be fully functional, PCI passthrough support in &product-name;
956 depends upon an IOMMU hardware unit which is not yet too widely
957 available. If the device uses bus mastering, for example it
958 performs DMA to the OS memory on its own, then an IOMMU is
959 required. Otherwise such DMA transactions may write to the wrong
960 physical memory address as the device DMA engine is programmed
961 using a device-specific protocol to perform memory transactions.
962 The IOMMU functions as translation unit mapping physical memory
963 access requests from the device using knowledge of the guest
964 physical address to host physical addresses translation rules.
965 </para>
966
967 <para>
968 Intel's solution for IOMMU is called Intel Virtualization
969 Technology for Directed I/O (VT-d), and AMD's solution is called
970 AMD-Vi. Check your motherboard datasheet for the appropriate
971 technology. Even if your hardware does not have a IOMMU, certain
972 PCI cards may work, such as serial PCI adapters, but the guest
973 will show a warning on boot and the VM execution will terminate if
974 the guest driver will attempt to enable card bus mastering.
975 </para>
976
977 <para>
978 It is very common that the BIOS or the host OS disables the IOMMU
979 by default. So before any attempt to use it please make sure that
980 the following apply:
981 </para>
982
983 <itemizedlist>
984
985 <listitem>
986 <para>
987 Your motherboard has an IOMMU unit.
988 </para>
989 </listitem>
990
991 <listitem>
992 <para>
993 Your CPU supports the IOMMU.
994 </para>
995 </listitem>
996
997 <listitem>
998 <para>
999 The IOMMU is enabled in the BIOS.
1000 </para>
1001 </listitem>
1002
1003 <listitem>
1004 <para>
1005 The VM must run with VT-x/AMD-V and nested paging enabled.
1006 </para>
1007 </listitem>
1008
1009 <listitem>
1010 <para>
1011 Your Linux kernel was compiled with IOMMU support, including
1012 DMA remapping. See the
1013 <computeroutput>CONFIG_DMAR</computeroutput> kernel
1014 compilation option. The PCI stub driver
1015 (<computeroutput>CONFIG_PCI_STUB</computeroutput>) is required
1016 as well.
1017 </para>
1018 </listitem>
1019
1020 <listitem>
1021 <para>
1022 Your Linux kernel recognizes and uses the IOMMU unit. The
1023 <computeroutput>intel_iommu=on</computeroutput> boot option
1024 could be needed. Search for DMAR and PCI-DMA in kernel boot
1025 log.
1026 </para>
1027 </listitem>
1028
1029 </itemizedlist>
1030
1031 <para>
1032 Once you made sure that the host kernel supports the IOMMU, the
1033 next step is to select the PCI card and attach it to the guest. To
1034 figure out the list of available PCI devices, use the
1035 <command>lspci</command> command. The output will look as follows:
1036 </para>
1037
1038<screen>01:00.0 VGA compatible controller: ATI Technologies Inc Cedar PRO [Radeon HD 5450]
103901:00.1 Audio device: ATI Technologies Inc Manhattan HDMI Audio [Mobility Radeon HD 5000 Series]
104002:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168B PCI Express Gigabit
1041 Ethernet controller (rev 03)
104203:00.0 SATA controller: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
104303:00.1 IDE interface: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
104406:00.0 VGA compatible controller: nVidia Corporation G86 [GeForce 8500 GT] (rev a1)</screen>
1045
1046 <para>
1047 The first column is a PCI address, in the format
1048 <computeroutput>bus:device.function</computeroutput>. This address
1049 could be used to identify the device for further operations. For
1050 example, to attach a PCI network controller on the system listed
1051 above to the second PCI bus in the guest, as device 5, function 0,
1052 use the following command:
1053 </para>
1054
1055<screen>VBoxManage modifyvm "VM name" --pciattach 02:00.0@01:05.0</screen>
1056
1057 <para>
1058 To detach the same device, use:
1059 </para>
1060
1061<screen>VBoxManage modifyvm "VM name" --pcidetach 02:00.0</screen>
1062
1063 <para>
1064 Please note that both host and guest could freely assign a
1065 different PCI address to the card attached during runtime, so
1066 those addresses only apply to the address of the card at the
1067 moment of attachment on the host, and during BIOS PCI init on the
1068 guest.
1069 </para>
1070
1071 <para>
1072 If the virtual machine has a PCI device attached, certain
1073 limitations apply:
1074 </para>
1075
1076 <itemizedlist>
1077
1078 <listitem>
1079 <para>
1080 Only PCI cards with non-shared interrupts, such as those using
1081 MSI on the host, are supported at the moment.
1082 </para>
1083 </listitem>
1084
1085 <listitem>
1086 <para>
1087 No guest state can be reliably saved or restored. The internal
1088 state of the PCI card cannot be retrieved.
1089 </para>
1090 </listitem>
1091
1092 <listitem>
1093 <para>
1094 Teleportation, also called live migration, does not work. The
1095 internal state of the PCI card cannot be retrieved.
1096 </para>
1097 </listitem>
1098
1099 <listitem>
1100 <para>
1101 No lazy physical memory allocation. The host will preallocate
1102 the whole RAM required for the VM on startup, as we cannot
1103 catch physical hardware accesses to the physical memory.
1104 </para>
1105 </listitem>
1106
1107 </itemizedlist>
1108
1109 </sect1>
1110
1111 <sect1 id="webcam-passthrough">
1112
1113 <title>Webcam Passthrough</title>
1114
1115 <sect2 id="webcam-using-guest">
1116
1117 <title>Using a Host Webcam in the Guest</title>
1118
1119 <para>
1120 &product-name; 4.3 includes an experimental feature which
1121 enables a guest to use a host webcam. This complements the
1122 general USB passthrough support which was the typical way of
1123 using host webcams in earlier versions. The webcam passthrough
1124 support can handle non-USB video sources in theory, but this is
1125 completely untested.
1126 </para>
1127
1128 <note>
1129 <para>
1130 The webcam passthrough module is shipped as part of the
1131 &product-name; extension pack, which must be installed
1132 separately. See <xref
1133 linkend="intro-installing" />.
1134 </para>
1135 </note>
1136
1137 <para>
1138 The host webcam can be attached to the VM using the
1139 <emphasis role="bold">Devices</emphasis> menu in the VM menu
1140 bar. The <emphasis role="bold">Webcams</emphasis> menu contains
1141 a list of available video input devices on the host. Clicking on
1142 a webcam name attaches or detaches the corresponding host
1143 device.
1144 </para>
1145
1146 <para>
1147 The <command>VBoxManage</command> command line tool can be used
1148 to enable webcam passthrough. Please see the host-specific
1149 sections below for additional details. The following commands
1150 are available:
1151 </para>
1152
1153 <itemizedlist>
1154
1155 <listitem>
1156 <para>
1157 Get a list of host webcams, or other video input devices:
1158 </para>
1159
1160<screen>VBoxManage list webcams</screen>
1161
1162 <para>
1163 The output format is as follows:
1164 </para>
1165
1166<screen>alias "user friendly name"
1167host path or identifier</screen>
1168
1169 <para>
1170 The alias can be used as a shortcut in other commands. Alias
1171 '.0' means the default video input device on the host. Alias
1172 '.1', '.2'means first, second video input device, and so on.
1173 The device order is host-specific.
1174 </para>
1175 </listitem>
1176
1177 <listitem>
1178 <para>
1179 Attach a webcam to a running VM, as follows:
1180 </para>
1181
1182<screen>VBoxManage controlvm "VM name" webcam attach [host_path|alias [settings]]</screen>
1183
1184 <para>
1185 This attaches a USB webcam device to the guest.
1186 </para>
1187
1188 <para>
1189 The <computeroutput>settings</computeroutput> parameter is a
1190 string
1191 <computeroutput>Setting1=Value1;Setting2=Value2</computeroutput>,
1192 which enables you to configure the emulated webcam device.
1193 The following settings are supported:
1194 </para>
1195
1196 <itemizedlist>
1197
1198 <listitem>
1199 <para>
1200 <computeroutput>MaxFramerate</computeroutput>: The
1201 highest rate at which video frames are sent to the
1202 guest. A higher frame rate requires more CPU power.
1203 Therefore sometimes it is useful to set a lower limit.
1204 Default is no limit and allow the guest to use all frame
1205 rates supported by the host webcam.
1206 </para>
1207 </listitem>
1208
1209 <listitem>
1210 <para>
1211 <computeroutput>MaxPayloadTransferSize</computeroutput>:
1212 How many bytes the emulated webcam can send to the guest
1213 at a time. Default value is 3060 bytes, which is used by
1214 some webcams. Higher values can slightly reduce CPU
1215 load, if the guest is able to use larger buffers.
1216 However, a high
1217 <computeroutput>MaxPayloadTransferSize</computeroutput>
1218 might be not supported by some guests.
1219 </para>
1220 </listitem>
1221
1222 </itemizedlist>
1223 </listitem>
1224
1225 <listitem>
1226 <para>
1227 Detach a webcam from a running VM, as follows:
1228 </para>
1229
1230<screen>VBoxManage controlvm "VM name" webcam detach [host_path|alias]</screen>
1231 </listitem>
1232
1233 <listitem>
1234 <para>
1235 List the webcams attached to a running VM, as follows:
1236 </para>
1237
1238<screen>VBoxManage controlvm "VM name" webcam list</screen>
1239
1240 <para>
1241 The output contains the path or alias which was used in the
1242 <command>webcam attach</command> command for each attached
1243 webcam.
1244 </para>
1245 </listitem>
1246
1247 </itemizedlist>
1248
1249 </sect2>
1250
1251 <sect2 id="webcam-win-hosts">
1252
1253 <title>Windows Hosts</title>
1254
1255 <para>
1256 When the webcam device is detached from the host, the emulated
1257 webcam device is automatically detached from the guest.
1258 </para>
1259
1260 </sect2>
1261
1262 <sect2 id="webcam-mac-hosts">
1263
1264 <title>Mac OS X Hosts</title>
1265
1266 <para>
1267 OS X version 10.9 or later is required.
1268 </para>
1269
1270 <para>
1271 When the webcam device is detached from the host, the emulated
1272 webcam device remains attached to the guest and must be manually
1273 detached using the <computeroutput>VBoxManage controlvm "VM
1274 name" webcam detach</computeroutput> command.
1275 </para>
1276
1277 </sect2>
1278
1279 <sect2 id="webcam-linux-hosts">
1280
1281 <title>Linux and Oracle Solaris Hosts</title>
1282
1283 <para>
1284 When the webcam is detached from the host the emulated webcam
1285 device is automatically detached from the guest only if the
1286 webcam is streaming video. If the emulated webcam is inactive it
1287 should be manually detached using the <computeroutput>VBoxManage
1288 controlvm "VM name" webcam detach</computeroutput> command.
1289 </para>
1290
1291 <para>
1292 Aliases <computeroutput>.0</computeroutput> and
1293 <computeroutput>.1</computeroutput> are mapped to
1294 <computeroutput>/dev/video0</computeroutput>, alias
1295 <computeroutput>.2</computeroutput> is mapped to
1296 <computeroutput>/dev/video1</computeroutput> and so forth.
1297 </para>
1298
1299 </sect2>
1300
1301 </sect1>
1302
1303 <sect1 id="adv-display-config">
1304
1305 <title>Advanced Display Configuration</title>
1306
1307 <sect2 id="customvesa">
1308
1309 <title>Custom VESA Resolutions</title>
1310
1311 <para>
1312 Apart from the standard VESA resolutions, the &product-name;
1313 VESA BIOS enables you to add up to 16 custom video modes which
1314 will be reported to the guest operating system. When using
1315 Windows guests with the &product-name; Guest Additions, a custom
1316 graphics driver will be used instead of the fallback VESA
1317 solution so this information does not apply.
1318 </para>
1319
1320 <para>
1321 Additional video modes can be configured for each VM using the
1322 extra data facility. The extra data key is called
1323 <computeroutput>CustomVideoMode&lt;x&gt;</computeroutput> with
1324 <computeroutput>x</computeroutput> being a number from 1 to 16.
1325 Please note that modes will be read from 1 until either the
1326 following number is not defined or 16 is reached. The following
1327 example adds a video mode that corresponds to the native display
1328 resolution of many notebook computers:
1329 </para>
1330
1331<screen>VBoxManage setextradata "VM name" "CustomVideoMode1" "1400x1050x16"</screen>
1332
1333 <para>
1334 The VESA mode IDs for custom video modes start at
1335 <computeroutput>0x160</computeroutput>. In order to use the
1336 above defined custom video mode, the following command line has
1337 to be supplied to Linux:
1338 </para>
1339
1340<screen>vga = 0x200 | 0x160
1341vga = 864</screen>
1342
1343 <para>
1344 For guest operating systems with &product-name; Guest Additions,
1345 a custom video mode can be set using the video mode hint
1346 feature.
1347 </para>
1348
1349 </sect2>
1350
1351 <sect2 id="max-resolution-guests">
1352
1353 <title>Configuring the Maximum Resolution of Guests When Using the Graphical
1354 Frontend</title>
1355
1356 <para>
1357 When guest systems with the Guest Additions installed are
1358 started using the graphical frontend, the normal &product-name;
1359 application, they will not be allowed to use screen resolutions
1360 greater than the host's screen size unless the user manually
1361 resizes them by dragging the window, switching to full screen or
1362 seamless mode or sending a video mode hint using
1363 <command>VBoxManage</command>. This behavior is what most users
1364 will want, but if you have different needs, it is possible to
1365 change it by issuing one of the following commands from the
1366 command line:
1367 </para>
1368
1369<screen>VBoxManage setextradata global GUI/MaxGuestResolution any</screen>
1370
1371 <para>
1372 will remove all limits on guest resolutions.
1373 </para>
1374
1375<screen>VBoxManage setextradata global GUI/MaxGuestResolution &gt;width,height&lt;</screen>
1376
1377 <para>
1378 manually specifies a maximum resolution.
1379 </para>
1380
1381<screen>VBoxManage setextradata global GUI/MaxGuestResolution auto</screen>
1382
1383 <para>
1384 restores the default settings. Note that these settings apply
1385 globally to all guest systems, not just to a single machine.
1386 </para>
1387
1388 </sect2>
1389
1390 </sect1>
1391
1392 <sect1 id="adv-storage-config">
1393
1394 <title>Advanced Storage Configuration</title>
1395
1396 <sect2 id="rawdisk">
1397
1398 <title>Using a Raw Host Hard Disk From a Guest</title>
1399
1400 <para>
1401 As an alternative to using virtual disk images as described in
1402 <xref linkend="storage" />, &product-name; can also present
1403 either entire physical hard disks or selected partitions as
1404 virtual disks to virtual machines.
1405 </para>
1406
1407 <para>
1408 With &product-name;, this type of access is called <emphasis>raw
1409 hard disk access</emphasis>. It enables a guest operating system
1410 to access its virtual hard disk without going through the host
1411 OS file system. The actual performance difference for image
1412 files vs. raw disk varies greatly depending on the overhead of
1413 the host file system, whether dynamically growing images are
1414 used, and on host OS caching strategies. The caching indirectly
1415 also affects other aspects such as failure behavior. For
1416 example, whether the virtual disk contains all data written
1417 before a host OS crash. Consult your host OS documentation for
1418 details on this.
1419 </para>
1420
1421 <warning>
1422 <para>
1423 Raw hard disk access is for expert users only. Incorrect use
1424 or use of an outdated configuration can lead to
1425 <emphasis role="bold">total loss of data</emphasis> on the
1426 physical disk. Most importantly, <emphasis>do not</emphasis>
1427 attempt to boot the partition with the currently running host
1428 operating system in a guest. This will lead to severe data
1429 corruption.
1430 </para>
1431 </warning>
1432
1433 <para>
1434 Raw hard disk access, both for entire disks and individual
1435 partitions, is implemented as part of the VMDK image format
1436 support. As a result, you will need to create a special VMDK
1437 image file which defines where the data will be stored. After
1438 creating such a special VMDK image, you can use it like a
1439 regular virtual disk image. For example, you can use the
1440 VirtualBox Manager, see <xref linkend="vdis" />, or
1441 <command>VBoxManage</command> to assign the image to a virtual
1442 machine.
1443 </para>
1444
1445 <sect3 id="rawdisk-access-entire-physical-disk">
1446
1447 <title>Access to Entire Physical Hard Disk</title>
1448
1449 <para>
1450 While this variant is the simplest to set up, you must be
1451 aware that this will give a guest operating system direct and
1452 full access to an <emphasis>entire physical disk</emphasis>.
1453 If your <emphasis>host</emphasis> operating system is also
1454 booted from this disk, please take special care to not access
1455 the partition from the guest at all. On the positive side, the
1456 physical disk can be repartitioned in arbitrary ways without
1457 having to recreate the image file that gives access to the raw
1458 disk.
1459 </para>
1460
1461 <para>
1462 On a Linux host, to create an image that represents an entire
1463 physical hard disk which will not contain any actual data, as
1464 this will all be stored on the physical disk, use the
1465 following command:
1466 </para>
1467
1468<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
1469 -rawdisk /dev/sda</screen>
1470
1471 <para>
1472 This creates the image
1473 <computeroutput>/path/to/file.vmdk</computeroutput>, which
1474 must be an absolute path. All data will be read and written
1475 from <computeroutput>/dev/sda</computeroutput>.
1476 </para>
1477
1478 <para>
1479 On a Windows host, instead of the above device specification,
1480 for example use
1481 <computeroutput>\\.\PhysicalDrive0</computeroutput>. On a Mac
1482 OS X host, instead of the above device specification use for
1483 example <computeroutput>/dev/disk1</computeroutput>. Note that
1484 on OS X you can only get access to an entire disk if no volume
1485 is mounted from it.
1486 </para>
1487
1488 <para>
1489 Creating the image requires read/write access for the given
1490 device. Read/write access is also later needed when using the
1491 image from a virtual machine. On some host platforms, such as
1492 Windows Vista and later, raw disk access may be restricted and
1493 not permitted by the host OS in some situations.
1494 </para>
1495
1496 <para>
1497 Just like with regular disk images, this does not
1498 automatically attach the newly created image to a virtual
1499 machine. This can be done as follows:
1500 </para>
1501
1502<screen>VBoxManage storageattach WindowsXP --storagectl "IDE Controller"
1503 --port 0 --device 0 --type hdd --medium /path/to/file.vmdk</screen>
1504
1505 <para>
1506 When this is done the selected virtual machine will boot from
1507 the specified physical disk.
1508 </para>
1509
1510 </sect3>
1511
1512 <sect3 id="rawdisk-access-disk-partitions">
1513
1514 <title>Access to Individual Physical Hard Disk Partitions</title>
1515
1516 <para>
1517 This <emphasis>raw partition support</emphasis> is quite
1518 similar to the full hard disk access described above. However,
1519 in this case, any partitioning information will be stored
1520 inside the VMDK image. This means that you can install a
1521 different boot loader in the virtual hard disk without
1522 affecting the host's partitioning information. While the guest
1523 will be able to <emphasis>see</emphasis> all partitions that
1524 exist on the physical disk, access will be filtered in that
1525 reading from partitions for which no access is allowed the
1526 partitions will only yield zeroes, and all writes to them are
1527 ignored.
1528 </para>
1529
1530 <para>
1531 To create a special image for raw partition support, which
1532 will contain a small amount of data, on a Linux host, use the
1533 command:
1534 </para>
1535
1536<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
1537 -rawdisk /dev/sda -partitions 1,5</screen>
1538
1539 <para>
1540 The command is identical to the one for full hard disk access,
1541 except for the additional
1542 <computeroutput>-partitions</computeroutput> parameter. This
1543 example would create the image
1544 <computeroutput>/path/to/file.vmdk</computeroutput>, which
1545 must be absolute, and partitions 1 and 5 of
1546 <computeroutput>/dev/sda</computeroutput> would be made
1547 accessible to the guest.
1548 </para>
1549
1550 <para>
1551 &product-name; uses the same partition numbering as your Linux
1552 host. As a result, the numbers given in the above example
1553 would refer to the first primary partition and the first
1554 logical drive in the extended partition, respectively.
1555 </para>
1556
1557 <para>
1558 On a Windows host, instead of the above device specification,
1559 use for example
1560 <computeroutput>\\.\PhysicalDrive0</computeroutput>. On a Mac
1561 OS X host, instead of the above device specification use
1562 <computeroutput>/dev/disk1</computeroutput>, for example. Note
1563 that on OS X you can only use partitions which are not
1564 mounted. Eject the respective volume first. Partition numbers
1565 are the same on Linux, Windows, and Mac OS X hosts.
1566 </para>
1567
1568 <para>
1569 The numbers for the list of partitions can be taken from the
1570 output of the following command:
1571 </para>
1572
1573<screen>VBoxManage internalcommands listpartitions -rawdisk /dev/sda</screen>
1574
1575 <para>
1576 The output lists the partition types and sizes to give the
1577 user enough information to identify the partitions necessary
1578 for the guest.
1579 </para>
1580
1581 <para>
1582 Images which give access to individual partitions are specific
1583 to a particular host disk setup. You cannot transfer these
1584 images to another host. Also, whenever the host partitioning
1585 changes, the image <emphasis>must be recreated</emphasis>.
1586 </para>
1587
1588 <para>
1589 Creating the image requires read/write access for the given
1590 device. Read/write access is also later needed when using the
1591 image from a virtual machine. If this is not feasible, there
1592 is a special variant for raw partition access, currently only
1593 available on Linux hosts, that avoids having to give the
1594 current user access to the entire disk. To set up such an
1595 image, use:
1596 </para>
1597
1598<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
1599 -rawdisk /dev/sda -partitions 1,5 -relative</screen>
1600
1601 <para>
1602 When used from a virtual machine, the image will then refer
1603 not to the entire disk, but only to the individual partitions.
1604 In this example, <computeroutput>/dev/sda1</computeroutput>
1605 and <computeroutput>/dev/sda5</computeroutput>. As a
1606 consequence, read/write access is only required for the
1607 affected partitions, not for the entire disk. During creation
1608 however, read-only access to the entire disk is required to
1609 obtain the partitioning information.
1610 </para>
1611
1612 <para>
1613 In some configurations it may be necessary to change the MBR
1614 code of the created image. For example, to replace the Linux
1615 boot loader that is used on the host by another boot loader.
1616 This enables for example the guest to boot directly to
1617 Windows, while the host boots Linux from the "same" disk. For
1618 this purpose the <computeroutput>-mbr</computeroutput>
1619 parameter is provided. It specifies a file name from which to
1620 take the MBR code. The partition table is not modified at all,
1621 so a MBR file from a system with totally different
1622 partitioning can be used. An example of this is:
1623 </para>
1624
1625<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
1626 -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr</screen>
1627
1628 <para>
1629 The modified MBR will be stored inside the image, not on the
1630 host disk.
1631 </para>
1632
1633 <para>
1634 The created image can be attached to a storage controller in a
1635 VM configuration as usual.
1636 </para>
1637
1638 </sect3>
1639
1640 </sect2>
1641
1642 <sect2 id="changevpd">
1643
1644 <title>Configuring the Hard Disk Vendor Product Data (VPD)</title>
1645
1646 <para>
1647 &product-name; reports vendor product data for its virtual hard
1648 disks which consist of hard disk serial number, firmware
1649 revision and model number. These can be changed using the
1650 following commands:
1651 </para>
1652
1653<screen>VBoxManage setextradata "VM name"
1654 "VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial"
1655VBoxManage setextradata "VM name"
1656 "VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware"
1657VBoxManage setextradata "VM name"
1658 "VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model"</screen>
1659
1660 <para>
1661 The serial number is a 20 byte alphanumeric string, the firmware
1662 revision an 8 byte alphanumeric string and the model number a 40
1663 byte alphanumeric string. Instead of Port0, referring to the
1664 first port, specify the desired SATA hard disk port.
1665 </para>
1666
1667 <para>
1668 The above commands apply to virtual machines with an AHCI (SATA)
1669 controller. The commands for virtual machines with an IDE
1670 controller are:
1671 </para>
1672
1673<screen>VBoxManage setextradata "VM name"
1674 "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial"
1675VBoxManage setextradata "VM name"
1676 "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware"
1677VBoxManage setextradata "VM name"
1678 "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model"</screen>
1679
1680 <para>
1681 For hard disks it is also possible to mark the drive as having a
1682 non-rotational medium with:
1683 </para>
1684
1685<screen>VBoxManage setextradata "VM name"
1686 "VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1"</screen>
1687
1688 <para>
1689 Additional three parameters are needed for CD/DVD drives to
1690 report the vendor product data:
1691 </para>
1692
1693<screen>VBoxManage setextradata "VM name"
1694 "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor"
1695VBoxManage setextradata "VM name"
1696 "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product"
1697VBoxManage setextradata "VM name"
1698 "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIRevision" "revision"</screen>
1699
1700 <para>
1701 The vendor id is an 8 byte alphanumeric string, the product id
1702 an 16 byte alphanumeric string and the revision a 4 byte
1703 alphanumeric string. Instead of Port0, referring to the first
1704 port, specify the desired SATA hard disk port.
1705 </para>
1706
1707 </sect2>
1708
1709 <sect2 id="iscsi-intnet">
1710
1711 <title>Access iSCSI Targets Using Internal Networking</title>
1712
1713 <para>
1714 As an experimental feature, &product-name; enables access to an
1715 iSCSI target running in a virtual machine which is configured to
1716 use Internal Networking mode. See
1717 <xref linkend="storage-iscsi" />,
1718 <xref linkend="network_internal" />, and
1719 <xref
1720 linkend="vboxmanage-storageattach" />.
1721 </para>
1722
1723 <para>
1724 The IP stack accessing Internal Networking must be configured in
1725 the virtual machine which accesses the iSCSI target. A free
1726 static IP and a MAC address not used by other virtual machines
1727 must be chosen. In the example below, adapt the name of the
1728 virtual machine, the MAC address, the IP configuration, and the
1729 Internal Networking name (MyIntNet) according to your needs. The
1730 following eight commands must first be issued:
1731 </para>
1732
1733<screen>VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Trusted 1
1734VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f
1735VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1
1736VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0
1737VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet
1738VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet
1739VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/TrunkType 2
1740VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen>
1741
1742 <para>
1743 Finally the iSCSI disk must be attached with the
1744 <computeroutput>--intnet</computeroutput> option to tell the
1745 iSCSI initiator to use internal networking, as follows:
1746 </para>
1747
1748<screen>VBoxManage storageattach ... --medium iscsi
1749--server 10.0.9.30 --target iqn.2008-12.com.sun:sampletarget --intnet</screen>
1750
1751 <para>
1752 Compared to a regular iSCSI setup, the IP address of the target
1753 <emphasis>must</emphasis> be specified as a numeric IP address,
1754 as there is no DNS resolver for internal networking.
1755 </para>
1756
1757 <para>
1758 The virtual machine with the iSCSI target should be started
1759 before the VM using it is powered on. If a virtual machine using
1760 an iSCSI disk is started without having the iSCSI target powered
1761 up, it can take up to 200 seconds to detect this situation. The
1762 VM will fail to power up.
1763 </para>
1764
1765 </sect2>
1766
1767 </sect1>
1768
1769 <sect1 id="serialports-legacy-cmds">
1770
1771 <title>Legacy Commands for Using Serial Ports</title>
1772
1773 <para>
1774 In legacy releases, &product-name; provided support for virtual
1775 serial ports. This was rather complicated to set up, requiring a
1776 sequence of <command>VBoxManage setextradata</command> statements.
1777 That method of setting up serial ports is no longer necessary and
1778 <emphasis>deprecated.</emphasis> To set up virtual serial ports,
1779 use the methods described in <xref linkend="serialports" />.
1780 </para>
1781
1782 <note>
1783 <para>
1784 For backwards compatibility, the legacy
1785 <computeroutput>setextradata</computeroutput> statements, whose
1786 description is retained below from the old version of the
1787 manual, take <emphasis>precedence</emphasis> over the new way of
1788 configuring serial ports. As a result, if configuring serial
1789 ports the new way does not work, make sure the VM in question
1790 does not have old configuration data such as below still active.
1791 </para>
1792 </note>
1793
1794 <para>
1795 The legacy sequence of configuring a serial port used the
1796 following commands:
1797 </para>
1798
1799<screen>VBoxManage setextradata "VM name"
1800 "VBoxInternal/Devices/serial/0/Config/IRQ" 4
1801VBoxManage setextradata "VM name"
1802 "VBoxInternal/Devices/serial/0/Config/IOBase" 0x3f8
1803VBoxManage setextradata "VM name"
1804 "VBoxInternal/Devices/serial/0/LUN#0/Driver" Char
1805VBoxManage setextradata "VM name"
1806 "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Driver" NamedPipe
1807VBoxManage setextradata "VM name"
1808 "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/Location" "\\.\pipe\vboxCOM1"
1809VBoxManage setextradata "VM name"
1810 "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/IsServer" 1</screen>
1811
1812 <para>
1813 This sets up a serial port in the guest with the default settings
1814 for COM1 (IRQ 4, I/O address 0x3f8) and the
1815 <computeroutput>Location</computeroutput> setting assumes that
1816 this configuration is used on a Windows host, because the Windows
1817 named pipe syntax is used. Keep in mind that on Windows hosts a
1818 named pipe must always start with
1819 <computeroutput>\\.\pipe\</computeroutput>. On Linux the same
1820 configuration settings apply, except that the path name for the
1821 <computeroutput>Location</computeroutput> can be chosen more
1822 freely. Local domain sockets can be placed anywhere, provided the
1823 user running &product-name; has the permission to create a new
1824 file in the directory. The final command above defines that
1825 &product-name; acts as a server. It creates the named pipe itself
1826 instead of connecting to an already existing one.
1827 </para>
1828
1829 </sect1>
1830
1831 <sect1 id="changenat">
1832
1833 <title>Fine Tuning the &product-name; NAT Engine</title>
1834
1835 <sect2 id="nat-address-config">
1836
1837 <title>Configuring the Address of a NAT Network Interface</title>
1838
1839 <para>
1840 In NAT mode, the guest network interface is assigned to the IPv4
1841 range <computeroutput>10.0.x.0/24</computeroutput> by default
1842 where <computeroutput>x</computeroutput> corresponds to the
1843 instance of the NAT interface +2. So
1844 <computeroutput>x</computeroutput> is 2 when there is only one
1845 NAT instance active. In that case the guest is assigned to the
1846 address <computeroutput>10.0.2.15</computeroutput>, the gateway
1847 is set to <computeroutput>10.0.2.2</computeroutput> and the name
1848 server can be found at
1849 <computeroutput>10.0.2.3</computeroutput>.
1850 </para>
1851
1852 <para>
1853 If the NAT network needs to be changed, use the following
1854 command:
1855 </para>
1856
1857<screen>VBoxManage modifyvm "VM name" --natnet1 "192.168/16"</screen>
1858
1859 <para>
1860 This command would reserve the network addresses from
1861 <computeroutput>192.168.0.0</computeroutput> to
1862 <computeroutput>192.168.254.254</computeroutput> for the first
1863 NAT network instance of "VM name". The guest IP would be
1864 assigned to <computeroutput>192.168.0.15</computeroutput> and
1865 the default gateway could be found at
1866 <computeroutput>192.168.0.2</computeroutput>.
1867 </para>
1868
1869 </sect2>
1870
1871 <sect2 id="nat-adv-tftp">
1872
1873 <title>Configuring the Boot Server (Next Server) of a NAT Network Interface</title>
1874
1875 <para>
1876 For network booting in NAT mode, by default &product-name; uses
1877 a built-in TFTP server at the IP address 10.0.2.4. This default
1878 behavior should work fine for typical remote-booting scenarios.
1879 However, it is possible to change the boot server IP and the
1880 location of the boot image with the following commands:
1881 </para>
1882
1883<screen>VBoxManage modifyvm "VM name" --nattftpserver1 10.0.2.2
1884VBoxManage modifyvm "VM name" --nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</screen>
1885
1886 </sect2>
1887
1888 <sect2 id="nat-adv-settings">
1889
1890 <title>Tuning TCP/IP Buffers for NAT</title>
1891
1892 <para>
1893 The &product-name; NAT stack performance is often determined by
1894 its interaction with the host's TCP/IP stack and the size of
1895 several buffers, <computeroutput>SO_RCVBUF</computeroutput> and
1896 <computeroutput>SO_SNDBUF</computeroutput>. For certain setups
1897 users might want to adjust the buffer size for a better
1898 performance. This can by achieved using the following commands,
1899 where values are in kilobytes and can range from 8 to 1024:
1900 </para>
1901
1902<screen>VBoxManage modifyvm "VM name" --natsettings1 16000,128,128,0,0</screen>
1903
1904 <para>
1905 This example illustrates tuning the NAT settings. The first
1906 parameter is the MTU, then the size of the socket's send buffer
1907 and the size of the socket's receive buffer, the initial size of
1908 the TCP send window, and lastly the initial size of the TCP
1909 receive window. Note that specifying zero means fallback to the
1910 default value.
1911 </para>
1912
1913 <para>
1914 Each of these buffers has a default size of 64KB and default MTU
1915 is 1500.
1916 </para>
1917
1918 </sect2>
1919
1920 <sect2 id="nat-bind-sockets">
1921
1922 <title>Binding NAT Sockets to a Specific Interface</title>
1923
1924 <para>
1925 By default, &product-name;'s NAT engine will route TCP/IP
1926 packets through the default interface assigned by the host's
1927 TCP/IP stack. The technical reason for this is that the NAT
1928 engine uses sockets for communication. If you want to change
1929 this behavior, you can tell the NAT engine to bind to a
1930 particular IP address instead. For example, use the following
1931 command:
1932 </para>
1933
1934<screen>VBoxManage modifyvm "VM name" --natbindip1 "10.45.0.2"</screen>
1935
1936 <para>
1937 After this, all outgoing traffic will be sent through the
1938 interface with the IP address 10.45.0.2. Ensure that this
1939 interface is up and running before changing the NAT bind
1940 address.
1941 </para>
1942
1943 </sect2>
1944
1945 <sect2 id="nat-adv-dns">
1946
1947 <title>Enabling DNS Proxy in NAT Mode</title>
1948
1949 <para>
1950 The NAT engine by default offers the same DNS servers to the
1951 guest that are configured on the host. In some scenarios, it can
1952 be desirable to hide the DNS server IPs from the guest, for
1953 example when this information can change on the host due to
1954 expiring DHCP leases. In this case, you can tell the NAT engine
1955 to act as DNS proxy using the following command:
1956 </para>
1957
1958<screen>VBoxManage modifyvm "VM name" --natdnsproxy1 on</screen>
1959
1960 </sect2>
1961
1962 <sect2 id="nat_host_resolver_proxy">
1963
1964 <title>Using the Host's Resolver as a DNS Proxy in NAT Mode</title>
1965
1966 <para>
1967 For resolving network names, the DHCP server of the NAT engine
1968 offers a list of registered DNS servers of the host. If for some
1969 reason you need to hide this DNS server list and use the host's
1970 resolver settings, thereby forcing the &product-name; NAT engine
1971 to intercept DNS requests and forward them to host's resolver,
1972 use the following command:
1973 </para>
1974
1975<screen>VBoxManage modifyvm "VM name" --natdnshostresolver1 on</screen>
1976
1977 <para>
1978 Note that this setting is similar to the DNS proxy mode, however
1979 whereas the proxy mode just forwards DNS requests to the
1980 appropriate servers, the resolver mode will interpret the DNS
1981 requests and use the host's DNS API to query the information and
1982 return it to the guest.
1983 </para>
1984
1985 <sect3 id="nat_host_resolver_name_intercepting">
1986
1987 <title>User-Defined Host Name Resolving</title>
1988
1989 <para>
1990 In some cases it might be useful to intercept the name
1991 resolving mechanism, providing a user-defined IP address on a
1992 particular DNS request. The intercepting mechanism enables the
1993 user to map not only a single host but domains and even more
1994 complex naming conventions if required.
1995 </para>
1996
1997 <para>
1998 The following command sets a rule for mapping a name to a
1999 specified IP:
2000 </para>
2001
2002<screen>VBoxManage setextradata "VM name" \
2003 "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
2004 &lt;unique rule name of interception rule&gt;/HostIP" &lt;IPv4&gt;
2005VBoxManage setextradata "VM name" \
2006 "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
2007 &lt;unique rule name&gt;/HostName" &lt;name of host&gt;</screen>
2008
2009 <para>
2010 The following command sets a rule for mapping a pattern name
2011 to a specified IP:
2012 </para>
2013
2014<screen>VBoxManage setextradata "VM name" \
2015 "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
2016 &lt;unique rule name&gt;/HostIP" &lt;IPv4&gt;
2017VBoxManage setextradata "VM name" \
2018 "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
2019 &lt;unique rule name&gt;/HostNamePattern" &lt;hostpattern&gt;</screen>
2020
2021 <para>
2022 The host pattern may include <computeroutput>"|", "?" and
2023 "*"</computeroutput>.
2024 </para>
2025
2026 <para>
2027 This example demonstrates how to instruct the host-resolver
2028 mechanism to resolve all domain and probably some mirrors of
2029 www.blocked-site.info site with IP 127.0.0.1:
2030 </para>
2031
2032<screen>VBoxManage setextradata "VM name" \
2033 "VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
2034 all_blocked_site/HostIP" 127.0.0.1
2035VBoxManage setextradata "VM name" \
2036 "VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
2037 all_blocked_site/HostNamePattern" "*.blocked-site.*|*.fb.org"</screen>
2038
2039 <para>
2040 The host resolver mechanism should be enabled to use
2041 user-defined mapping rules, otherwise they do not have any
2042 effect.
2043 </para>
2044
2045 </sect3>
2046
2047 </sect2>
2048
2049 <sect2 id="nat-adv-alias">
2050
2051 <title>Configuring Aliasing of the NAT Engine</title>
2052
2053 <para>
2054 By default, the NAT core uses aliasing and uses random ports
2055 when generating an alias for a connection. This works well for
2056 the most protocols like SSH, FTP and so on. Though some
2057 protocols might need a more transparent behavior or may depend
2058 on the real port number the packet was sent from. It is possible
2059 to change the NAT mode using the <command>VBoxManage</command>
2060 frontend with the following commands:
2061 </para>
2062
2063<screen>VBoxManage modifyvm "VM name" --nataliasmode1 proxyonly</screen>
2064
2065<screen>VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</screen>
2066
2067 <para>
2068 The first example disables aliasing and switches NAT into
2069 transparent mode, the second example enforces preserving of port
2070 values. These modes can be combined if necessary.
2071 </para>
2072
2073 </sect2>
2074
2075 </sect1>
2076
2077 <sect1 id="changedmi">
2078
2079 <title>Configuring the BIOS DMI Information</title>
2080
2081 <para>
2082 The DMI data that &product-name; provides to guests can be changed
2083 for a specific VM. Use the following commands to configure the DMI
2084 BIOS information. In case your VM is configured to use EFI
2085 firmware you need to replace
2086 <computeroutput>pcbios</computeroutput> by
2087 <computeroutput>efi</computeroutput> in the keys.
2088 </para>
2089
2090 <itemizedlist>
2091
2092 <listitem>
2093 <para>
2094 DMI BIOS information (type 0)
2095 </para>
2096
2097<screen>VBoxManage setextradata "VM name"
2098 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor" "BIOS Vendor"
2099VBoxManage setextradata "VM name"
2100 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion" "BIOS Version"
2101VBoxManage setextradata "VM name"
2102 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate" "BIOS Release Date"
2103VBoxManage setextradata "VM name"
2104 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor" 1
2105VBoxManage setextradata "VM name"
2106 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor" 2
2107VBoxManage setextradata "VM name"
2108 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3
2109VBoxManage setextradata "VM name"
2110 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4</screen>
2111 </listitem>
2112
2113 <listitem>
2114 <para>
2115 DMI system information (type 1)
2116 </para>
2117
2118<screen>VBoxManage setextradata "VM name"
2119 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor" "System Vendor"
2120VBoxManage setextradata "VM name"
2121 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct" "System Product"
2122VBoxManage setextradata "VM name"
2123 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion" "System Version"
2124VBoxManage setextradata "VM name"
2125 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "System Serial"
2126VBoxManage setextradata "VM name"
2127 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU" "System SKU"
2128VBoxManage setextradata "VM name"
2129 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily" "System Family"
2130VBoxManage setextradata "VM name"
2131 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid"
2132 "9852bf98-b83c-49db-a8de-182c42c7226b"</screen>
2133 </listitem>
2134
2135 <listitem>
2136 <para>
2137 DMI board information (type 2)
2138 </para>
2139
2140<screen>VBoxManage setextradata "VM name"
2141 "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVendor" "Board Vendor"
2142VBoxManage setextradata "VM name"
2143 "VBoxInternal/Devices/pcbios/0/Config/DmiBoardProduct" "Board Product"
2144VBoxManage setextradata "VM name"
2145 "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVersion" "Board Version"
2146VBoxManage setextradata "VM name"
2147 "VBoxInternal/Devices/pcbios/0/Config/DmiBoardSerial" "Board Serial"
2148VBoxManage setextradata "VM name"
2149 "VBoxInternal/Devices/pcbios/0/Config/DmiBoardAssetTag" "Board Tag"
2150VBoxManage setextradata "VM name"
2151 "VBoxInternal/Devices/pcbios/0/Config/DmiBoardLocInChass" "Board Location"
2152VBoxManage setextradata "VM name"
2153 "VBoxInternal/Devices/pcbios/0/Config/DmiBoardBoardType" 10</screen>
2154 </listitem>
2155
2156 <listitem>
2157 <para>
2158 DMI system enclosure or chassis (type 3)
2159 </para>
2160
2161<screen>VBoxManage setextradata "VM name"
2162 "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVendor" "Chassis Vendor"
2163VBoxManage setextradata "VM name"
2164 "VBoxInternal/Devices/pcbios/0/Config/DmiChassisType" 3
2165VBoxManage setextradata "VM name"
2166 "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVersion" "Chassis Version"
2167VBoxManage setextradata "VM name"
2168 "VBoxInternal/Devices/pcbios/0/Config/DmiChassisSerial" "Chassis Serial"
2169VBoxManage setextradata "VM name"
2170 "VBoxInternal/Devices/pcbios/0/Config/DmiChassisAssetTag" "Chassis Tag"</screen>
2171 </listitem>
2172
2173 <listitem>
2174 <para>
2175 DMI processor information (type 4)
2176 </para>
2177
2178<screen>VBoxManage setextradata "VM name"
2179 "VBoxInternal/Devices/pcbios/0/Config/DmiProcManufacturer" "GenuineIntel"
2180VBoxManage setextradata "VM name"
2181 "VBoxInternal/Devices/pcbios/0/Config/DmiProcVersion" "Pentium(R) III"</screen>
2182 </listitem>
2183
2184 <listitem>
2185 <para>
2186 DMI OEM strings (type 11)
2187 </para>
2188
2189<screen>VBoxManage setextradata "VM name"
2190 "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxVer" "vboxVer_1.2.3"
2191VBoxManage setextradata "VM name"
2192 "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxRev" "vboxRev_12345"</screen>
2193 </listitem>
2194
2195 </itemizedlist>
2196
2197 <para>
2198 If a DMI string is not set, the default value of &product-name; is
2199 used. To set an empty string use
2200 <computeroutput>"&lt;EMPTY&gt;"</computeroutput>.
2201 </para>
2202
2203 <para>
2204 Note that in the above list, all quoted parameters (DmiBIOSVendor,
2205 DmiBIOSVersion but not DmiBIOSReleaseMajor) are expected to be
2206 strings. If such a string is a valid number, the parameter is
2207 treated as number and the VM will most probably refuse to start
2208 with an <computeroutput>VERR_CFGM_NOT_STRING</computeroutput>
2209 error. In that case, use
2210 <computeroutput>"string:&lt;value&gt;"</computeroutput>. For
2211 example:
2212 </para>
2213
2214<screen>VBoxManage setextradata "VM name"
2215 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "string:1234"</screen>
2216
2217 <para>
2218 Changing this information can be necessary to provide the DMI
2219 information of the host to the guest to prevent Windows from
2220 asking for a new product key. On Linux hosts, the DMI BIOS
2221 information can be obtained with the following command:
2222 </para>
2223
2224<screen>dmidecode -t0</screen>
2225
2226 <para>
2227 The DMI system information can be obtained as follows:
2228 </para>
2229
2230<screen>dmidecode -t1</screen>
2231
2232 </sect1>
2233
2234 <sect1 id="changeacpicust">
2235
2236 <title>Configuring Custom ACPI Tables</title>
2237
2238 <para>
2239 &product-name; can be configured to present up to four custom ACPI
2240 tables to the guest. A command such as the following can be used
2241 to configure custom ACPI tables. Note that CustomTable1,
2242 CustomTable2, and CustomTable3 are available in addition to
2243 CustomTable0.
2244 </para>
2245
2246<screen>VBoxManage setextradata "VM name"
2247"VBoxInternal/Devices/acpi/0/Config/CustomTable0" "/path/to/table.bin"</screen>
2248
2249 <para>
2250 Configuring custom ACPI tables can for example avoid the need for
2251 asking for a new product key on Windows Vista, Windows 7, Windows
2252 8 and later guests. On Linux hosts, one of the system's ACPI
2253 tables can be read from
2254 <computeroutput>/sys/firmware/acpi/tables/</computeroutput>.
2255 </para>
2256
2257 </sect1>
2258
2259 <sect1 id="fine-tune-timers">
2260
2261 <title>Fine Tuning Timers and Time Synchronization</title>
2262
2263 <sect2 id="changetscmode">
2264
2265 <title>Configuring the Guest Time Stamp Counter (TSC) to Reflect Guest
2266 Execution</title>
2267
2268 <para>
2269 By default, &product-name; keeps all sources of time visible to
2270 the guest synchronized to a single time source, the monotonic
2271 host time. This reflects the assumptions of many guest operating
2272 systems, which expect all time sources to reflect "wall clock"
2273 time. In special circumstances it may be useful however to make
2274 the time stamp counter (TSC) in the guest reflect the time
2275 actually spent executing the guest.
2276 </para>
2277
2278 <para>
2279 This special TSC handling mode can be enabled on a per-VM basis,
2280 and for best results must be used only in combination with
2281 hardware virtualization. To enable this mode use the following
2282 command:
2283 </para>
2284
2285<screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution" 1</screen>
2286
2287 <para>
2288 To revert to the default TSC handling mode use:
2289 </para>
2290
2291<screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution"</screen>
2292
2293 <para>
2294 Note that if you use the special TSC handling mode with a guest
2295 operating system which is very strict about the consistency of
2296 time sources you may get a warning or error message about the
2297 timing inconsistency. It may also cause clocks to become
2298 unreliable with some guest operating systems depending on how
2299 they use the TSC.
2300 </para>
2301
2302 </sect2>
2303
2304 <sect2 id="warpguest">
2305
2306 <title>Accelerate or Slow Down the Guest Clock</title>
2307
2308 <para>
2309 For certain purposes it can be useful to accelerate or to slow
2310 down the virtual guest clock. This can be achieved as follows:
2311 </para>
2312
2313<screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 200</screen>
2314
2315 <para>
2316 The above example will double the speed of the guest clock while
2317 </para>
2318
2319<screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 50</screen>
2320
2321 <para>
2322 will halve the speed of the guest clock. Note that changing the
2323 rate of the virtual clock can confuse the guest and can even
2324 lead to abnormal guest behavior. For instance, a higher clock
2325 rate means shorter timeouts for virtual devices with the result
2326 that a slightly increased response time of a virtual device due
2327 to an increased host load can cause guest failures. Note further
2328 that any time synchronization mechanism will frequently try to
2329 resynchronize the guest clock with the reference clock, which is
2330 the host clock if the &product-name; Guest Additions are active.
2331 Therefore any time synchronization should be disabled if the
2332 rate of the guest clock is changed as described above. See
2333 <xref linkend="changetimesync" />.
2334 </para>
2335
2336 </sect2>
2337
2338 <sect2 id="changetimesync">
2339
2340 <title>Tuning the Guest Additions Time Synchronization Parameters</title>
2341
2342 <para>
2343 The &product-name; Guest Additions ensure that the guest's
2344 system time is synchronized with the host time. There are
2345 several parameters which can be tuned. The parameters can be set
2346 for a specific VM using the following command:
2347 </para>
2348
2349<screen>VBoxManage guestproperty set "VM name" "/VirtualBox/GuestAdd/VBoxService/PARAMETER" VALUE</screen>
2350
2351 <para>
2352 where <computeroutput>PARAMETER</computeroutput> is one of the
2353 following:
2354 </para>
2355
2356 <variablelist>
2357
2358 <varlistentry>
2359 <term>
2360 <computeroutput>--timesync-interval</computeroutput>
2361 </term>
2362
2363 <listitem>
2364 <para>
2365 Specifies the interval at which to synchronize the time
2366 with the host. The default is 10000 ms (10 seconds).
2367 </para>
2368 </listitem>
2369 </varlistentry>
2370
2371 <varlistentry>
2372 <term>
2373 <computeroutput>--timesync-min-adjust</computeroutput>
2374 </term>
2375
2376 <listitem>
2377 <para>
2378 The minimum absolute drift value measured in milliseconds
2379 to make adjustments for. The default is 1000 ms on OS/2
2380 and 100 ms elsewhere.
2381 </para>
2382 </listitem>
2383 </varlistentry>
2384
2385 <varlistentry>
2386 <term>
2387 <computeroutput>--timesync-latency-factor</computeroutput>
2388 </term>
2389
2390 <listitem>
2391 <para>
2392 The factor to multiply the time query latency with to
2393 calculate the dynamic minimum adjust time. The default is
2394 8 times, which means as follows:
2395 </para>
2396
2397 <para>
2398 Measure the time it takes to determine the host time, the
2399 guest has to contact the VM host service which may take
2400 some time. Multiply this value by 8 and do an adjustment
2401 only if the time difference between host and guest is
2402 bigger than this value. Do not do any time adjustment
2403 otherwise.
2404 </para>
2405 </listitem>
2406 </varlistentry>
2407
2408 <varlistentry>
2409 <term>
2410 <computeroutput>--timesync-max-latency</computeroutput>
2411 </term>
2412
2413 <listitem>
2414 <para>
2415 The max host timer query latency to accept. The default is
2416 250 ms.
2417 </para>
2418 </listitem>
2419 </varlistentry>
2420
2421 <varlistentry>
2422 <term>
2423 <computeroutput>--timesync-set-threshold</computeroutput>
2424 </term>
2425
2426 <listitem>
2427 <para>
2428 The absolute drift threshold, given as milliseconds where
2429 to start setting the time instead of trying to smoothly
2430 adjust it. The default is 20 minutes.
2431 </para>
2432 </listitem>
2433 </varlistentry>
2434
2435 <varlistentry>
2436 <term>
2437 <computeroutput>--timesync-set-start</computeroutput>
2438 </term>
2439
2440 <listitem>
2441 <para>
2442 Set the time when starting the time sync service.
2443 </para>
2444 </listitem>
2445 </varlistentry>
2446
2447 <varlistentry>
2448 <term>
2449 <computeroutput>--timesync-set-on-restore
2450 0|1</computeroutput>
2451 </term>
2452
2453 <listitem>
2454 <para>
2455 Set the time after the VM was restored from a saved state
2456 when passing 1 as parameter. This is the default. Disable
2457 by passing 0. In the latter case, the time will be
2458 adjusted smoothly, which can take a long time.
2459 </para>
2460 </listitem>
2461 </varlistentry>
2462
2463 </variablelist>
2464
2465 <para>
2466 All these parameters can be specified as command line parameters
2467 to VBoxService as well.
2468 </para>
2469
2470 </sect2>
2471
2472 <sect2 id="disabletimesync">
2473
2474 <title>Disabling the Guest Additions Time Synchronization</title>
2475
2476 <para>
2477 Once installed and started, the &product-name; Guest Additions
2478 will try to synchronize the guest time with the host time. This
2479 can be prevented by forbidding the guest service from reading
2480 the host clock:
2481 </para>
2482
2483<screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</screen>
2484
2485 </sect2>
2486
2487 </sect1>
2488
2489 <sect1 id="vboxbowsolaris11">
2490
2491 <title>Installing the Alternate Bridged Networking Driver on Oracle Solaris 11
2492 hosts</title>
2493
2494 <para>
2495 &product-name; includes a network filter driver that utilizes
2496 Oracle Solaris 11's Crossbow functionality. By default, this new
2497 driver is installed for Oracle Solaris 11 hosts, builds 159 and
2498 above, that have support for it.
2499 </para>
2500
2501 <para>
2502 To force installation of the older STREAMS based network filter
2503 driver, execute as root the following command before installing
2504 the &product-name; package:
2505 </para>
2506
2507<screen>touch /etc/vboxinst_vboxflt</screen>
2508
2509 <para>
2510 To force installation of the Crossbow based network filter driver,
2511 execute as root the following command before installing the
2512 &product-name; package:
2513 </para>
2514
2515<screen>touch /etc/vboxinst_vboxbow</screen>
2516
2517 <para>
2518 To check which driver is currently being used by &product-name;,
2519 execute:
2520 </para>
2521
2522<screen>modinfo | grep vbox</screen>
2523
2524 <para>
2525 If the output contains "vboxbow", it indicates &product-name; is
2526 using the Crossbow network filter driver, while the name "vboxflt"
2527 indicates usage of the older STREAMS network filter.
2528 </para>
2529
2530 </sect1>
2531
2532 <sect1 id="vboxbowvnictemplates">
2533
2534 <title>&product-name; VNIC Templates for VLANs on Oracle Solaris 11 Hosts</title>
2535
2536 <para>
2537 &product-name; supports Virtual Network Interface (VNIC) templates
2538 for configuring VMs over VLANs. An &product-name; VNIC template is
2539 a VNIC whose name starts with
2540 <computeroutput>vboxvnic_template</computeroutput>. The string is
2541 case-sensitive.
2542 </para>
2543
2544 <para>
2545 On Oracle Solaris 11 hosts, when Crossbow-based bridged networking
2546 is used, a VNIC template may be used to specify the VLAN ID to use
2547 while bridging over a network link.
2548 </para>
2549
2550 <para>
2551 The following is an example of how to use a VNIC template to
2552 configure a VM over a VLAN. Create an &product-name; VNIC
2553 template, by executing as root:
2554 </para>
2555
2556<screen>dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0</screen>
2557
2558 <para>
2559 This will create a temporary VNIC template over interface "nge0"
2560 with the VLAN ID 23. To create VNIC templates that are persistent
2561 across host reboots, skip the <computeroutput>-t</computeroutput>
2562 parameter in the above command. You may check the current state of
2563 links using the following command:
2564 </para>
2565
2566<screen>$ dladm show-link
2567LINK CLASS MTU STATE BRIDGE OVER
2568nge0 phys 1500 up -- --
2569nge1 phys 1500 down -- --
2570vboxvnic_template0 vnic 1500 up -- nge0
2571
2572$ dladm show-vnic
2573LINK OVER SPEED MACADDRESS MACADDRTYPE VID
2574vboxvnic_template0 nge0 1000 2:8:20:25:12:75 random 23</screen>
2575
2576 <para>
2577 Once the VNIC template is created, any VMs that need to be on VLAN
2578 23 over the interface <computeroutput>nge0</computeroutput> can be
2579 configured to bridge using this VNIC template.
2580 </para>
2581
2582 <para>
2583 VNIC templates makes managing VMs on VLANs simpler and efficient.
2584 The VLAN details are not stored as part of every VM's
2585 configuration but rather inherited from the VNIC template while
2586 starting the VM. The VNIC template itself can be modified anytime
2587 using the <command>dladm</command> command.
2588 </para>
2589
2590 <para>
2591 VNIC templates can be created with additional properties such as
2592 bandwidth limits, CPU fanout etc. Refer to your Oracle Solaris
2593 network documentation on how to accomplish this. These additional
2594 properties, if any, are also applied to VMs which bridge using the
2595 VNIC template.
2596 </para>
2597
2598 </sect1>
2599
2600 <sect1 id="addhostonlysolaris">
2601
2602 <title>Configuring Multiple Host-Only Network Interfaces on Oracle Solaris
2603 Hosts</title>
2604
2605 <para>
2606 By default &product-name; provides you with one host-only network
2607 interface. Adding more host-only network interfaces on Oracle
2608 Solaris hosts requires manual configuration. Here is how to add
2609 another host-only network interface.
2610 </para>
2611
2612 <para>
2613 Begin by stopping all running VMs. Then, unplumb the existing
2614 "vboxnet0" interface by execute the following command as root:
2615 </para>
2616
2617<screen>ifconfig vboxnet0 unplumb</screen>
2618
2619 <para>
2620 If you have several vboxnet interfaces, you will need to unplumb
2621 all of them. Once all vboxnet interfaces are unplumbed, remove the
2622 driver by executing the following command as root:
2623 </para>
2624
2625<screen>rem_drv vboxnet</screen>
2626
2627 <para>
2628 Edit the file
2629 <computeroutput>/platform/i86pc/kernel/drv/vboxnet.conf</computeroutput>
2630 and add a line for the new interface we want to add as shown
2631 below:
2632 </para>
2633
2634<screen>name="vboxnet" parent="pseudo" instance=1;
2635name="vboxnet" parent="pseudo" instance=2;</screen>
2636
2637 <para>
2638 Add as many of these lines as required with each line having a
2639 unique instance number.
2640 </para>
2641
2642 <para>
2643 Next, reload the vboxnet driver by executing the following command
2644 as root:
2645 </para>
2646
2647<screen>add_drv vboxnet</screen>
2648
2649 <para>
2650 On Oracle Solaris 11.1 and newer hosts you may want to rename the
2651 default vanity interface name. To check what name has been
2652 assigned, execute:
2653 </para>
2654
2655<screen>dladm show-phys
2656LINK MEDIA STATE SPEED DUPLEX DEVICE
2657net0 Ethernet up 100 full e1000g0
2658net2 Ethernet up 1000 full vboxnet1
2659net1 Ethernet up 1000 full vboxnet0</screen>
2660
2661 <para>
2662 In the above example, we can rename "net2" to "vboxnet1" before
2663 proceeding to plumb the interface. This can be done by executing
2664 as root:
2665 </para>
2666
2667<screen>dladm rename-link net2 vboxnet1</screen>
2668
2669 <para>
2670 Now plumb all the interfaces using <computeroutput>ifconfig
2671 vboxnetX plumb</computeroutput>, where 'X' would be 1 in this
2672 case. Once the interface is plumbed, it may be configured like any
2673 other network interface. Refer to the
2674 <computeroutput>ifconfig</computeroutput> documentation for
2675 further details.
2676 </para>
2677
2678 <para>
2679 To make the settings for the newly added interfaces persistent
2680 across reboots, you will need to edit the files
2681 <computeroutput>/etc/inet/netmasks</computeroutput>, and if you
2682 are using NWAM <computeroutput>/etc/nwam/llp</computeroutput> and
2683 add the appropriate entries to set the netmask and static IP for
2684 each of those interfaces. The &product-name; installer only
2685 updates these configuration files for the one "vboxnet0" interface
2686 it creates by default.
2687 </para>
2688
2689 </sect1>
2690
2691 <sect1 id="solariscodedumper">
2692
2693 <title>Configuring the &product-name; CoreDumper on Oracle Solaris Hosts</title>
2694
2695 <para>
2696 &product-name; is capable of producing its own core files for
2697 extensive debugging when things go wrong. Currently this is only
2698 available on Oracle Solaris hosts.
2699 </para>
2700
2701 <para>
2702 The &product-name; CoreDumper can be enabled using the following
2703 command:
2704 </para>
2705
2706<screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpEnabled 1</screen>
2707
2708 <para>
2709 You can specify which directory to use for core dumps with this
2710 command, as follows:
2711 </para>
2712
2713<screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir &lt;path-to-directory&gt;</screen>
2714
2715 <para>
2716 Make sure the directory you specify is on a volume with sufficient
2717 free space and that the &product-name; process has sufficient
2718 permissions to write files to this directory. If you skip this
2719 command and do not specify any core dump directory, the current
2720 directory of the &product-name; executable will be used. This
2721 would most likely fail when writing cores as they are protected
2722 with root permissions. It is recommended you explicitly set a core
2723 dump directory.
2724 </para>
2725
2726 <para>
2727 You must specify when the &product-name; CoreDumper should be
2728 triggered. This is done using the following commands:
2729 </para>
2730
2731<screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpReplaceSystemDump 1
2732VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpLive 1</screen>
2733
2734 <para>
2735 At least one of the above two commands will have to be provided if
2736 you have enabled the &product-name; CoreDumper.
2737 </para>
2738
2739 <para>
2740 Setting <computeroutput>CoreDumpReplaceSystemDump</computeroutput>
2741 sets up the VM to override the host's core dumping mechanism and
2742 in the event of any crash only the &product-name; CoreDumper would
2743 produce the core file.
2744 </para>
2745
2746 <para>
2747 Setting <computeroutput>CoreDumpLive</computeroutput> sets up the
2748 VM to produce cores whenever the VM process receives a
2749 <computeroutput>SIGUSR2</computeroutput> signal. After producing
2750 the core file, the VM will not be terminated and will continue to
2751 run. You can thus take cores of the VM process using the following
2752 command:
2753 </para>
2754
2755<screen>kill -s SIGUSR2 &lt;VM-process-id&gt;</screen>
2756
2757 <para>
2758 Core files produced by the &product-name; CoreDumper are of the
2759 form
2760 <computeroutput>core.vb.&lt;ProcessName&gt;.&lt;ProcessID&gt;</computeroutput>,
2761 for example
2762 <computeroutput>core.vb.VBoxHeadless.11321</computeroutput>.
2763 </para>
2764
2765 </sect1>
2766
2767 <sect1 id="vboxandsolzvmm">
2768
2769 <title>&product-name; and Oracle Solaris Kernel Zones</title>
2770
2771 <para>
2772 Oracle Solaris kernel zones on x86-based systems make use of
2773 hardware-assisted virtualization features like &product-name;
2774 does. However, for kernel zones and &product-name; to share this
2775 hardware resource, they need to cooperate.
2776 </para>
2777
2778 <para>
2779 By default, due to performance reasons, &product-name; acquires
2780 the hardware-assisted virtualization resource (VT-x/AMD-V)
2781 globally on the host machine and uses it until the last
2782 &product-name; VM that requires it is powered off. This prevents
2783 other software from using VT-x/AMD-V during the time
2784 &product-name; has taken control of it.
2785 </para>
2786
2787 <para>
2788 &product-name; can be instructed to relinquish use of
2789 hardware-assisted virtualization features when not executing guest
2790 code, thereby allowing kernel zones to make use of them. To do
2791 this, shutdown all &product-name; VMs and execute the following
2792 command:
2793 </para>
2794
2795<screen>VBoxManage setproperty hwvirtexclusive off</screen>
2796
2797 <para>
2798 This command needs to be executed only once as the setting is
2799 stored as part of the global &product-name; settings which will
2800 continue to persist across host-reboots and &product-name;
2801 upgrades.
2802 </para>
2803
2804 </sect1>
2805
2806 <sect1 id="guitweaks">
2807
2808 <title>Locking Down the &product-name; GUI</title>
2809
2810 <sect2 id="customize-vm-manager">
2811
2812 <title>Customizing the VirtualBox Manager</title>
2813
2814 <para>
2815 There are several advanced customization settings for locking
2816 down the VirtualBox Manager. Locking down means removing some
2817 features that the user should not see.
2818 </para>
2819
2820<screen>VBoxManage setextradata global GUI/Customizations OPTION[,OPTION...]</screen>
2821
2822 <para>
2823 where <computeroutput>OPTION</computeroutput> is one of the
2824 following keywords:
2825 </para>
2826
2827 <variablelist>
2828
2829 <varlistentry>
2830 <term>
2831 <computeroutput>noSelector</computeroutput>
2832 </term>
2833
2834 <listitem>
2835 <para>
2836 Do not allow users to start the VirtualBox Manager. Trying
2837 to do so will show a window containing a proper error
2838 message.
2839 </para>
2840 </listitem>
2841 </varlistentry>
2842
2843 <varlistentry>
2844 <term>
2845 <computeroutput>noMenuBar</computeroutput>
2846 </term>
2847
2848 <listitem>
2849 <para>
2850 VM windows will not contain a menu bar.
2851 </para>
2852 </listitem>
2853 </varlistentry>
2854
2855 <varlistentry>
2856 <term>
2857 <computeroutput>noStatusBar</computeroutput>
2858 </term>
2859
2860 <listitem>
2861 <para>
2862 VM windows will not contain a status bar.
2863 </para>
2864 </listitem>
2865 </varlistentry>
2866
2867 </variablelist>
2868
2869 <para>
2870 To disable any of these VirtualBox Manager customizations use
2871 the following command:
2872 </para>
2873
2874<screen>VBoxManage setextradata global GUI/Customizations</screen>
2875
2876 </sect2>
2877
2878 <sect2 id="customize-vm-selector">
2879
2880 <title>VM Selector Customization</title>
2881
2882 <para>
2883 The following per-machine VM extradata settings can be used to
2884 change the behavior of the VM selector window in respect of
2885 certain VMs:
2886 </para>
2887
2888<screen>VBoxManage setextradata "VM name" SETTING true</screen>
2889
2890 <para>
2891 where <computeroutput>SETTING</computeroutput> can be:
2892 </para>
2893
2894 <variablelist>
2895
2896 <varlistentry>
2897 <term>
2898 <computeroutput>GUI/HideDetails</computeroutput>
2899 </term>
2900
2901 <listitem>
2902 <para>
2903 Do not show the VM configuration of a certain VM. The
2904 details window will remain just empty if this VM is
2905 selected.
2906 </para>
2907 </listitem>
2908 </varlistentry>
2909
2910 <varlistentry>
2911 <term>
2912 <computeroutput>GUI/PreventReconfiguration</computeroutput>
2913 </term>
2914
2915 <listitem>
2916 <para>
2917 Do not allow the user to open the
2918 <emphasis role="bold">Settings</emphasis> dialog for a
2919 certain VM.
2920 </para>
2921 </listitem>
2922 </varlistentry>
2923
2924 <varlistentry>
2925 <term>
2926 <computeroutput>GUI/PreventSnapshotOperations</computeroutput>
2927 </term>
2928
2929 <listitem>
2930 <para>
2931 Prevent snapshot operations for a VM from the GUI, either
2932 at runtime or when the VM is powered off.
2933 </para>
2934 </listitem>
2935 </varlistentry>
2936
2937 <varlistentry>
2938 <term>
2939 <computeroutput>GUI/HideFromManager</computeroutput>
2940 </term>
2941
2942 <listitem>
2943 <para>
2944 Hide a certain VM in the VM selector window.
2945 </para>
2946 </listitem>
2947 </varlistentry>
2948
2949 <varlistentry>
2950 <term>
2951 <computeroutput>GUI/PreventApplicationUpdate</computeroutput>
2952 </term>
2953
2954 <listitem>
2955 <para>
2956 Disable the automatic update check and hide the
2957 corresponding menu item.
2958 </para>
2959 </listitem>
2960 </varlistentry>
2961
2962 </variablelist>
2963
2964 <para>
2965 Please note that these settings would not prevent the user from
2966 reconfiguring the VM by using <command>VBoxManage
2967 modifyvm</command>.
2968 </para>
2969
2970 </sect2>
2971
2972 <sect2 id="config-vm-selector-menu">
2973
2974 <title>Configure VM Selector Menu Entries</title>
2975
2976 <para>
2977 You can disable, or blacklist, certain entries in the global
2978 settings page of the VM selector:
2979 </para>
2980
2981<screen>VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages OPTION[,OPTION...]</screen>
2982
2983 <para>
2984 where <computeroutput>OPTION</computeroutput> is one of the
2985 following keywords:
2986 </para>
2987
2988 <variablelist>
2989
2990 <varlistentry>
2991 <term>
2992 <computeroutput>General</computeroutput>
2993 </term>
2994
2995 <listitem>
2996 <para>
2997 Do not show the <emphasis role="bold">General</emphasis>
2998 settings pane.
2999 </para>
3000 </listitem>
3001 </varlistentry>
3002
3003 <varlistentry>
3004 <term>
3005 <computeroutput>Input</computeroutput>
3006 </term>
3007
3008 <listitem>
3009 <para>
3010 Do not show the <emphasis role="bold">Input</emphasis>
3011 settings pane.
3012 </para>
3013 </listitem>
3014 </varlistentry>
3015
3016 <varlistentry>
3017 <term>
3018 <computeroutput>Update</computeroutput>
3019 </term>
3020
3021 <listitem>
3022 <para>
3023 Do not show the <emphasis role="bold">Update</emphasis>
3024 settings pane.
3025 </para>
3026 </listitem>
3027 </varlistentry>
3028
3029 <varlistentry>
3030 <term>
3031 <computeroutput>Language</computeroutput>
3032 </term>
3033
3034 <listitem>
3035 <para>
3036 Do not show the <emphasis role="bold">Language</emphasis>
3037 settings pane.
3038 </para>
3039 </listitem>
3040 </varlistentry>
3041
3042 <varlistentry>
3043 <term>
3044 <computeroutput>Display</computeroutput>
3045 </term>
3046
3047 <listitem>
3048 <para>
3049 Do not show the <emphasis role="bold">Display</emphasis>
3050 settings pane.
3051 </para>
3052 </listitem>
3053 </varlistentry>
3054
3055 <varlistentry>
3056 <term>
3057 <computeroutput>Network</computeroutput>
3058 </term>
3059
3060 <listitem>
3061 <para>
3062 Do not show the <emphasis role="bold">Network</emphasis>
3063 settings pane.
3064 </para>
3065 </listitem>
3066 </varlistentry>
3067
3068 <varlistentry>
3069 <term>
3070 <computeroutput>Extensions</computeroutput>
3071 </term>
3072
3073 <listitem>
3074 <para>
3075 Do not show the
3076 <emphasis role="bold">Extensions</emphasis> settings pane.
3077 </para>
3078 </listitem>
3079 </varlistentry>
3080
3081 <varlistentry>
3082 <term>
3083 <computeroutput>Proxy</computeroutput>
3084 </term>
3085
3086 <listitem>
3087 <para>
3088 Do not show the <emphasis role="bold">Proxy</emphasis>
3089 settings pane.
3090 </para>
3091 </listitem>
3092 </varlistentry>
3093
3094 </variablelist>
3095
3096 <para>
3097 This is a global setting. Any combination of the above is
3098 allowed. To restore the default behavior, use
3099 </para>
3100
3101<screen>VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages</screen>
3102
3103 </sect2>
3104
3105 <sect2 id="config-vm-window-menu">
3106
3107 <title>Configure VM Window Menu Entries</title>
3108
3109 <para>
3110 You can disable, or blacklist, certain menu actions in the VM
3111 window:
3112 </para>
3113
3114<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus OPTION[,OPTION...]</screen>
3115
3116 <para>
3117 where <computeroutput>OPTION</computeroutput> is one of the
3118 following keywords:
3119 </para>
3120
3121 <variablelist>
3122
3123 <varlistentry>
3124 <term>
3125 <computeroutput>All</computeroutput>
3126 </term>
3127
3128 <listitem>
3129 <para>
3130 Do not show any menu in the VM window.
3131 </para>
3132 </listitem>
3133 </varlistentry>
3134
3135 <varlistentry>
3136 <term>
3137 <computeroutput>Machine</computeroutput>
3138 </term>
3139
3140 <listitem>
3141 <para>
3142 Do not show the <emphasis role="bold">Machine</emphasis>
3143 menu in the VM window.
3144 </para>
3145 </listitem>
3146 </varlistentry>
3147
3148 <varlistentry>
3149 <term>
3150 <computeroutput>View</computeroutput>
3151 </term>
3152
3153 <listitem>
3154 <para>
3155 Do not show the <emphasis role="bold">View</emphasis> menu
3156 in the VM window.
3157 </para>
3158 </listitem>
3159 </varlistentry>
3160
3161 <varlistentry>
3162 <term>
3163 <computeroutput>Devices</computeroutput>
3164 </term>
3165
3166 <listitem>
3167 <para>
3168 Do not show the <emphasis role="bold">Devices</emphasis>
3169 menu in the VM window.
3170 </para>
3171 </listitem>
3172 </varlistentry>
3173
3174 <varlistentry>
3175 <term>
3176 <computeroutput>Help</computeroutput>
3177 </term>
3178
3179 <listitem>
3180 <para>
3181 Do not show the <emphasis role="bold">Help</emphasis> menu
3182 in the VM window.
3183 </para>
3184 </listitem>
3185 </varlistentry>
3186
3187 <varlistentry>
3188 <term>
3189 <computeroutput>Debug</computeroutput>
3190 </term>
3191
3192 <listitem>
3193 <para>
3194 Do not show the <emphasis role="bold">Debug</emphasis>
3195 menu in the VM window. The Debug menu is only visible if
3196 the GUI was started with special command line parameters
3197 or environment variable settings.
3198 </para>
3199 </listitem>
3200 </varlistentry>
3201
3202 </variablelist>
3203
3204 <para>
3205 This is a per-VM setting. Any combination of the above is
3206 allowed. To restore the default behavior, use
3207 </para>
3208
3209<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus</screen>
3210
3211 <para>
3212 You can also disable, or blacklist, certain menu actions of
3213 certain menus. Use the following command to disable certain
3214 actions of the <emphasis role="bold">Application</emphasis>
3215 menu. This is only available on Mac OS X hosts.
3216 </para>
3217
3218<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen>
3219
3220 <para>
3221 where <computeroutput>OPTION</computeroutput> is one of the
3222 following keywords:
3223 </para>
3224
3225 <variablelist>
3226
3227 <varlistentry>
3228 <term>
3229 <computeroutput>All</computeroutput>
3230 </term>
3231
3232 <listitem>
3233 <para>
3234 Do not show any menu item in this menu.
3235 </para>
3236 </listitem>
3237 </varlistentry>
3238
3239 <varlistentry>
3240 <term>
3241 <computeroutput>About</computeroutput>
3242 </term>
3243
3244 <listitem>
3245 <para>
3246 Do not show the <emphasis role="bold">About</emphasis>
3247 menu item in this menu.
3248 </para>
3249 </listitem>
3250 </varlistentry>
3251
3252 </variablelist>
3253
3254 <para>
3255 This is a per-VM setting. Any combination of the above is
3256 allowed. To restore the default behavior, use
3257 </para>
3258
3259<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus</screen>
3260
3261 <para>
3262 Use the following command to disable certain actions of the
3263 <emphasis role="bold">Machine</emphasis> menu:
3264 </para>
3265
3266<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen>
3267
3268 <para>
3269 where <computeroutput>OPTION</computeroutput> is one of the
3270 following keywords:
3271 </para>
3272
3273 <variablelist>
3274
3275 <varlistentry>
3276 <term>
3277 <computeroutput>All</computeroutput>
3278 </term>
3279
3280 <listitem>
3281 <para>
3282 Do not show any menu item in this menu.
3283 </para>
3284 </listitem>
3285 </varlistentry>
3286
3287 <varlistentry>
3288 <term>
3289 <computeroutput>SettingsDialog</computeroutput>
3290 </term>
3291
3292 <listitem>
3293 <para>
3294 Do not show the <emphasis role="bold">Settings</emphasis>
3295 menu item in this menu.
3296 </para>
3297 </listitem>
3298 </varlistentry>
3299
3300 <varlistentry>
3301 <term>
3302 <computeroutput>TakeSnapshot</computeroutput>
3303 </term>
3304
3305 <listitem>
3306 <para>
3307 Do not show the <emphasis role="bold">Take
3308 Snapshot</emphasis> menu item in this menu.
3309 </para>
3310 </listitem>
3311 </varlistentry>
3312
3313 <varlistentry>
3314 <term>
3315 <computeroutput>TakeScreenshot</computeroutput>
3316 </term>
3317
3318 <listitem>
3319 <para>
3320 Do not show the <emphasis role="bold">Take
3321 Screenshot</emphasis> menu item in this menu.
3322 </para>
3323 </listitem>
3324 </varlistentry>
3325
3326 <varlistentry>
3327 <term>
3328 <computeroutput>InformationDialog</computeroutput>
3329 </term>
3330
3331 <listitem>
3332 <para>
3333 Do not show the <emphasis role="bold">Session
3334 Information</emphasis> menu item in this menu.
3335 </para>
3336 </listitem>
3337 </varlistentry>
3338
3339 <varlistentry>
3340 <term>
3341 <computeroutput>MouseIntegration</computeroutput>
3342 </term>
3343
3344 <listitem>
3345 <para>
3346 Do not show the <emphasis role="bold">Disable Mouse
3347 Integration</emphasis> menu item in this menu.
3348 </para>
3349 </listitem>
3350 </varlistentry>
3351
3352 <varlistentry>
3353 <term>
3354 <computeroutput>TypeCAD</computeroutput>
3355 </term>
3356
3357 <listitem>
3358 <para>
3359 Do not show the <emphasis role="bold">Insert
3360 Ctrl+Alt+Del</emphasis> menu item in this menu.
3361 </para>
3362 </listitem>
3363 </varlistentry>
3364
3365 <varlistentry>
3366 <term>
3367 <computeroutput>TypeCABS</computeroutput>
3368 </term>
3369
3370 <listitem>
3371 <para>
3372 Do not show the <emphasis role="bold">Insert
3373 Ctrl+Alt+Backspace</emphasis> menu item in this menu.
3374 Available on X11 hosts only.
3375 </para>
3376 </listitem>
3377 </varlistentry>
3378
3379 <varlistentry>
3380 <term>
3381 <computeroutput>Pause</computeroutput>
3382 </term>
3383
3384 <listitem>
3385 <para>
3386 Do not show the <emphasis role="bold">Pause</emphasis>
3387 menu item in this menu.
3388 </para>
3389 </listitem>
3390 </varlistentry>
3391
3392 <varlistentry>
3393 <term>
3394 <computeroutput>Reset</computeroutput>
3395 </term>
3396
3397 <listitem>
3398 <para>
3399 Do not show the <emphasis role="bold">Reset</emphasis>
3400 menu item in this menu.
3401 </para>
3402 </listitem>
3403 </varlistentry>
3404
3405 <varlistentry>
3406 <term>
3407 <computeroutput>SaveState</computeroutput>
3408 </term>
3409
3410 <listitem>
3411 <para>
3412 Do not show the <emphasis role="bold">Save the machine
3413 state</emphasis> menu item in this menu.
3414 </para>
3415 </listitem>
3416 </varlistentry>
3417
3418 <varlistentry>
3419 <term>
3420 <computeroutput>Shutdown</computeroutput>
3421 </term>
3422
3423 <listitem>
3424 <para>
3425 Do not show the <emphasis role="bold">ACPI
3426 Shutdown</emphasis> menu item in this menu.
3427 </para>
3428 </listitem>
3429 </varlistentry>
3430
3431 <varlistentry>
3432 <term>
3433 <computeroutput>PowerOff</computeroutput>
3434 </term>
3435
3436 <listitem>
3437 <para>
3438 Do not show the <emphasis role="bold">Power Off the
3439 machine</emphasis> menu item in this menu.
3440 </para>
3441 </listitem>
3442 </varlistentry>
3443
3444 </variablelist>
3445
3446 <para>
3447 This is a per-VM setting. Any combination of the above is
3448 allowed. To restore the default behavior, use
3449 </para>
3450
3451<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions</screen>
3452
3453 <para>
3454 Use the following command to disable certain actions of the
3455 <emphasis role="bold">View</emphasis> menu:
3456 </para>
3457
3458<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeViewMenuActions OPTION[,OPTION...]</screen>
3459
3460 <para>
3461 where <computeroutput>OPTION</computeroutput> is one of the
3462 following keywords:
3463 </para>
3464
3465 <variablelist>
3466
3467 <varlistentry>
3468 <term>
3469 <computeroutput>All</computeroutput>
3470 </term>
3471
3472 <listitem>
3473 <para>
3474 Do not show any menu item in this menu.
3475 </para>
3476 </listitem>
3477 </varlistentry>
3478
3479 <varlistentry>
3480 <term>
3481 <computeroutput>Fullscreen</computeroutput>
3482 </term>
3483
3484 <listitem>
3485 <para>
3486 Do not show the <emphasis role="bold">Switch to
3487 Fullscreen</emphasis> menu item in this menu.
3488 </para>
3489 </listitem>
3490 </varlistentry>
3491
3492 <varlistentry>
3493 <term>
3494 <computeroutput>Seamless</computeroutput>
3495 </term>
3496
3497 <listitem>
3498 <para>
3499 Do not show the <emphasis role="bold">Switch to Seamless
3500 Mode</emphasis> menu item in this menu.
3501 </para>
3502 </listitem>
3503 </varlistentry>
3504
3505 <varlistentry>
3506 <term>
3507 <computeroutput>Scale</computeroutput>
3508 </term>
3509
3510 <listitem>
3511 <para>
3512 Do not show the <emphasis role="bold">Switch to Scaled
3513 Mode</emphasis> menu item in this menu.
3514 </para>
3515 </listitem>
3516 </varlistentry>
3517
3518 <varlistentry>
3519 <term>
3520 <computeroutput>GuestAutoresize</computeroutput>
3521 </term>
3522
3523 <listitem>
3524 <para>
3525 Do not show the <emphasis role="bold">Auto-resize Guest
3526 Display</emphasis> menu item in this menu.
3527 </para>
3528 </listitem>
3529 </varlistentry>
3530
3531 <varlistentry>
3532 <term>
3533 <computeroutput>AdjustWindow</computeroutput>
3534 </term>
3535
3536 <listitem>
3537 <para>
3538 Do not show the <emphasis role="bold">Adjust Window
3539 Size</emphasis> menu item in this menu.
3540 </para>
3541 </listitem>
3542 </varlistentry>
3543
3544 <varlistentry>
3545 <term>
3546 <computeroutput>Multiscreen</computeroutput>
3547 </term>
3548
3549 <listitem>
3550 <para>
3551 Do not show the
3552 <emphasis role="bold">Multiscreen</emphasis> menu item in
3553 this menu. Only visible in full screen/seamless mode.
3554 </para>
3555 </listitem>
3556 </varlistentry>
3557
3558 </variablelist>
3559
3560 <para>
3561 This is a per-VM setting. Any combination of the above is
3562 allowed. To restore the default behavior, use
3563 </para>
3564
3565<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeViewMenuActions</screen>
3566
3567 <para>
3568 Use the following command to disable certain actions of the
3569 <emphasis role="bold">View</emphasis> menu:
3570 </para>
3571
3572<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDevicesMenuActions OPTION[,OPTION...]</screen>
3573
3574 <para>
3575 where <computeroutput>OPTION</computeroutput> is one of the
3576 following keywords to disable actions in the
3577 <emphasis role="bold">Devices</emphasis> menu:
3578 </para>
3579
3580 <variablelist>
3581
3582 <varlistentry>
3583 <term>
3584 <computeroutput>All</computeroutput>
3585 </term>
3586
3587 <listitem>
3588 <para>
3589 Do not show any menu item in this menu.
3590 </para>
3591 </listitem>
3592 </varlistentry>
3593
3594 <varlistentry>
3595 <term>
3596 <computeroutput>OpticalDevices</computeroutput>
3597 </term>
3598
3599 <listitem>
3600 <para>
3601 Do not show the <emphasis role="bold">CD/DVD
3602 Devices</emphasis> menu item in this menu.
3603 </para>
3604 </listitem>
3605 </varlistentry>
3606
3607 <varlistentry>
3608 <term>
3609 <computeroutput>FloppyDevices</computeroutput>
3610 </term>
3611
3612 <listitem>
3613 <para>
3614 Do not show the <emphasis role="bold">Floppy
3615 Devices</emphasis> menu item in this menu.
3616 </para>
3617 </listitem>
3618 </varlistentry>
3619
3620 <varlistentry>
3621 <term>
3622 <computeroutput>USBDevices</computeroutput>
3623 </term>
3624
3625 <listitem>
3626 <para>
3627 Do not show the <emphasis role="bold">USB
3628 Devices</emphasis> menu item in this menu.
3629 </para>
3630 </listitem>
3631 </varlistentry>
3632
3633 <varlistentry>
3634 <term>
3635 <computeroutput>SharedClipboard</computeroutput>
3636 </term>
3637
3638 <listitem>
3639 <para>
3640 Do not show the <emphasis role="bold">Shared
3641 Clipboard</emphasis> menu item in this menu.
3642 </para>
3643 </listitem>
3644 </varlistentry>
3645
3646 <varlistentry>
3647 <term>
3648 <computeroutput>DragAndDrop</computeroutput>
3649 </term>
3650
3651 <listitem>
3652 <para>
3653 Do not show the <emphasis role="bold">Drag and
3654 Drop</emphasis> menu item in this menu.
3655 </para>
3656 </listitem>
3657 </varlistentry>
3658
3659 <varlistentry>
3660 <term>
3661 <computeroutput>NetworkSettings</computeroutput>
3662 </term>
3663
3664 <listitem>
3665 <para>
3666 Do not show the <emphasis role="bold">Network
3667 Settings...</emphasis> menu item in this menu.
3668 </para>
3669 </listitem>
3670 </varlistentry>
3671
3672 <varlistentry>
3673 <term>
3674 <computeroutput>SharedFoldersSettings</computeroutput>
3675 </term>
3676
3677 <listitem>
3678 <para>
3679 Do not show the <emphasis role="bold">Shared Folders
3680 Settings...</emphasis> menu item in this menu.
3681 </para>
3682 </listitem>
3683 </varlistentry>
3684
3685 <varlistentry>
3686 <term>
3687 <computeroutput>VRDEServer</computeroutput>
3688 </term>
3689
3690 <listitem>
3691 <para>
3692 Do not show the <emphasis role="bold">Remove
3693 Display</emphasis> menu item in this menu.
3694 </para>
3695 </listitem>
3696 </varlistentry>
3697
3698 <varlistentry>
3699 <term>
3700 <computeroutput>InstallGuestTools</computeroutput>
3701 </term>
3702
3703 <listitem>
3704 <para>
3705 Do not show the <emphasis role="bold">Insert Guest
3706 Additions CD image...</emphasis> menu item in this menu.
3707 </para>
3708 </listitem>
3709 </varlistentry>
3710
3711 </variablelist>
3712
3713 <para>
3714 This is a per-VM setting. Any combination of the above is
3715 allowed. To restore the default behavior, use
3716 </para>
3717
3718<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDevicesMenuActions</screen>
3719
3720 <para>
3721 Use the following command to disable certain actions of the
3722 <emphasis role="bold">View</emphasis> menu:
3723 </para>
3724
3725<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDebuggerMenuActions OPTION[,OPTION...]</screen>
3726
3727 <para>
3728 where <computeroutput>OPTION</computeroutput> is one of the
3729 following keywords to disable actions in the
3730 <emphasis>Debug</emphasis> menu, which is normally completely
3731 disabled:
3732 </para>
3733
3734 <variablelist>
3735
3736 <varlistentry>
3737 <term>
3738 <computeroutput>All</computeroutput>
3739 </term>
3740
3741 <listitem>
3742 <para>
3743 Do not show any menu item in this menu.
3744 </para>
3745 </listitem>
3746 </varlistentry>
3747
3748 <varlistentry>
3749 <term>
3750 <computeroutput>Statistics</computeroutput>
3751 </term>
3752
3753 <listitem>
3754 <para>
3755 Do not show the
3756 <emphasis role="bold">Statistics...</emphasis> menu item
3757 in this menu.
3758 </para>
3759 </listitem>
3760 </varlistentry>
3761
3762 <varlistentry>
3763 <term>
3764 <computeroutput>CommandLine</computeroutput>
3765 </term>
3766
3767 <listitem>
3768 <para>
3769 Do not show the <emphasis role="bold">Command
3770 Line...</emphasis> menu item in this menu.
3771 </para>
3772 </listitem>
3773 </varlistentry>
3774
3775 <varlistentry>
3776 <term>
3777 <computeroutput>Logging</computeroutput>
3778 </term>
3779
3780 <listitem>
3781 <para>
3782 Do not show the
3783 <emphasis role="bold">Logging...</emphasis> menu item in
3784 this menu.
3785 </para>
3786 </listitem>
3787 </varlistentry>
3788
3789 <varlistentry>
3790 <term>
3791 <computeroutput>LogDialog</computeroutput>
3792 </term>
3793
3794 <listitem>
3795 <para>
3796 Do not show the <emphasis role="bold">Show
3797 Log...</emphasis> menu item in this menu.
3798 </para>
3799 </listitem>
3800 </varlistentry>
3801
3802 </variablelist>
3803
3804 <para>
3805 This is a per-VM setting. Any combination of the above is
3806 allowed. To restore the default behavior, use
3807 </para>
3808
3809<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDebuggerMenuActions</screen>
3810
3811 <para>
3812 Use the following command to disable certain actions of the
3813 <emphasis role="bold">View</emphasis> menu:
3814 </para>
3815
3816<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeHelpMenuActions OPTION[,OPTION...]</screen>
3817
3818 <para>
3819 where <computeroutput>OPTION</computeroutput> is one of the
3820 following keywords to disable actions in the
3821 <emphasis role="bold">Help</emphasis> menu, which is normally
3822 completely disabled:
3823 </para>
3824
3825 <variablelist>
3826
3827 <varlistentry>
3828 <term>
3829 <computeroutput>All</computeroutput>
3830 </term>
3831
3832 <listitem>
3833 <para>
3834 Do not show any menu item in this menu.
3835 </para>
3836 </listitem>
3837 </varlistentry>
3838
3839 <varlistentry>
3840 <term>
3841 <computeroutput>Contents</computeroutput>
3842 </term>
3843
3844 <listitem>
3845 <para>
3846 Do not show the
3847 <emphasis role="bold">Contents...</emphasis> menu item in
3848 this menu.
3849 </para>
3850 </listitem>
3851 </varlistentry>
3852
3853 <varlistentry>
3854 <term>
3855 <computeroutput>WebSite</computeroutput>
3856 </term>
3857
3858 <listitem>
3859 <para>
3860 Do not show the <emphasis role="bold">VirtualBox Web
3861 Site...</emphasis> menu item in this menu.
3862 </para>
3863 </listitem>
3864 </varlistentry>
3865
3866 <varlistentry>
3867 <term>
3868 <computeroutput>ResetWarnings</computeroutput>
3869 </term>
3870
3871 <listitem>
3872 <para>
3873 Do not show the <emphasis role="bold">Reset All
3874 Warnings</emphasis> menu item in this menu.
3875 </para>
3876 </listitem>
3877 </varlistentry>
3878
3879 <varlistentry>
3880 <term>
3881 <computeroutput>NetworkAccessManager</computeroutput>
3882 </term>
3883
3884 <listitem>
3885 <para>
3886 Do not show the <emphasis role="bold">Network Operations
3887 Manager</emphasis> menu item in this menu.
3888 </para>
3889 </listitem>
3890 </varlistentry>
3891
3892 <varlistentry>
3893 <term>
3894 <computeroutput>About</computeroutput>
3895 </term>
3896
3897 <listitem>
3898 <para>
3899 Do not show the <emphasis role="bold">About</emphasis>
3900 menu item in this menu. Only for non-Mac OS X hosts.
3901 </para>
3902 </listitem>
3903 </varlistentry>
3904
3905 <varlistentry>
3906 <term>
3907 <computeroutput>Contents</computeroutput>
3908 </term>
3909
3910 <listitem>
3911 <para>
3912 Do not show the
3913 <emphasis role="bold">Contents...</emphasis> menu item in
3914 this menu.
3915 </para>
3916 </listitem>
3917 </varlistentry>
3918
3919 <varlistentry>
3920 <term>
3921 <computeroutput>Contents</computeroutput>
3922 </term>
3923
3924 <listitem>
3925 <para>
3926 Do not show the
3927 <emphasis role="bold">Contents...</emphasis> menu item in
3928 this menu.
3929 </para>
3930 </listitem>
3931 </varlistentry>
3932
3933 </variablelist>
3934
3935 <para>
3936 This is a per-VM setting. Any combination of the above is
3937 allowed. To restore the default behavior, use
3938 </para>
3939
3940<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeHelpMenuActions</screen>
3941
3942 </sect2>
3943
3944 <sect2 id="config-vm-window-status-bar">
3945
3946 <title>Configure VM Window Status Bar Entries</title>
3947
3948 <para>
3949 You can disable, or blacklist, certain status bar items:
3950 </para>
3951
3952<screen>VBoxManage setextradata "VM name" GUI/RestrictedStatusBarIndicators OPTION[,OPTION...]</screen>
3953
3954 <para>
3955 where <computeroutput>OPTION</computeroutput> is one of the
3956 following keywords:
3957 </para>
3958
3959 <variablelist>
3960
3961 <varlistentry>
3962 <term>
3963 <computeroutput>HardDisks</computeroutput>
3964 </term>
3965
3966 <listitem>
3967 <para>
3968 Do not show the hard disk icon in the VM window status
3969 bar. By default the hard disk icon is only shown if the VM
3970 configuration contains one or more hard disks.
3971 </para>
3972 </listitem>
3973 </varlistentry>
3974
3975 <varlistentry>
3976 <term>
3977 <computeroutput>OpticalDisks</computeroutput>
3978 </term>
3979
3980 <listitem>
3981 <para>
3982 Do not show the CD icon in the VM window status bar. By
3983 default the CD icon is only shown if the VM configuration
3984 contains one or more CD drives.
3985 </para>
3986 </listitem>
3987 </varlistentry>
3988
3989 <varlistentry>
3990 <term>
3991 <computeroutput>FloppyDisks</computeroutput>
3992 </term>
3993
3994 <listitem>
3995 <para>
3996 Do not show the floppy icon in the VM window status bar.
3997 By default the floppy icon is only shown if the VM
3998 configuration contains one or more floppy drives.
3999 </para>
4000 </listitem>
4001 </varlistentry>
4002
4003 <varlistentry>
4004 <term>
4005 <computeroutput>Network</computeroutput>
4006 </term>
4007
4008 <listitem>
4009 <para>
4010 Do not show the network icon in the VM window status bar.
4011 By default the network icon is only shown if the VM
4012 configuration contains one or more active network
4013 adapters.
4014 </para>
4015 </listitem>
4016 </varlistentry>
4017
4018 <varlistentry>
4019 <term>
4020 <computeroutput>USB</computeroutput>
4021 </term>
4022
4023 <listitem>
4024 <para>
4025 Do not show the USB icon in the status bar.
4026 </para>
4027 </listitem>
4028 </varlistentry>
4029
4030 <varlistentry>
4031 <term>
4032 <computeroutput>SharedFolders</computeroutput>
4033 </term>
4034
4035 <listitem>
4036 <para>
4037 Do not show the shared folders icon in the status bar.
4038 </para>
4039 </listitem>
4040 </varlistentry>
4041
4042 <varlistentry>
4043 <term>
4044 <computeroutput>Capture</computeroutput>
4045 </term>
4046
4047 <listitem>
4048 <para>
4049 Do not show the capture icon in the status bar.
4050 </para>
4051 </listitem>
4052 </varlistentry>
4053
4054 <varlistentry>
4055 <term>
4056 <computeroutput>Features</computeroutput>
4057 </term>
4058
4059 <listitem>
4060 <para>
4061 Do not show the CPU features icon in the status bar.
4062 </para>
4063 </listitem>
4064 </varlistentry>
4065
4066 <varlistentry>
4067 <term>
4068 <computeroutput>Mouse</computeroutput>
4069 </term>
4070
4071 <listitem>
4072 <para>
4073 Do not show the mouse icon in the status bar.
4074 </para>
4075 </listitem>
4076 </varlistentry>
4077
4078 <varlistentry>
4079 <term>
4080 <computeroutput>Keyboard</computeroutput>
4081 </term>
4082
4083 <listitem>
4084 <para>
4085 Do not show the keyboard icon in the status bar.
4086 </para>
4087 </listitem>
4088 </varlistentry>
4089
4090 </variablelist>
4091
4092 <para>
4093 This is a per-VM setting. Any combination of the above is
4094 allowed. If all options are specified, no icons are displayed in
4095 the status bar of the VM window. To restore the default
4096 behavior, use
4097 </para>
4098
4099<screen>VBoxManage setextradata "VM name" GUI/RestrictedStatusBarIndicators</screen>
4100
4101 </sect2>
4102
4103 <sect2 id="config-vm-window-visual-modes">
4104
4105 <title>Configure VM Window Visual Modes</title>
4106
4107 <para>
4108 You can disable, or blacklist, certain VM visual modes:
4109 </para>
4110
4111<screen>VBoxManage setextradata "VM name" GUI/RestrictedVisualStates OPTION[,OPTION...]</screen>
4112
4113 <para>
4114 where <computeroutput>OPTION</computeroutput> is one of the
4115 following keywords:
4116 </para>
4117
4118 <variablelist>
4119
4120 <varlistentry>
4121 <term>
4122 <computeroutput>Fullscreen</computeroutput>
4123 </term>
4124
4125 <listitem>
4126 <para>
4127 Do not allow to switch the VM into full screen mode.
4128 </para>
4129 </listitem>
4130 </varlistentry>
4131
4132 <varlistentry>
4133 <term>
4134 <computeroutput>Seamless</computeroutput>
4135 </term>
4136
4137 <listitem>
4138 <para>
4139 Do not allow to switch the VM into seamless mode.
4140 </para>
4141 </listitem>
4142 </varlistentry>
4143
4144 <varlistentry>
4145 <term>
4146 <computeroutput>Scale</computeroutput>
4147 </term>
4148
4149 <listitem>
4150 <para>
4151 Do not allow to switch the VM into scale mode.
4152 </para>
4153 </listitem>
4154 </varlistentry>
4155
4156 </variablelist>
4157
4158 <para>
4159 This is a per-VM setting. Any combination of the above is
4160 allowed. To restore the default behavior, use
4161 </para>
4162
4163<screen>VBoxManage setextradata "VM name" GUI/RestrictedVisualStates</screen>
4164
4165 </sect2>
4166
4167 <sect2 id="host-key-customize">
4168
4169 <title>Host Key Customization</title>
4170
4171 <para>
4172 To disable all Host key combinations, open the preferences and
4173 change the Host key to None. This might be useful when using
4174 &product-name; in a kiosk mode.
4175 </para>
4176
4177 <para>
4178 To redefine or disable certain Host key actions, use the
4179 following command:
4180 </para>
4181
4182<screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...."</screen>
4183
4184 <para>
4185 The following table shows the possible Host key actions,
4186 together with their default Host key shortcut. Setting an action
4187 to None will disable that Host key action.
4188 </para>
4189
4190 <table id="table-host-key-customize" tabstyle="oracle-all">
4191 <title>Host Key Customization</title>
4192 <tgroup cols="3">
4193 <thead>
4194 <row>
4195 <entry><para>
4196 <emphasis role="bold">Action</emphasis>
4197 </para></entry>
4198 <entry><para>
4199 <emphasis role="bold">Default Key</emphasis>
4200 </para></entry>
4201 <entry><para>
4202 <emphasis role="bold">Action</emphasis>
4203 </para></entry>
4204 </row>
4205 </thead>
4206 <tbody>
4207 <row>
4208 <entry><para>
4209 <computeroutput>TakeSnapshot</computeroutput>
4210 </para></entry>
4211 <entry><para>
4212 T
4213 </para></entry>
4214 <entry><para>
4215 Take a snapshot
4216 </para></entry>
4217 </row>
4218 <row>
4219 <entry><para>
4220 <computeroutput>TakeScreenshot</computeroutput>
4221 </para></entry>
4222 <entry><para>
4223 E
4224 </para></entry>
4225 <entry><para>
4226 Take a screenshot
4227 </para></entry>
4228 </row>
4229 <row>
4230 <entry><para>
4231 <computeroutput>MouseIntegration</computeroutput>
4232 </para></entry>
4233 <entry><para>
4234 I
4235 </para></entry>
4236 <entry><para>
4237 Toggle mouse integration
4238 </para></entry>
4239 </row>
4240 <row>
4241 <entry><para>
4242 <computeroutput>TypeCAD</computeroutput>
4243 </para></entry>
4244 <entry><para>
4245 Del
4246 </para></entry>
4247 <entry><para>
4248 Inject Ctrl+Alt+Del
4249 </para></entry>
4250 </row>
4251 <row>
4252 <entry><para>
4253 <computeroutput>TypeCABS</computeroutput>
4254 </para></entry>
4255 <entry><para>
4256 Backspace
4257 </para></entry>
4258 <entry><para>
4259 Inject Ctrl+Alt+Backspace
4260 </para></entry>
4261 </row>
4262 <row>
4263 <entry><para>
4264 <computeroutput>Pause</computeroutput>
4265 </para></entry>
4266 <entry><para>
4267 P
4268 </para></entry>
4269 <entry><para>
4270 Pause the VM
4271 </para></entry>
4272 </row>
4273 <row>
4274 <entry><para>
4275 <computeroutput>Reset</computeroutput>
4276 </para></entry>
4277 <entry><para>
4278 R
4279 </para></entry>
4280 <entry>Hard reset the guest</entry>
4281 </row>
4282 <row>
4283 <entry><para>
4284 <computeroutput>SaveState</computeroutput>
4285 </para></entry>
4286 <entry><para></para></entry>
4287 <entry><para>
4288 Save the VM state and terminate the VM
4289 </para></entry>
4290 </row>
4291 <row>
4292 <entry><para>
4293 <computeroutput>Shutdown</computeroutput>
4294 </para></entry>
4295 <entry><para>
4296 H
4297 </para></entry>
4298 <entry><para>
4299 Press the virtual ACPI power button
4300 </para></entry>
4301 </row>
4302 <row>
4303 <entry><para>
4304 <computeroutput>PowerOff</computeroutput>
4305 </para></entry>
4306 <entry><para></para></entry>
4307 <entry><para>
4308 Power off the VM without saving the state
4309 </para></entry>
4310 </row>
4311 <row>
4312 <entry><para>
4313 <computeroutput>Close</computeroutput>
4314 </para></entry>
4315 <entry><para>
4316 Q
4317 </para></entry>
4318 <entry><para>
4319 Show the Close VM dialog
4320 </para></entry>
4321 </row>
4322 <row>
4323 <entry><para>
4324 <computeroutput>FullscreenMode</computeroutput>
4325 </para></entry>
4326 <entry><para>
4327 F
4328 </para></entry>
4329 <entry><para>
4330 Switch the VM into full screen mode
4331 </para></entry>
4332 </row>
4333 <row>
4334 <entry><para>
4335 <computeroutput>SeamlessMode</computeroutput>
4336 </para></entry>
4337 <entry><para>
4338 L
4339 </para></entry>
4340 <entry><para>
4341 Switch the VM into seamless mode
4342 </para></entry>
4343 </row>
4344 <row>
4345 <entry><para>
4346 <computeroutput>ScaleMode</computeroutput>
4347 </para></entry>
4348 <entry><para>
4349 C
4350 </para></entry>
4351 <entry><para>
4352 Switch the VM into scaled mode
4353 </para></entry>
4354 </row>
4355 <row>
4356 <entry><para>
4357 <computeroutput>GuestAutoResize</computeroutput>
4358 </para></entry>
4359 <entry><para>
4360 G
4361 </para></entry>
4362 <entry><para>
4363 Automatically resize the guest window
4364 </para></entry>
4365 </row>
4366 <row>
4367 <entry><para>
4368 <computeroutput>WindowAdjust</computeroutput>
4369 </para></entry>
4370 <entry><para>
4371 A
4372 </para></entry>
4373 <entry><para>
4374 Immediately resize the guest window
4375 </para></entry>
4376 </row>
4377 <row>
4378 <entry><para>
4379 <computeroutput>PopupMenu</computeroutput>
4380 </para></entry>
4381 <entry><para>
4382 Home
4383 </para></entry>
4384 <entry><para>
4385 Show the popup menu in full screen mode and seamless
4386 mode
4387 </para></entry>
4388 </row>
4389 <row>
4390 <entry><para>
4391 <computeroutput>SettingsDialog</computeroutput>
4392 </para></entry>
4393 <entry><para>
4394 S
4395 </para></entry>
4396 <entry><para>
4397 Open the VM Settings dialog
4398 </para></entry>
4399 </row>
4400 <row>
4401 <entry><para>
4402 <computeroutput>InformationDialog</computeroutput>
4403 </para></entry>
4404 <entry><para>
4405 N
4406 </para></entry>
4407 <entry><para>
4408 Show the VM Session Information window
4409 </para></entry>
4410 </row>
4411 <row>
4412 <entry><para>
4413 <computeroutput>NetworkAdaptersDialog</computeroutput>
4414 </para></entry>
4415 <entry><para></para></entry>
4416 <entry><para>
4417 Show the VM Network Adapters dialog
4418 </para></entry>
4419 </row>
4420 <row>
4421 <entry><para>
4422 <computeroutput>SharedFoldersDialog</computeroutput>
4423 </para></entry>
4424 <entry><para></para></entry>
4425 <entry><para>
4426 Show the VM Shared Folders dialog
4427 </para></entry>
4428 </row>
4429 <row>
4430 <entry><para>
4431 <computeroutput>InstallGuestAdditions</computeroutput>
4432 </para></entry>
4433 <entry><para>
4434 D
4435 </para></entry>
4436 <entry><para>
4437 Mount the ISO containing the Guest Additions
4438 </para></entry>
4439 </row>
4440 </tbody>
4441 </tgroup>
4442 </table>
4443
4444 <para>
4445 To disable full screen mode and seamless mode, use the following
4446 command:
4447 </para>
4448
4449<screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</screen>
4450
4451 </sect2>
4452
4453 <sect2 id="terminate-vm-action">
4454
4455 <title>Action when Terminating the VM</title>
4456
4457 <para>
4458 You can disallow, or blacklist, certain actions when terminating
4459 a VM. To disallow specific actions, use the following command:
4460 </para>
4461
4462<screen>VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...]</screen>
4463
4464 <para>
4465 where <computeroutput>OPTION</computeroutput> is one of the
4466 following keywords:
4467 </para>
4468
4469 <variablelist>
4470
4471 <varlistentry>
4472 <term>
4473 <computeroutput>SaveState</computeroutput>
4474 </term>
4475
4476 <listitem>
4477 <para>
4478 Do not allow the user to save the VM state when
4479 terminating the VM.
4480 </para>
4481 </listitem>
4482 </varlistentry>
4483
4484 <varlistentry>
4485 <term>
4486 <computeroutput>Shutdown</computeroutput>
4487 </term>
4488
4489 <listitem>
4490 <para>
4491 Do not allow the user to shutdown the VM by sending the
4492 ACPI power-off event to the guest.
4493 </para>
4494 </listitem>
4495 </varlistentry>
4496
4497 <varlistentry>
4498 <term>
4499 <computeroutput>PowerOff</computeroutput>
4500 </term>
4501
4502 <listitem>
4503 <para>
4504 Do not allow the user to power off the VM.
4505 </para>
4506 </listitem>
4507 </varlistentry>
4508
4509 <varlistentry>
4510 <term>
4511 <computeroutput>PowerOffRestoringSnapshot</computeroutput>
4512 </term>
4513
4514 <listitem>
4515 <para>
4516 Do not allow the user to return to the last snapshot when
4517 powering off the VM.
4518 </para>
4519 </listitem>
4520 </varlistentry>
4521
4522 <varlistentry>
4523 <term>
4524 <computeroutput>Detach</computeroutput>
4525 </term>
4526
4527 <listitem>
4528 <para>
4529 Do not allow the user to detach from the VM process if the
4530 VM was started in separate mode.
4531 </para>
4532 </listitem>
4533 </varlistentry>
4534
4535 </variablelist>
4536
4537 <para>
4538 This is a per-VM setting. Any combination of the above is
4539 allowed. If all options are specified, the VM cannot be shut
4540 down at all.
4541 </para>
4542
4543 </sect2>
4544
4545 <sect2 id="terminate-vm-default-action">
4546
4547 <title>Default Action when Terminating the VM</title>
4548
4549 <para>
4550 You can define a specific action for terminating a VM. In
4551 contrast to the setting decribed in the previous section, this
4552 setting allows only one action when the user terminates the VM.
4553 No exit menu is shown. Use the following command:
4554 </para>
4555
4556<screen>VBoxManage setextradata "VM name" GUI/DefaultCloseAction ACTION</screen>
4557
4558 <para>
4559 where <computeroutput>ACTION</computeroutput> is one of the
4560 following keywords:
4561 </para>
4562
4563 <variablelist>
4564
4565 <varlistentry>
4566 <term>
4567 <computeroutput>SaveState</computeroutput>
4568 </term>
4569
4570 <listitem>
4571 <para>
4572 Save the VM state before terminating the VM process.
4573 </para>
4574 </listitem>
4575 </varlistentry>
4576
4577 <varlistentry>
4578 <term>
4579 <computeroutput>Shutdown</computeroutput>
4580 </term>
4581
4582 <listitem>
4583 <para>
4584 The VM is shut down by sending the ACPI power-off event to
4585 the guest.
4586 </para>
4587 </listitem>
4588 </varlistentry>
4589
4590 <varlistentry>
4591 <term>
4592 <computeroutput>PowerOff</computeroutput>
4593 </term>
4594
4595 <listitem>
4596 <para>
4597 The VM is powered off.
4598 </para>
4599 </listitem>
4600 </varlistentry>
4601
4602 <varlistentry>
4603 <term>
4604 <computeroutput>PowerOffRestoringSnapshot</computeroutput>
4605 </term>
4606
4607 <listitem>
4608 <para>
4609 The VM is powered off and the saved state returns to the
4610 last snapshot.
4611 </para>
4612 </listitem>
4613 </varlistentry>
4614
4615 <varlistentry>
4616 <term>
4617 <computeroutput>Detach</computeroutput>
4618 </term>
4619
4620 <listitem>
4621 <para>
4622 Terminate the frontend but leave the VM process running.
4623 </para>
4624 </listitem>
4625 </varlistentry>
4626
4627 </variablelist>
4628
4629 <para>
4630 This is a per-VM setting. Any combination of the above is
4631 allowed. If all options are specified, the VM cannot be shut
4632 down at all.
4633 </para>
4634
4635 </sect2>
4636
4637 <sect2 id="guru-meditation-action">
4638
4639 <title>Action for Handling a Guru Meditation</title>
4640
4641 <para>
4642 A VM runs into a Guru Meditation if there is a problem which
4643 cannot be fixed by other means than terminating the process. The
4644 default is to show a message window which instructs the user to
4645 open a bug report.
4646 </para>
4647
4648 <para>
4649 This behavior can be configured as follows:
4650 </para>
4651
4652<screen>VBoxManage setextradata "VM name" GUI/GuruMeditationHandler MODE</screen>
4653
4654 <para>
4655 where <computeroutput>MODE</computeroutput> is one of the
4656 following keywords:
4657 </para>
4658
4659 <variablelist>
4660
4661 <varlistentry>
4662 <term>
4663 <computeroutput>Default</computeroutput>
4664 </term>
4665
4666 <listitem>
4667 <para>
4668 A message window is shown. After the user confirmed, the
4669 VM is terminated.
4670 </para>
4671 </listitem>
4672 </varlistentry>
4673
4674 <varlistentry>
4675 <term>
4676 <computeroutput>PowerOff</computeroutput>
4677 </term>
4678
4679 <listitem>
4680 <para>
4681 The VM is immediately powered-off without showing any
4682 message window. The VM logfile will show information about
4683 what happened.
4684 </para>
4685 </listitem>
4686 </varlistentry>
4687
4688 <varlistentry>
4689 <term>
4690 <computeroutput>Ignore</computeroutput>
4691 </term>
4692
4693 <listitem>
4694 <para>
4695 The VM is left in stuck mode. Execution is stopped but no
4696 message window is shown. The VM has to be powered off
4697 manually.
4698 </para>
4699 </listitem>
4700 </varlistentry>
4701
4702 </variablelist>
4703
4704 <para>
4705 This is a per-VM setting.
4706 </para>
4707
4708 </sect2>
4709
4710 <sect2 id="mouse-capture">
4711
4712 <title>Configuring Automatic Mouse Capturing</title>
4713
4714 <para>
4715 By default, the mouse is captured if the user clicks on the
4716 guest window and the guest expects relative mouse coordinates at
4717 this time. This happens if the pointing device is configured as
4718 PS/2 mouse and the guest has not yet started the &product-name;
4719 Guest Additions. For instance, the guest is booting or the Guest
4720 Additions are not installed, or if the pointing device is
4721 configured as a USB tablet but the guest has no USB driver
4722 loaded yet. Once the Guest Additions become active or the USB
4723 guest driver is started, the mouse capture is automatically
4724 released.
4725 </para>
4726
4727 <para>
4728 The default behavior is sometimes not desired. Therefore it can
4729 be configured as follows:
4730 </para>
4731
4732<screen>VBoxManage setextradata "VM name" GUI/MouseCapturePolicy MODE</screen>
4733
4734 <para>
4735 where <computeroutput>MODE</computeroutput> is one of the
4736 following keywords:
4737 </para>
4738
4739 <variablelist>
4740
4741 <varlistentry>
4742 <term>
4743 <computeroutput>Default</computeroutput>
4744 </term>
4745
4746 <listitem>
4747 <para>
4748 The default behavior as described above.
4749 </para>
4750 </listitem>
4751 </varlistentry>
4752
4753 <varlistentry>
4754 <term>
4755 <computeroutput>HostComboOnly</computeroutput>
4756 </term>
4757
4758 <listitem>
4759 <para>
4760 The mouse is only captured if the Host Key is toggled.
4761 </para>
4762 </listitem>
4763 </varlistentry>
4764
4765 <varlistentry>
4766 <term>
4767 <computeroutput>Disabled</computeroutput>
4768 </term>
4769
4770 <listitem>
4771 <para>
4772 The mouse is never captured, also not by toggling the Host
4773 Key
4774 </para>
4775 </listitem>
4776 </varlistentry>
4777
4778 </variablelist>
4779
4780 <para>
4781 This is a per-VM setting.
4782 </para>
4783
4784 </sect2>
4785
4786 <sect2 id="legacy-fullscreen-mode">
4787
4788 <title>Requesting Legacy Full-Screen Mode</title>
4789
4790 <para>
4791 &product-name; uses special window manager facilities to switch
4792 a multi-screen machine to full-screen on a multi-monitor host
4793 system. However, not all window managers provide these
4794 facilities correctly. &product-name; can be configured to use a
4795 legacy method of switching to full-screen mode instead, by using
4796 the command:
4797 </para>
4798
4799<screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode true</screen>
4800
4801 <para>
4802 You can go back to the default method by using the following
4803 command:
4804 </para>
4805
4806<screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode</screen>
4807
4808 <para>
4809 This is a global setting.
4810 </para>
4811
4812 </sect2>
4813
4814 <sect2 id="restrict-network-attachments">
4815
4816 <title>Removing Certain Modes of Networking from the GUI</title>
4817
4818 <para>
4819 It is possible to remove networking modes from
4820 &product-name; GUI. To achieve this:
4821 </para>
4822
4823<screen>VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes OPTION[,OPTION...]</screen>
4824
4825 <para>
4826 where <computeroutput>OPTION</computeroutput> is one of the
4827 following keywords:
4828 </para>
4829
4830 <variablelist>
4831
4832 <varlistentry>
4833 <term>
4834 <computeroutput>NAT</computeroutput>
4835 </term>
4836
4837 <listitem>
4838 <para>
4839 Remove the <emphasis role="bold">NAT</emphasis> option
4840 from the GUI.
4841 </para>
4842 </listitem>
4843 </varlistentry>
4844
4845 <varlistentry>
4846 <term>
4847 <computeroutput>NATNetwork</computeroutput>
4848 </term>
4849
4850 <listitem>
4851 <para>
4852 Remove the <emphasis role="bold">NAT network</emphasis> option
4853 from the GUI.
4854 </para>
4855 </listitem>
4856 </varlistentry>
4857
4858 <varlistentry>
4859 <term>
4860 <computeroutput>BridgetAdapter</computeroutput>
4861 </term>
4862
4863 <listitem>
4864 <para>
4865 Remove the <emphasis role="bold">Bridged networking</emphasis> option
4866 from the GUI.
4867 </para>
4868 </listitem>
4869 </varlistentry>
4870
4871 <varlistentry>
4872 <term>
4873 <computeroutput>InternalNetwork</computeroutput>
4874 </term>
4875
4876 <listitem>
4877 <para>
4878 Remove the <emphasis role="bold">Internal networking</emphasis> option
4879 from the GUI.
4880 </para>
4881 </listitem>
4882 </varlistentry>
4883
4884 <varlistentry>
4885 <term>
4886 <computeroutput>HostOnlyAdapter</computeroutput>
4887 </term>
4888
4889 <listitem>
4890 <para>
4891 Remove the <emphasis role="bold">Host Only networking</emphasis> option
4892 from the GUI.
4893 </para>
4894 </listitem>
4895 </varlistentry>
4896
4897 <varlistentry>
4898 <term>
4899 <computeroutput>GenericDriver</computeroutput>
4900 </term>
4901
4902 <listitem>
4903 <para>
4904 Remove the <emphasis role="bold">Generic networking</emphasis> option
4905 from the GUI.
4906 </para>
4907 </listitem>
4908 </varlistentry>
4909
4910 </variablelist>
4911
4912
4913 <para>
4914 This is a global setting. Any combination of the above is
4915 allowed. To restore the default behavior, use
4916 </para>
4917
4918<screen>VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes</screen>
4919
4920
4921 </sect2>
4922 </sect1>
4923
4924 <sect1 id="vboxwebsrv-daemon">
4925
4926 <title>Starting the &product-name; Web Service Automatically</title>
4927
4928 <para>
4929 The &product-name; web service,
4930 <computeroutput>vboxwebsrv</computeroutput>, is used for
4931 controlling &product-name; remotely. It is documented in detail in
4932 the &product-name; Software Development Kit (SDK). See
4933 <xref linkend="VirtualBoxAPI" />. As the client base using this
4934 interface is growing, we added start scripts for the various
4935 operation systems we support. The following sections describe how
4936 to use them. The &product-name; web service is never started
4937 automatically as a result of a standard installation.
4938 </para>
4939
4940 <sect2 id="vboxwebsrv-linux">
4941
4942 <title>Linux: Starting the Web Service With init</title>
4943
4944 <para>
4945 On Linux, the web service can be automatically started during
4946 host boot by adding appropriate parameters to the file
4947 <computeroutput>/etc/default/virtualbox</computeroutput>. There
4948 is one mandatory parameter,
4949 <computeroutput>VBOXWEB_USER</computeroutput>, which must be set
4950 to the user which will later start the VMs. The parameters in
4951 the following table all start with the
4952 <computeroutput>VBOXWEB_</computeroutput> prefix string. For
4953 example: <computeroutput>VBOXWEB_HOST</computeroutput> and
4954 <computeroutput>VBOXWEB_PORT</computeroutput>.
4955 </para>
4956
4957 <table id="table-websrv-config-params" tabstyle="oracle-all">
4958 <title>Web Service Configuration Parameters</title>
4959 <tgroup cols="3">
4960 <thead>
4961 <row>
4962 <entry><para>
4963 <emphasis role="bold">Parameter</emphasis>
4964 </para></entry>
4965 <entry><para>
4966 <emphasis role="bold">Description</emphasis>
4967 </para></entry>
4968 <entry><para>
4969 <emphasis role="bold">Default</emphasis>
4970 </para></entry>
4971 </row>
4972 </thead>
4973 <tbody>
4974 <row>
4975 <entry><para>
4976 <computeroutput>USER</computeroutput>
4977 </para></entry>
4978 <entry><para>
4979 The user which the web service runs as
4980 </para></entry>
4981 <entry><para></para></entry>
4982 </row>
4983 <row>
4984 <entry><para>
4985 <computeroutput>HOST</computeroutput>
4986 </para></entry>
4987 <entry><para>
4988 The host to bind the web service to
4989 </para></entry>
4990 <entry><para>
4991 localhost
4992 </para></entry>
4993 </row>
4994 <row>
4995 <entry><para>
4996 <computeroutput>PORT</computeroutput>
4997 </para></entry>
4998 <entry><para>
4999 The port to bind the web service to
5000 </para></entry>
5001 <entry><para>
5002 18083
5003 </para></entry>
5004 </row>
5005 <row>
5006 <entry><para>
5007 <computeroutput>SSL_KEYFILE</computeroutput>
5008 </para></entry>
5009 <entry><para>
5010 Server key and certificate file, in PEM format
5011 </para></entry>
5012 <entry><para></para></entry>
5013 </row>
5014 <row>
5015 <entry><para>
5016 <computeroutput>SSL_PASSWORDFILE</computeroutput>
5017 </para></entry>
5018 <entry><para>
5019 File name for password to server key
5020 </para></entry>
5021 <entry><para></para></entry>
5022 </row>
5023 <row>
5024 <entry><para>
5025 <computeroutput>SSL_CACERT</computeroutput>
5026 </para></entry>
5027 <entry><para>
5028 CA certificate file, in PEM format
5029 </para></entry>
5030 <entry><para></para></entry>
5031 </row>
5032 <row>
5033 <entry><para>
5034 <computeroutput>SSL_CAPATH</computeroutput>
5035 </para></entry>
5036 <entry><para>
5037 CA certificate path
5038 </para></entry>
5039 <entry><para></para></entry>
5040 </row>
5041 <row>
5042 <entry><para>
5043 <computeroutput>SSL_DHFILE</computeroutput>
5044 </para></entry>
5045 <entry><para>
5046 DH file name or DH key length in bits
5047 </para></entry>
5048 <entry><para></para></entry>
5049 </row>
5050 <row>
5051 <entry><para>
5052 <computeroutput>SSL_RANDFILE</computeroutput>
5053 </para></entry>
5054 <entry><para>
5055 File containing seed for random number generator
5056 </para></entry>
5057 <entry><para></para></entry>
5058 </row>
5059 <row>
5060 <entry><para>
5061 <computeroutput>TIMEOUT</computeroutput>
5062 </para></entry>
5063 <entry><para>
5064 Session timeout in seconds, 0 disables timeouts
5065 </para></entry>
5066 <entry><para>
5067 300
5068 </para></entry>
5069 </row>
5070 <row>
5071 <entry><para>
5072 <computeroutput>CHECK_INTERVAL</computeroutput>
5073 </para></entry>
5074 <entry><para>
5075 Frequency of timeout checks in seconds
5076 </para></entry>
5077 <entry><para>
5078 5
5079 </para></entry>
5080 </row>
5081 <row>
5082 <entry><para>
5083 <computeroutput>THREADS</computeroutput>
5084 </para></entry>
5085 <entry><para>
5086 Maximum number of worker threads to run in parallel
5087 </para></entry>
5088 <entry><para>
5089 100
5090 </para></entry>
5091 </row>
5092 <row>
5093 <entry><para>
5094 <computeroutput>KEEPALIVE</computeroutput>
5095 </para></entry>
5096 <entry><para>
5097 Maximum number of requests before a socket will be
5098 closed
5099 </para></entry>
5100 <entry><para>
5101 100
5102 </para></entry>
5103 </row>
5104 <row>
5105 <entry><para>
5106 <computeroutput>ROTATE</computeroutput>
5107 </para></entry>
5108 <entry><para>
5109 Number of log files, 0 disables log rotation
5110 </para></entry>
5111 <entry><para>
5112 10
5113 </para></entry>
5114 </row>
5115 <row>
5116 <entry><para>
5117 <computeroutput>LOGSIZE</computeroutput>
5118 </para></entry>
5119 <entry><para>
5120 Maximum log file size to trigger rotation, in bytes
5121 </para></entry>
5122 <entry><para>
5123 1MB
5124 </para></entry>
5125 </row>
5126 <row>
5127 <entry><para>
5128 <computeroutput>LOGINTERVAL</computeroutput>
5129 </para></entry>
5130 <entry><para>
5131 Maximum time interval to trigger log rotation, in
5132 seconds
5133 </para></entry>
5134 <entry><para>
5135 1 day
5136 </para></entry>
5137 </row>
5138 </tbody>
5139 </tgroup>
5140 </table>
5141
5142 <para>
5143 Setting the parameter
5144 <computeroutput>SSL_KEYFILE</computeroutput> enables the SSL/TLS
5145 support. Using encryption is strongly encouraged, as otherwise
5146 everything, including passwords, is transferred in clear text.
5147 </para>
5148
5149 </sect2>
5150
5151 <sect2 id="vboxwebsrv-solaris">
5152
5153 <title>Oracle Solaris: Starting the Web Service With SMF</title>
5154
5155 <para>
5156 On Oracle Solaris hosts, the &product-name; web service daemon
5157 is integrated into the SMF framework. You can change the
5158 parameters, but do not have to if the defaults below already
5159 match your needs:
5160 </para>
5161
5162<screen>svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
5163svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
5164svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root</screen>
5165
5166 <para>
5167 <xref linkend="table-websrv-config-params"/> showing the
5168 parameter names and defaults also applies for Oracle Solaris.
5169 The parameter names must be changed to lowercase and a prefix of
5170 <computeroutput>config/</computeroutput> has to be added. For
5171 example: <computeroutput>config/user</computeroutput> or
5172 <computeroutput>config/ssl_keyfile</computeroutput>. If you make
5173 any change, do not forget to run the following command to put
5174 the changes into effect immediately:
5175 </para>
5176
5177<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen>
5178
5179 <para>
5180 If you forget the above command then the previous settings are
5181 used when enabling the service. Check the current property
5182 settings as follows:
5183 </para>
5184
5185<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen>
5186
5187 <para>
5188 When everything is configured correctly you can start the
5189 &product-name; web service with the following command:
5190 </para>
5191
5192<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen>
5193
5194 <para>
5195 For more information about SMF, please refer to the Oracle
5196 Solaris documentation.
5197 </para>
5198
5199 </sect2>
5200
5201 <sect2 id="vboxwebsrv-osx">
5202
5203 <title>Mac OS X: Starting the Web Service With launchd</title>
5204
5205 <para>
5206 On Mac OS X, launchd is used to start the &product-name;
5207 webservice. An example configuration file can be found in
5208 <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>.
5209 It can be enabled by changing the
5210 <computeroutput>Disabled</computeroutput> key from
5211 <computeroutput>true</computeroutput> to
5212 <computeroutput>false</computeroutput>. To manually start the
5213 service use the following command:
5214 </para>
5215
5216<screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
5217
5218 <para>
5219 For additional information on how launchd services could be
5220 configured see:
5221 </para>
5222
5223 <para>
5224 <ulink
5225 url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html</ulink>.
5226 </para>
5227
5228 </sect2>
5229
5230 </sect1>
5231
5232 <sect1 id="vboxwatchdog">
5233
5234 <title>&product-name; Watchdog</title>
5235
5236 <para>
5237 The memory ballooning service, formerly known as
5238 <computeroutput>VBoxBalloonCtrl</computeroutput>, was renamed to
5239 VBoxWatchdog. This service now incorporates the following host
5240 services that are meant to be run in a server environment:
5241 </para>
5242
5243 <itemizedlist>
5244
5245 <listitem>
5246 <para>
5247 <emphasis role="bold">Memory ballooning control.</emphasis>
5248 This service automatically takes care of a VM's configured
5249 memory balloon. See <xref linkend="guestadd-balloon" />. This
5250 service is useful for server environments where VMs may
5251 dynamically require more or less memory during runtime.
5252 </para>
5253
5254 <para>
5255 The service periodically checks a VM's current memory balloon
5256 and its free guest RAM and automatically adjusts the current
5257 memory balloon by inflating or deflating it accordingly. This
5258 handling only applies to running VMs having recent Guest
5259 Additions installed.
5260 </para>
5261 </listitem>
5262
5263 <listitem>
5264 <para>
5265 <emphasis role="bold">Host isolation detection.</emphasis>
5266 This service provides a way to detect whether the host cannot
5267 reach the specific &product-name; server instance anymore and
5268 take appropriate actions, such as shutting down, saving the
5269 current state or even powering down certain VMs.
5270 </para>
5271 </listitem>
5272
5273 </itemizedlist>
5274
5275 <para>
5276 All configuration values can be either specified using the command
5277 line or global extradata, whereas command line values always have
5278 a higher priority when set. Some of the configuration values also
5279 be specified on a per-VM basis. So the overall lookup order is:
5280 command line, per-VM basis extradata if available, global
5281 extradata.
5282 </para>
5283
5284 <sect2 id="vboxwatchdog-ballonctrl">
5285
5286 <title>Memory Ballooning Control</title>
5287
5288 <para>
5289 The memory ballooning control inflates and deflates the memory
5290 balloon of VMs based on the VMs free memory and the desired
5291 maximum balloon size.
5292 </para>
5293
5294 <para>
5295 To set up the memory ballooning control the maximum ballooning
5296 size a VM can reach needs to be set. This can be specified using
5297 the command line, as follows:
5298 </para>
5299
5300<screen>--balloon-max &lt;Size in MB&gt;</screen>
5301
5302 <para>
5303 Using a per-VM basis extradata value, as follows:
5304 </para>
5305
5306<screen>VBoxManage setextradata &lt;VM-Name&gt; VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
5307
5308 <para>
5309 Using a global extradata value, as follows:
5310 </para>
5311
5312<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
5313
5314 <note>
5315 <para>
5316 If no maximum ballooning size is specified by at least one of
5317 the parameters above, no ballooning will be performed at all.
5318 </para>
5319 </note>
5320
5321 <para>
5322 Setting the ballooning increment in MB can be either done using
5323 command line, as follows:
5324 </para>
5325
5326<screen>--balloon-inc &lt;Size in MB&gt;</screen>
5327
5328 <para>
5329 Using a global extradata value, as follows:
5330 </para>
5331
5332<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB &lt;Size in MB&gt;</screen>
5333
5334 <para>
5335 The default ballooning increment is 256 MB if not specified.
5336 </para>
5337
5338 <para>
5339 The same options apply for a ballooning decrement. Using the
5340 command line, as follows:
5341 </para>
5342
5343<screen>--balloon-dec &lt;Size in MB&gt;</screen>
5344
5345 <para>
5346 Using a global extradata value, as follows:
5347 </para>
5348
5349<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB &lt;Size in MB&gt;</screen>
5350
5351 <para>
5352 The default ballooning decrement is 128 MB if not specified.
5353 </para>
5354
5355 <para>
5356 The lower limit in MB for a balloon can be defined using the
5357 command line, as follows:
5358 </para>
5359
5360<screen>--balloon-lower-limit &lt;Size in MB&gt;</screen>
5361
5362 <para>
5363 Using a global extradata value, as follows:
5364 </para>
5365
5366<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB &lt;Size in MB&gt;</screen>
5367
5368 <para>
5369 The default lower limit is 128 MB if not specified.
5370 </para>
5371
5372 </sect2>
5373
5374 <sect2 id="vboxwatchdog-hostisln">
5375
5376 <title>Host Isolation Detection</title>
5377
5378 <para>
5379 To detect whether a host is being isolated, that is, the host
5380 cannot reach the &product-name; server instance anymore, the
5381 host needs to set an alternating value to a global extradata
5382 value within a time period. If this value is not set within that
5383 time period a timeout occurred and the so-called host isolation
5384 response will be performed to the VMs handled. Which VMs are
5385 handled can be controlled by defining VM groups and assigning
5386 VMs to those groups. By default no groups are set, meaning that
5387 all VMs on the server will be handled when no host response is
5388 received within 30 seconds.
5389 </para>
5390
5391 <para>
5392 Set the groups handled by the host isolation detection using the
5393 following command line:
5394 </para>
5395
5396<screen>--apimon-groups=&lt;string[,stringN]&gt;</screen>
5397
5398 <para>
5399 Using a global extradata value, as follows:
5400 </para>
5401
5402<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups &lt;string[,stringN]&gt;</screen>
5403
5404 <para>
5405 Set the host isolation timeout using the following command line:
5406 </para>
5407
5408<screen>--apimon-isln-timeout=&lt;ms&gt;</screen>
5409
5410 <para>
5411 Using a global extradata value, as follows:
5412 </para>
5413
5414<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS &lt;ms&gt;</screen>
5415
5416 <para>
5417 Set the actual host isolation response using the following
5418 command line:
5419 </para>
5420
5421<screen>--apimon-isln-response=&lt;cmd&gt;</screen>
5422
5423 <para>
5424 Using a global extradata value, as follows:
5425 </para>
5426
5427<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse &lt;cmd&gt;</screen>
5428
5429 <para>
5430 The following response commands are available:
5431 </para>
5432
5433 <itemizedlist>
5434
5435 <listitem>
5436 <para>
5437 <computeroutput>none</computeroutput>. This has no effect.
5438 </para>
5439 </listitem>
5440
5441 <listitem>
5442 <para>
5443 <computeroutput>pause</computeroutput>. Pauses the execution
5444 of a VM.
5445 </para>
5446 </listitem>
5447
5448 <listitem>
5449 <para>
5450 <computeroutput>poweroff</computeroutput>. Shuts down the VM
5451 by pressing the virtual power button. The VM will not have
5452 the chance of saving any data or veto the shutdown process.
5453 </para>
5454 </listitem>
5455
5456 <listitem>
5457 <para>
5458 <computeroutput>save</computeroutput>. Saves the current
5459 machine state and powers off the VM afterwards. If saving
5460 the machine state fails the VM will be paused.
5461 </para>
5462 </listitem>
5463
5464 <listitem>
5465 <para>
5466 <computeroutput>shutdown</computeroutput>. Shuts down the VM
5467 in a gentle way by sending an
5468 <computeroutput>ACPI</computeroutput> shutdown event to the
5469 VM's operating system. The OS then has the chance of doing a
5470 clean shutdown.
5471 </para>
5472 </listitem>
5473
5474 </itemizedlist>
5475
5476 </sect2>
5477
5478 <sect2 id="vboxwatchdog-moreinfo">
5479
5480 <title>More Information</title>
5481
5482 <para>
5483 For more advanced options and parameters like verbose logging
5484 check the built-in command line help accessible with
5485 <computeroutput>--help</computeroutput>.
5486 </para>
5487
5488 </sect2>
5489
5490 <sect2 id="vboxwatchdog-linux">
5491
5492 <title>Linux: Starting the Watchdog Service With init</title>
5493
5494 <para>
5495 On Linux, the watchdog service can be automatically started
5496 during host boot by adding appropriate parameters to the file
5497 <computeroutput>/etc/default/virtualbox</computeroutput>. There
5498 is one mandatory parameter,
5499 <computeroutput>VBOXWATCHDOG_USER</computeroutput>, which must
5500 be set to the user which will later start the VMs. For backward
5501 compatibility you can also specify
5502 <computeroutput>VBOXBALLOONCTRL_USER</computeroutput>.
5503 </para>
5504
5505 <para>
5506 The parameters in the following table all start with the
5507 <computeroutput>VBOXWATCHDOG_</computeroutput> prefix string.
5508 For example:
5509 <computeroutput>VBOXWATCHDOG_BALLOON_INTERVAL</computeroutput>
5510 and <computeroutput>VBOXWATCHDOG_LOGSIZE</computeroutput>.
5511 Legacy parameters such as
5512 <computeroutput>VBOXBALLOONCTRL_INTERVAL</computeroutput> can
5513 still be used.
5514 </para>
5515
5516 <table id="table-vboxwatchdog-config-params" tabstyle="oracle-all">
5517 <title>&product-name; Watchdog Configuration Parameters</title>
5518 <tgroup cols="3">
5519 <thead>
5520 <row>
5521 <entry><para>
5522 <emphasis role="bold">Parameter</emphasis>
5523 </para></entry>
5524 <entry><para>
5525 <emphasis role="bold">Description</emphasis>
5526 </para></entry>
5527 <entry><para>
5528 <emphasis role="bold">Default</emphasis>
5529 </para></entry>
5530 </row>
5531 </thead>
5532 <tbody>
5533 <row>
5534 <entry><para>
5535 <computeroutput>USER</computeroutput>
5536 </para></entry>
5537 <entry><para>
5538 The user which the watchdog service runs as
5539 </para></entry>
5540 <entry><para></para></entry>
5541 </row>
5542 <row>
5543 <entry><para>
5544 <computeroutput>ROTATE</computeroutput>
5545 </para></entry>
5546 <entry><para>
5547 Number of log files, 0 disables log rotation
5548 </para></entry>
5549 <entry><para>
5550 10
5551 </para></entry>
5552 </row>
5553 <row>
5554 <entry><para>
5555 <computeroutput>LOGSIZE</computeroutput>
5556 </para></entry>
5557 <entry><para>
5558 Maximum log file size to trigger rotation, in bytes
5559 </para></entry>
5560 <entry><para>
5561 1MB
5562 </para></entry>
5563 </row>
5564 <row>
5565 <entry><para>
5566 <computeroutput>LOGINTERVAL</computeroutput>
5567 </para></entry>
5568 <entry><para>
5569 Maximum time interval to trigger log rotation, in
5570 seconds
5571 </para></entry>
5572 <entry><para>
5573 1 day
5574 </para></entry>
5575 </row>
5576 <row>
5577 <entry><para>
5578 <computeroutput>BALLOON_INTERVAL</computeroutput>
5579 </para></entry>
5580 <entry><para>
5581 Interval for checking the balloon size, in
5582 milliseconds
5583 </para></entry>
5584 <entry><para>
5585 30000
5586 </para></entry>
5587 </row>
5588 <row>
5589 <entry><para>
5590 <computeroutput>BALLOON_INCREMENT</computeroutput>
5591 </para></entry>
5592 <entry><para>
5593 Balloon size increment, in megabytes
5594 </para></entry>
5595 <entry><para>
5596 256
5597 </para></entry>
5598 </row>
5599 <row>
5600 <entry><para>
5601 <computeroutput>BALLOON_DECREMENT</computeroutput>
5602 </para></entry>
5603 <entry><para>
5604 Balloon size decrement, in megabytes
5605 </para></entry>
5606 <entry><para>
5607 128
5608 </para></entry>
5609 </row>
5610 <row>
5611 <entry><para>
5612 <computeroutput>BALLOON_LOWERLIMIT</computeroutput>
5613 </para></entry>
5614 <entry><para>
5615 Balloon size lower limit, in megabytes
5616 </para></entry>
5617 <entry><para>
5618 64
5619 </para></entry>
5620 </row>
5621 <row>
5622 <entry><para>
5623 <computeroutput>BALLOON_SAFETYMARGIN</computeroutput>
5624 </para></entry>
5625 <entry><para>
5626 Free memory required for decreasing the balloon size,
5627 in megabytes
5628 </para></entry>
5629 <entry><para>
5630 1024
5631 </para></entry>
5632 </row>
5633 </tbody>
5634 </tgroup>
5635 </table>
5636
5637 </sect2>
5638
5639 <sect2 id="vboxwatchdog-solaris">
5640
5641 <title>Oracle Solaris: Starting the Watchdog Service With SMF</title>
5642
5643 <para>
5644 On Oracle Solaris hosts, the &product-name; watchdog service
5645 daemon is integrated into the SMF framework. You can change the
5646 parameters, but do not have to if the defaults already match
5647 your needs:
5648 </para>
5649
5650<screen>svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \
5651 config/balloon_interval=10000
5652svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \
5653config/balloon_safetymargin=134217728</screen>
5654
5655 <para>
5656 <xref linkend="table-vboxwatchdog-config-params"/> also applies
5657 for Oracle Solaris. The parameter names must be changed to
5658 lowercase and a prefix of
5659 <computeroutput>config/</computeroutput> has to be added. For
5660 example: <computeroutput>config/user</computeroutput> or
5661 <computeroutput>config/balloon_safetymargin</computeroutput>. If
5662 you made any change, do not forget to run the following command
5663 to put the changes into effect immediately:
5664 </para>
5665
5666<screen>svcadm refresh svc:/application/virtualbox/balloonctrl:default</screen>
5667
5668 <para>
5669 If you forget the above command then the previous settings will
5670 be used when enabling the service. Check the current property
5671 settings with the following command:
5672 </para>
5673
5674<screen>svcprop -p config svc:/application/virtualbox/balloonctrl:default</screen>
5675
5676 <para>
5677 When everything is configured correctly you can start the
5678 &product-name; watchdog service with the following command:
5679 </para>
5680
5681<screen>svcadm enable svc:/application/virtualbox/balloonctrl:default</screen>
5682
5683 <para>
5684 For more information about SMF, please refer to the Oracle
5685 Solaris documentation.
5686 </para>
5687
5688 </sect2>
5689
5690 </sect1>
5691
5692 <sect1 id="otherextpacks">
5693
5694 <title>Other Extension Packs</title>
5695
5696 <para>
5697 Another extension pack called VNC is available. This extension
5698 pack is open source and replaces the previous integration of the
5699 VNC remote access protocol. This is experimental code, and is
5700 initially available in the &product-name; source code package
5701 only. It is to a large portion code contributed by users, and is
5702 not supported in any way by Oracle.
5703 </para>
5704
5705 <para>
5706 The keyboard handling is severely limited, and only the US
5707 keyboard layout works. Other keyboard layouts will have at least
5708 some keys which produce the wrong results, often with quite
5709 surprising effects, and for layouts which have significant
5710 differences to the US keyboard layout it is most likely unusable.
5711 </para>
5712
5713 <para>
5714 It is possible to install both the &product-name; Extension Pack
5715 and VNC, but only one VRDE module can be active at any time. The
5716 following command switches to the VNC VRDE module in VNC:
5717 </para>
5718
5719<screen>VBoxManage setproperty vrdeextpack VNC</screen>
5720
5721 <para>
5722 Configuring the remote access works very similarly to VRDP, see
5723 <xref linkend="vrde" />, with some limitations. VNC does not
5724 support specifying several port numbers, and the authentication is
5725 done differently. VNC can only deal with password authentication,
5726 and there is no option to use password hashes. This leaves no
5727 other choice than having a clear-text password in the VM
5728 configuration, which can be set with the following command:
5729 </para>
5730
5731<screen>VBoxManage modifyvm "VM name" --vrdeproperty VNCPassword=secret</screen>
5732
5733 <para>
5734 The user is responsible for keeping this password secret, and it
5735 should be removed when a VM configuration is passed to another
5736 person, for whatever purpose. Some VNC servers claim to have
5737 encrypted passwords in the configuration. This is not true
5738 encryption, it is only concealing the passwords, which is only as
5739 secure as using clear-text passwords.
5740 </para>
5741
5742 <para>
5743 The following command switches back to VRDP, if installed:
5744 </para>
5745
5746<screen>VBoxManage setproperty vrdeextpack "&product-name; Extension Pack"</screen>
5747
5748 </sect1>
5749
5750 <sect1 id="autostart">
5751
5752 <title>Starting Virtual Machines During System Boot</title>
5753
5754 <para>
5755 You can start VMs automatically during system boot on Linux,
5756 Oracle Solaris, and Mac OS X platforms for all users.
5757 </para>
5758
5759 <sect2 id="autostart-linux">
5760
5761 <title>Linux: Starting the Autostart Service With init</title>
5762
5763 <para>
5764 On Linux, the autostart service is activated by setting two
5765 variables in
5766 <computeroutput>/etc/default/virtualbox</computeroutput>. The
5767 first one is <computeroutput>VBOXAUTOSTART_DB</computeroutput>
5768 which contains an absolute path to the autostart database
5769 directory. The directory should have write access for every user
5770 who should be able to start virtual machines automatically.
5771 Furthermore the directory should have the sticky bit set. The
5772 second variable is
5773 <computeroutput>VBOXAUTOSTART_CONFIG</computeroutput> which
5774 points the service to the autostart configuration file which is
5775 used during boot to determine whether to allow individual users
5776 to start a VM automatically and configure startup delays. The
5777 configuration file can be placed in
5778 <computeroutput>/etc/vbox</computeroutput> and contains several
5779 options. One is <computeroutput>default_policy</computeroutput>
5780 which controls whether the autostart service allows or denies to
5781 start a VM for users which are not in the exception list. The
5782 exception list starts with
5783 <computeroutput>exception_list</computeroutput> and contains a
5784 comma separated list with usernames. Furthermore a separate
5785 startup delay can be configured for every user to avoid
5786 overloading the host. A sample configuration is given below:
5787 </para>
5788
5789<screen>
5790# Default policy is to deny starting a VM, the other option is "allow".
5791default_policy = deny
5792
5793# Bob is allowed to start virtual machines but starting them
5794# will be delayed for 10 seconds
5795bob = {
5796 allow = true
5797 startup_delay = 10
5798}
5799
5800# Alice is not allowed to start virtual machines, useful to exclude certain users
5801# if the default policy is set to allow.
5802alice = {
5803 allow = false
5804}
5805 </screen>
5806
5807 <para>
5808 Every user who wants to enable autostart for individual machines
5809 has to set the path to the autostart database directory with the
5810 following command:
5811 </para>
5812
5813<screen>VBoxManage setproperty autostartdbpath &lt;Autostart directory&gt;</screen>
5814
5815 </sect2>
5816
5817 <sect2 id="autostart-solaris">
5818
5819 <title>Oracle Solaris: Starting the Autostart Service With SMF</title>
5820
5821 <para>
5822 On Oracle Solaris hosts, the &product-name; autostart daemon is
5823 integrated into the SMF framework. To enable it you have to
5824 point the service to an existing configuration file which has
5825 the same format as on Linux, see
5826 <xref linkend="autostart-linux" />. For example:
5827 </para>
5828
5829<screen>svccfg -s svc:/application/virtualbox/autostart:default setprop \
5830 config/config=/etc/vbox/autostart.cfg</screen>
5831
5832 <para>
5833 When everything is configured correctly you can start the
5834 &product-name; autostart service with the following command:
5835 </para>
5836
5837<screen>svcadm enable svc:/application/virtualbox/autostart:default</screen>
5838
5839 <para>
5840 For more information about SMF, please refer to the Oracle
5841 Solaris documentation.
5842 </para>
5843
5844 </sect2>
5845
5846 <sect2 id="autostart-osx">
5847
5848 <title>Mac OS X: Starting the Autostart Service With launchd</title>
5849
5850 <para>
5851 On Mac OS X, launchd is used to start the &product-name;
5852 autostart service. An example configuration file can be found in
5853 <computeroutput>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</computeroutput>.
5854 To enable the service copy the file to
5855 <computeroutput>/Library/LaunchDaemons</computeroutput> and
5856 change the <computeroutput>Disabled</computeroutput> key from
5857 <computeroutput>true</computeroutput> to
5858 <computeroutput>false</computeroutput>. Furthermore replace the
5859 second parameter to an existing configuration file which has the
5860 same format as on Linux, see <xref linkend="autostart-linux" />.
5861 </para>
5862
5863 <para>
5864 To manually start the service use the following command:
5865 </para>
5866
5867<screen>launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist</screen>
5868
5869 <para>
5870 For additional information on how launchd services can be
5871 configured see:
5872 </para>
5873
5874 <para>
5875 <ulink
5876 url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html">http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html</ulink>.
5877 </para>
5878
5879 </sect2>
5880
5881 <sect2 id="autostart-windows">
5882
5883 <title>Windows: Starting the Autostart Service With windows service</title>
5884
5885 <para>
5886 On Windows, the autostarting is implemented as Windows service.
5887 The service is installed for every user with her/his own credentials.
5888 Before installing any autostart services on a system you have to define
5889 the <computeroutput>VBOXAUTOSTART_CONFIG</computeroutput> environment
5890 variable in the system variables with the path to the config file.
5891 The config file has the same format as on Linux,
5892 see <xref linkend="autostart-linux" />, except the user name
5893 can be specified using following formats: "user", "domain\user",
5894 ".\user" and "user@domain".
5895 </para>
5896
5897 <para>
5898 To activate the autostart ability for particular user a member of
5899 administrators group must run the following command:
5900 </para>
5901
5902 <screen>VBoxAutostartSvc install --user=&lt;user&gt; [--password-file=&lt;password_file&gt;]</screen>
5903
5904 <para>
5905 The password file should contain the password followed by a line break.
5906 The rest of the file is ignored. The user will be asked for a password
5907 if the password file is not specified.
5908 </para>
5909
5910 <para>
5911 To remove the autostart ability for particular user a member of
5912 administrators group must run the following command:
5913 </para>
5914
5915 <screen>VBoxAutostartSvc delete --user=&lt;user&gt;</screen>
5916
5917 <para>
5918 The user can be specified for both commands using following formats:
5919 "user", "domain\user", ".\user" and "user@domain"
5920 </para>
5921
5922 <para>
5923 Note:
5924 </para>
5925
5926 <para>
5927 If user has changed his password a member of administrators group
5928 must either reinstall the service or change the service credentials
5929 using windows service manager. The autostart service can not be
5930 installed for users with empty passwords due to Windows security policies.
5931 </para>
5932
5933 </sect2>
5934
5935 </sect1>
5936
5937 <sect1 id="vboxexpertstoragemgmt">
5938
5939 <title>&product-name; Expert Storage Management</title>
5940
5941 <para>
5942 In case the snapshot model of &product-name; is not sufficient it
5943 is possible to enable a special mode which makes it possible to
5944 reconfigure storage attachments while the VM is paused. The user
5945 has to make sure that the disk data stays consistent to the guest
5946 because unlike with hotplugging the guest is not informed about
5947 detached or newly attached media.
5948 </para>
5949
5950 <para>
5951 The expert storage management mode can be enabled per VM
5952 executing:
5953 </para>
5954
5955<screen>VBoxManage setextradata "VM name" "VBoxInternal2/SilentReconfigureWhilePaused" 1</screen>
5956
5957 <para>
5958 Storage attachments can be reconfigured while the VM is paused
5959 afterwards using:
5960 </para>
5961
5962<screen>VBoxManage storageattach ...</screen>
5963
5964 </sect1>
5965
5966 <sect1 id="hostpowertweaks">
5967
5968 <title>Handling of Host Power Management Events</title>
5969
5970 <para>
5971 Some host power management events are handled by &product-name;.
5972 The actual behavior depends on the platform:
5973 </para>
5974
5975 <itemizedlist>
5976
5977 <listitem>
5978 <para>
5979 <emphasis role="bold">Host Suspends.</emphasis> This event is
5980 generated when the host is about to suspend, that is, the host
5981 saves the state to some non-volatile storage and powers off.
5982 </para>
5983
5984 <para>
5985 This event is currently only handled on Windows hosts and Mac
5986 OS X hosts. When this event is generated, &product-name; will
5987 pause all running VMs.
5988 </para>
5989 </listitem>
5990
5991 <listitem>
5992 <para>
5993 <emphasis role="bold">Host Resumes.</emphasis> This event is
5994 generated when the host woke up from the suspended state.
5995 </para>
5996
5997 <para>
5998 This event is currently only handled on Windows hosts and Mac
5999 OS X hosts. When this event is generated, &product-name; will
6000 resume all VMs which are where paused before.
6001 </para>
6002 </listitem>
6003
6004 <listitem>
6005 <para>
6006 <emphasis role="bold">Battery Low.</emphasis> The battery
6007 level reached a critical level, usually less than 5 percent
6008 charged.
6009 </para>
6010
6011 <para>
6012 This event is currently only handled on Windows hosts and Mac
6013 OS X hosts. When this event is generated, &product-name; will
6014 save the state and terminate all VMs in preparation of a
6015 potential host powerdown.
6016 </para>
6017
6018 <para>
6019 The behavior can be configured. By executing the following
6020 command, no VM is saved:
6021 </para>
6022
6023<screen>VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 0</screen>
6024
6025 <para>
6026 This is a global setting as well as a per-VM setting. The
6027 per-VM value has higher precedence than the global value. The
6028 following command will save the state of all VMs but will not
6029 save the state of VM "foo":
6030 </para>
6031
6032<screen>VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 1
6033VBoxManage setextradata "foo" "VBoxInternal2/SavestateOnBatteryLow" 0</screen>
6034
6035 <para>
6036 The first line is actually not required as by default the
6037 savestate action is performed.
6038 </para>
6039 </listitem>
6040
6041 </itemizedlist>
6042
6043 </sect1>
6044
6045 <sect1 id="sse412passthrough">
6046
6047 <title>Passing Through SSE4.1/SSE4.2 Instructions</title>
6048
6049 <para>
6050 To provide SSE 4.1/SSE 4.2 support to guests, the host CPU has to
6051 implement these instruction sets. The instruction sets are exposed
6052 to guests by default, but it is possible to disable the
6053 instructions for certain guests by using the following commands:
6054 </para>
6055
6056<screen>VBoxManage setextradata "VM name" VBoxInternal/CPUM/IsaExts/SSE4.1 0
6057VBoxManage setextradata "VM name" VBoxInternal/CPUM/IsaExts/SSE4.2 0</screen>
6058
6059 <para>
6060 These are per-VM settings which are enabled by default.
6061 </para>
6062
6063 </sect1>
6064
6065 <sect1 id="hidledssync">
6066
6067 <title>Support for Keyboard Indicator Synchronization</title>
6068
6069 <para>
6070 This feature makes the host keyboard indicators (LEDs) match those
6071 of the VM's emulated keyboard when the machine window is active.
6072 It is currently implemented for Mac OS X and Windows hosts. This
6073 feature is enabled by default on supported host OSes. You can
6074 disable this feature by running the following command:
6075 </para>
6076
6077<screen>VBoxManage setextradata "VM name" GUI/HidLedsSync 0</screen>
6078
6079 <para>
6080 This is a per-VM setting, which is enabled by default.
6081 </para>
6082
6083 </sect1>
6084
6085 <sect1 id="usbtrafficcapturing">
6086
6087 <title>Capturing USB Traffic for Selected Devices</title>
6088
6089 <para>
6090 You can capture USB traffic for single USB devices or on the root
6091 hub level, which captures the traffic of all USB devices attached
6092 to the root hub. &product-name; stores the traffic in a format
6093 which is compatible with Wireshark. To capture the traffic of a
6094 specific USB device it must be attached to the VM with
6095 <command>VBoxManage</command> using the following command:
6096 </para>
6097
6098<screen>VBoxManage controlvm "VM name" usbattach "device uuid|address" --capturefile "filename"</screen>
6099
6100 <para>
6101 In order to enable capturing on the root hub use the following
6102 command while the VM is not running:
6103 </para>
6104
6105<screen>VBoxManage setextradata "VM name" \
6106 VBoxInternal/Devices/usb-ehci/0/LUN#0/Config/CaptureFilename "filename"</screen>
6107
6108 <para>
6109 The command above enables capturing on the root hub attached to
6110 the EHCI controller. To enable it for the OHCI or XHCI controller
6111 replace <computeroutput>usb-ehci</computeroutput> with
6112 <computeroutput>usb-ohci</computeroutput> or
6113 <computeroutput>usb-xhci</computeroutput> respectively.
6114 </para>
6115
6116 </sect1>
6117
6118 <sect1 id="heartbeatservice">
6119
6120 <title>Configuring the Heartbeat Service</title>
6121
6122 <para>
6123 &product-name; ships a simple heartbeat service. Once the Guest
6124 Additions are active, the guest sends frequent heartbeat pings to
6125 the host. If the guest stops sending the heartbeat pings without
6126 properly terminating the service, the VM process will log this
6127 event in the VBox.log file. In the future it might be possible to
6128 configure dedicated actions but for now there is only a warning in
6129 the log file.
6130 </para>
6131
6132 <para>
6133 There are two parameters to configure. The <emphasis>heartbeat
6134 interval</emphasis> defines the time between two heartbeat pings.
6135 The default value is 2 seconds, that is, the heartbeat service of
6136 the &product-name; Guest Additions will send a heartbeat ping
6137 every two seconds. The value in nanoseconds can be configured like
6138 this:
6139 </para>
6140
6141<screen>VBoxManage setextradata "VM name"\
6142 VBoxInternal/Devices/VMMDev/0/Config/HeartbeatInterval 2000000000</screen>
6143
6144 <para>
6145 The <emphasis>heartbeat timeout</emphasis> defines the time the
6146 host waits starting from the last heartbeat ping before it defines
6147 the guest as unresponsive. The default value is 2 times the
6148 heartbeat interval (4 seconds) and can be configured as following,
6149 in nanoseconds:
6150 </para>
6151
6152<screen>VBoxManage setextradata "VM name" \
6153 VBoxInternal/Devices/VMMDev/0/Config/HeartbeatTimeout 4000000000</screen>
6154
6155 <para>
6156 If the heartbeat timeout expires, there will be a log message like
6157 <emphasis>VMMDev: HeartBeatCheckTimer: Guest seems to be
6158 unresponsive. Last heartbeat received 5 seconds ago.</emphasis> If
6159 another heartbeat ping arrives after this warning, there will be a
6160 log message like <emphasis>VMMDev: GuestHeartBeat: Guest is
6161 alive.</emphasis>
6162 </para>
6163
6164 </sect1>
6165
6166 <sect1 id="diskencryption">
6167
6168 <title>Encryption of Disk Images</title>
6169
6170 <para>
6171 &product-name; enables you to transparently encrypt the data
6172 stored in hard disk images for the guest. It does not depend on a
6173 specific image format to be used. Images which have the data
6174 encrypted are not portable between &product-name; and other
6175 virtualization software.
6176 </para>
6177
6178 <para>
6179 &product-name; uses the AES algorithm in XTS mode and supports
6180 128-bit or 256-bit data encryption keys (DEK). The DEK is stored
6181 encrypted in the medium properties and is decrypted during VM
6182 startup by entering a password which was chosen when the image was
6183 encrypted.
6184 </para>
6185
6186 <para>
6187 Since the DEK is stored as part of the VM configuration file, it
6188 is important that it is kept safe. Losing the DEK means that the
6189 data stored in the disk images is lost irrecoverably. Having
6190 complete and up to date backups of all data related to the VM is
6191 the responsibility of the user.
6192 </para>
6193
6194 <sect2 id="diskencryption-limitations">
6195
6196 <title>Limitations of Disk Encryption</title>
6197
6198 <para>
6199 There are some limitations the user needs to be aware of when
6200 using this feature:
6201 </para>
6202
6203 <itemizedlist>
6204
6205 <listitem>
6206 <para>
6207 This feature is part of the &product-name; Extension Pack,
6208 which needs to be installed. Otherwise disk encryption is
6209 unavailable.
6210 </para>
6211 </listitem>
6212
6213 <listitem>
6214 <para>
6215 Since encryption works only on the stored user data, it is
6216 currently not possible to check for metadata integrity of
6217 the disk image. Attackers might destroy data by removing or
6218 changing blocks of data in the image or change metadata
6219 items such as the disk size.
6220 </para>
6221 </listitem>
6222
6223 <listitem>
6224 <para>
6225 Exporting appliances which contain encrypted disk images is
6226 not possible because the OVF specification does not support
6227 this. All images are therefore decrypted during export.
6228 </para>
6229 </listitem>
6230
6231 <listitem>
6232 <para>
6233 The DEK is kept in memory while the VM is running to be able
6234 to decrypt data read and encrypt data written by the guest.
6235 While this should be obvious the user needs to be aware of
6236 this because an attacker might be able to extract the key on
6237 a compromised host and decrypt the data.
6238 </para>
6239 </listitem>
6240
6241 <listitem>
6242 <para>
6243 When encrypting or decrypting the images, the password is
6244 passed in clear text using the &product-name; API. This
6245 needs to be kept in mind, especially when using third party
6246 API clients which make use of the webservice where the
6247 password might be transmitted over the network. The use of
6248 HTTPS is mandatory in such a case.
6249 </para>
6250 </listitem>
6251
6252 <listitem>
6253 <para>
6254 Encrypting images with differencing images is only possible
6255 if there are no snapshots or a linear chain of snapshots.
6256 This limitation may be addressed in a future &product-name;
6257 version.
6258 </para>
6259 </listitem>
6260
6261 </itemizedlist>
6262
6263 </sect2>
6264
6265 <sect2 id="diskencryption-encryption">
6266
6267 <title>Encrypting Disk Images</title>
6268
6269 <para>
6270 Encrypting disk images can be done either using the GUI or
6271 <command>VBoxManage</command>. While the GUI is easier to use,
6272 it works on a per VM basis and encrypts all disk images attached
6273 to the specific VM. With <command>VBoxManage</command> one can
6274 encrypt individual images, including all differencing images. To
6275 encrypt an unencrypted medium with
6276 <command>VBoxManage</command>, use:
6277 </para>
6278
6279<screen>VBoxManage encryptmedium "uuid|filename" \
6280 --newpassword "file|-" --cipher "cipher id" --newpasswordid "id"</screen>
6281
6282 <para>
6283 To supply the encryption password point
6284 <command>VBoxManage</command> to the file where the password is
6285 stored or specify <option>-</option> to let VBoxManage ask you
6286 for the password on the command line.
6287 </para>
6288
6289 <para>
6290 The cipher parameter specifies the cipher to use for encryption
6291 and can be either
6292 <computeroutput>AES-XTS128-PLAIN64</computeroutput> or
6293 <computeroutput>AES-XTS256-PLAIN64</computeroutput>. The
6294 specified password identifier can be freely chosen by the user
6295 and is used for correct identification when supplying multiple
6296 passwords during VM startup.
6297 </para>
6298
6299 <para>
6300 If the user uses the same password when encrypting multiple
6301 images and also the same password identifier, the user needs to
6302 supply the password only once during VM startup.
6303 </para>
6304
6305 </sect2>
6306
6307 <sect2 id="diskencryption-startvm">
6308
6309 <title>Starting a VM with Encrypted Images</title>
6310
6311 <para>
6312 When a VM is started using the GUI, a dialog will open where the
6313 user needs to enter all passwords for all encrypted images
6314 attached to the VM. If another frontend like VBoxHeadless is
6315 used, the VM will be paused as soon as the guest tries to access
6316 an encrypted disk. The user needs to provide the passwords
6317 through <command>VBoxManage</command> using the following
6318 command:
6319 </para>
6320
6321<screen>VBoxManage controlvm "uuid|vmname" addencpassword "id" "password" [--removeonsuspend "yes|no"]</screen>
6322
6323 <para>
6324 The <computeroutput>id</computeroutput> parameter must be the
6325 same as the password identifier supplied when encrypting the
6326 images. <computeroutput>password</computeroutput> is the
6327 password used when encrypting the images. The user can
6328 optionally specify <computeroutput>--removeonsuspend
6329 "yes|no"</computeroutput> to specify whether to remove the
6330 password from VM memory when the VM is suspended. Before the VM
6331 can be resumed, the user needs to supply the passwords again.
6332 This is useful when a VM is suspended by a host suspend event
6333 and the user does not want the password to remain in memory.
6334 </para>
6335
6336 </sect2>
6337
6338 <sect2 id="diskencryption-decryption">
6339
6340 <title>Decrypting Encrypted Images</title>
6341
6342 <para>
6343 In some circumstances it might be required to decrypt previously
6344 encrypted images. This can be done in the GUI for a complete VM
6345 or using <command>VBoxManage</command> with the following
6346 command:
6347 </para>
6348
6349<screen>VBoxManage encryptmedium "uuid|filename" --oldpassword "file|-"</screen>
6350
6351 <para>
6352 The only required parameter is the password the image was
6353 encrypted with. The options are the same as for encrypting
6354 images.
6355 </para>
6356
6357 </sect2>
6358
6359 </sect1>
6360
6361 <sect1 id="gimdebug">
6362
6363 <title>Paravirtualized Debugging</title>
6364
6365 <para>
6366 In this section we cover debugging of guest operating systems
6367 using interfaces supported by paravirtualization providers.
6368 </para>
6369
6370 <note>
6371 <para>
6372 Paravirtualized debugging significantly alter guest operating
6373 system behaviour and should only be used by expert users for
6374 debugging and diagnostics.
6375 </para>
6376 </note>
6377
6378 <para>
6379 These debug options are specified as a string of key-value pairs
6380 separated by commas. An empty string disables paravirtualized
6381 debugging.
6382 </para>
6383
6384 <sect2 id="gimdebughyperv">
6385
6386 <title>Hyper-V Debug Options</title>
6387
6388 <para>
6389 All of the options listed below are optional, and thus the
6390 default value specified will be used when the corresponding
6391 key-value pair is not specified.
6392 </para>
6393
6394 <itemizedlist>
6395
6396 <listitem>
6397 <para>
6398 Key:
6399 <emphasis role="bold"><computeroutput>enabled</computeroutput></emphasis>
6400 </para>
6401
6402 <para>
6403 Value: <computeroutput>0</computeroutput> or
6404 <computeroutput>1</computeroutput>
6405 </para>
6406
6407 <para>
6408 Default: <computeroutput>0</computeroutput>
6409 </para>
6410
6411 <para>
6412 Specify <computeroutput>1</computeroutput> to enable the
6413 Hyper-V debug interface. If this key-value pair is not
6414 specified or the value is not
6415 <computeroutput>1</computeroutput>, the Hyper-V debug
6416 interface is disabled regardless of other key-value pairs
6417 being present.
6418 </para>
6419 </listitem>
6420
6421 <listitem>
6422 <para>
6423 Key:
6424 <emphasis role="bold"><computeroutput>address</computeroutput></emphasis>
6425 </para>
6426
6427 <para>
6428 Value: IPv4 address
6429 </para>
6430
6431 <para>
6432 Default: 127.0.0.1
6433 </para>
6434
6435 <para>
6436 Specify the IPv4 address where the remote debugger is
6437 connected.
6438 </para>
6439 </listitem>
6440
6441 <listitem>
6442 <para>
6443 Key:
6444 <emphasis role="bold"><computeroutput>port</computeroutput></emphasis>
6445 </para>
6446
6447 <para>
6448 Value: UDP port number
6449 </para>
6450
6451 <para>
6452 Default: 50000
6453 </para>
6454
6455 <para>
6456 Specify the UDP port number where the remote debugger is
6457 connected.
6458 </para>
6459 </listitem>
6460
6461 <listitem>
6462 <para>
6463 Key:
6464 <emphasis role="bold"><computeroutput>vendor</computeroutput></emphasis>
6465 </para>
6466
6467 <para>
6468 Value: Hyper-V vendor signature reported by CPUID to the
6469 guest
6470 </para>
6471
6472 <para>
6473 Default: When debugging is enabled:
6474 <computeroutput>Microsoft Hv</computeroutput>, otherwise:
6475 <computeroutput>VBoxVBoxVBox</computeroutput>
6476 </para>
6477
6478 <para>
6479 Specify the Hyper-V vendor signature which is exposed to the
6480 guest by CPUID. For debugging Microsoft Windows guests, it
6481 is required the hypervisor reports the Microsoft vendor.
6482 </para>
6483 </listitem>
6484
6485 <listitem>
6486 <para>
6487 Key:
6488 <emphasis role="bold"><computeroutput>hypercallinterface</computeroutput>
6489 </emphasis>
6490 </para>
6491
6492 <para>
6493 Value: <computeroutput>0</computeroutput> or
6494 <computeroutput>1</computeroutput>
6495 </para>
6496
6497 <para>
6498 Default: <computeroutput>0</computeroutput>
6499 </para>
6500
6501 <para>
6502 Specify whether hypercalls should be suggested for
6503 initiating debug data transfers between host and guest
6504 rather than MSRs when requested by the guest.
6505 </para>
6506 </listitem>
6507
6508 <listitem>
6509 <para>
6510 Key:
6511 <emphasis role="bold"><computeroutput>vsinterface</computeroutput>
6512 </emphasis>
6513 </para>
6514
6515 <para>
6516 Value: <computeroutput>0</computeroutput> or
6517 <computeroutput>1</computeroutput>
6518 </para>
6519
6520 <para>
6521 Default: When debugging is enabled,
6522 <computeroutput>1</computeroutput>, otherwise
6523 <computeroutput>0</computeroutput>
6524 </para>
6525
6526 <para>
6527 Specify whether to expose the VS#1 virtualization service
6528 interface to the guest. This interface is required for
6529 debugging Microsoft Windows 10 32-bit guests, but is
6530 optional for other Windows versions.
6531 </para>
6532 </listitem>
6533
6534 </itemizedlist>
6535
6536 <sect3 id="gimdebughyperv-windows-setup">
6537
6538 <title>Setting up Windows Guests for Debugging with the Hyper-V
6539 Paravirtualization Provider</title>
6540
6541 <para>
6542 Windows supports debugging over a serial cable, USB, IEEE 1394
6543 Firewire, and Ethernet. USB and IEEE 1394 are not applicable
6544 for virtual machines, and Ethernet requires Windows 8 or
6545 later. While a serial connection is universally usable, it is
6546 slow.
6547 </para>
6548
6549 <para>
6550 Debugging using the Hyper-V debug transport, supported on
6551 Windows Vista and later, offers significant benefits. It
6552 provides excellent performance due to direct host-to-guest
6553 transfers, it is easy to set up and requires minimal support
6554 from the hypervisor. It can be used with the debugger running
6555 on the same host as the VM or with the debugger and VM on
6556 separate machines connected over a network.
6557 </para>
6558
6559 <para>
6560 <emphasis role="bold">Prerequisites</emphasis>
6561 </para>
6562
6563 <itemizedlist>
6564
6565 <listitem>
6566 <para>
6567 A VM configured for Hyper-V paravirtualization running a
6568 Windows Vista or newer Windows guest. You can check the
6569 effective paravirtualization provider for your VM with the
6570 output of the following <command>VBoxManage</command>
6571 command:
6572 </para>
6573
6574<screen>VBoxManage showvminfo "VM name"</screen>
6575 </listitem>
6576
6577 <listitem>
6578 <para>
6579 A sufficiently up-to-date version of the Microsoft WinDbg
6580 debugger required to debug the version of Windows in your
6581 VM.
6582 </para>
6583 </listitem>
6584
6585 <listitem>
6586 <para>
6587 While Windows 8 and newer Windows guests ship with Hyper-V
6588 debug support, Windows 7 and Vista do not. To use Hyper-V
6589 debugging with a Windows 7 or Vista guest, copy the file
6590 <computeroutput>kdvm.dll</computeroutput> from a Windows
6591 8.0 installation. This file is typically located in
6592 <computeroutput>C:\Windows\System32</computeroutput>. Copy
6593 it to the same location in your Windows 7/Vista guest.
6594 Make sure you copy the 32-bit or 64-bit version of the DLL
6595 which matches your guest OS.
6596 </para>
6597
6598 <note>
6599 <para>
6600 Only Windows 8.0 ships
6601 <computeroutput>kdvm.dll</computeroutput>. Windows 8.1
6602 and newer Windows versions do not.
6603 </para>
6604 </note>
6605 </listitem>
6606
6607 </itemizedlist>
6608
6609 <para>
6610 <emphasis role="bold">VM and Guest Configuration</emphasis>
6611 </para>
6612
6613 <orderedlist>
6614
6615 <listitem>
6616 <para>
6617 Power off the VM.
6618 </para>
6619 </listitem>
6620
6621 <listitem>
6622 <para>
6623 Enable the debug options with the following
6624 <command>VBoxManage</command> command:
6625 </para>
6626
6627<screen>VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1"</screen>
6628
6629 <para>
6630 The above command assumes your debugger will connect to
6631 your host machine on UDP port 50000. However, if you need
6632 to run the debugger on a remote machine you may specify
6633 the remote address and port here. For example:
6634 </para>
6635
6636<screen>VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1,address=192.168.32.1,port=55000"</screen>
6637
6638 <para>
6639 See <xref linkend="gimdebughyperv" /> for the complete set
6640 of options.
6641 </para>
6642 </listitem>
6643
6644 <listitem>
6645 <para>
6646 Start the VM.
6647 </para>
6648 </listitem>
6649
6650 <listitem>
6651 <para>
6652 In the guest, start an elevated command prompt and execute
6653 the following commands:
6654 </para>
6655
6656 <itemizedlist>
6657
6658 <listitem>
6659 <para>
6660 For a Windows 8 or newer Windows guest:
6661 </para>
6662
6663<screen>bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4</screen>
6664 </listitem>
6665
6666 <listitem>
6667 <para>
6668 For a Windows 7 or Vista guest:
6669 </para>
6670
6671<screen>bcdedit /set loadoptions host_ip=5.5.5.5,host_port=50000,encryption_key=1.2.3.4</screen>
6672
6673<screen>bcdedit /set dbgtransport kdvm.dll</screen>
6674
6675 <para>
6676 The IP address and port in the
6677 <command>bcdedit</command> command are ignored when
6678 using the Hyper-V debug transport. Any valid IP and a
6679 port number greater than 49151 and lower than 65536
6680 can be entered.
6681 </para>
6682
6683 <para>
6684 The encryption key in the <command>bcdedit</command>
6685 command is relevant and must be valid. The key
6686 "1.2.3.4" used in the above example is valid and may
6687 be used if security is not a concern. If you do not
6688 specify any encryption key, <command>bcdedit</command>
6689 will generate one for you and you will need to copy
6690 this key to later enter in Microsoft WinDbg on the
6691 remote end. This encryption key is used to encrypt the
6692 debug data exchanged between Windows and the debugger.
6693 </para>
6694 </listitem>
6695
6696 <listitem>
6697 <para>
6698 Run one or more of the following commands to enable
6699 debugging for the appropriate phase or component of
6700 your Windows guest:
6701 </para>
6702
6703<screen>bcdedit /set debug on</screen>
6704
6705<screen>bcdedit /set bootdebug on</screen>
6706
6707<screen>bcdedit /set {bootmgr} bootdebug on</screen>
6708
6709 <para>
6710 Please note that the <command>bootdebug</command>
6711 options are only effective on Windows 8 or newer when
6712 using the Hyper-V debug transport. Refer to Microsoft
6713 Windows documentation for detailed explanation of
6714 <command>bcdedit</command> options.
6715 </para>
6716 </listitem>
6717
6718 </itemizedlist>
6719 </listitem>
6720
6721 <listitem>
6722 <para>
6723 Start Microsoft WinDbg on your host machine or remote
6724 host.
6725 </para>
6726
6727 <para>
6728 From the <emphasis role="bold">File</emphasis> menu,
6729 select <emphasis role="bold">Kernel Debug</emphasis>. On
6730 the <emphasis role="bold">NET</emphasis> tab, specify the
6731 UDP port number you used in the
6732 <computeroutput>paravirtdebug</computeroutput> options. If
6733 you did not specify any, leave it as 50000. Ensure that
6734 the UDP port is not blocked by a firewall or other
6735 security software.
6736 </para>
6737
6738 <para>
6739 In the <emphasis role="bold">Key</emphasis> field, enter
6740 <computeroutput>1.2.3.4</computeroutput> or the encryption
6741 key from the <computeroutput>bcdedit</computeroutput>
6742 command in your Windows guest.
6743 </para>
6744
6745 <para>
6746 Click <emphasis role="bold">OK</emphasis> to start
6747 listening for connections. Microsoft WinDbg typically
6748 shows a Waiting to Reconnect message during this phase.
6749 </para>
6750
6751 <para>
6752 Alternatively, to directly start a debug session, run
6753 WinDbg from the command line as follows :
6754 </para>
6755
6756<screen>windbg.exe -k net:port=50000,key=1.2.3.4</screen>
6757
6758 <para>
6759 See the WinDbg documentation for the complete command line
6760 syntax.
6761 </para>
6762 </listitem>
6763
6764 <listitem>
6765 <para>
6766 Reboot your Windows guest and it should then connect as a
6767 debuggee with Microsoft WinDbg.
6768 </para>
6769 </listitem>
6770
6771 </orderedlist>
6772
6773 </sect3>
6774
6775 </sect2>
6776
6777 </sect1>
6778
6779 <sect1 id="pcspeaker_passthrough">
6780
6781 <title>PC Speaker Passthrough</title>
6782
6783 <para>
6784 As an experimental feature, primarily due to being limited to
6785 Linux host only and unknown Linux distribution coverage,
6786 &product-name; supports passing through the PC speaker to the
6787 host. The PC speaker, sometimes called the system speaker, is a
6788 way to produce audible feedback such as beeps without the need for
6789 regular audio and sound card support.
6790 </para>
6791
6792 <para>
6793 The PC speaker passthrough feature in &product-name; handles beeps
6794 only. Advanced PC speaker use by the VM, such as PCM audio, will
6795 not work, resulting in undefined host behavior.
6796 </para>
6797
6798 <para>
6799 Producing beeps on Linux is a very complex topic. &product-name;
6800 offers a collection of options, in an attempt to make this work
6801 deterministically and reliably on as many Linux distributions and
6802 system configurations as possible. These are summarized in the
6803 following table.
6804 </para>
6805
6806 <table id="table-pcspeaker-config" tabstyle="oracle-all">
6807 <title>PC Speaker Configuration Options</title>
6808 <tgroup cols="3">
6809 <thead>
6810 <row>
6811 <entry><para>
6812 <emphasis role="bold">Code</emphasis>
6813 </para></entry>
6814 <entry><para>
6815 <emphasis role="bold">Device</emphasis>
6816 </para></entry>
6817 <entry><para>
6818 <emphasis role="bold">Notes</emphasis>
6819 </para></entry>
6820 </row>
6821 </thead>
6822 <tbody>
6823 <row>
6824 <entry><para>
6825 1
6826 </para></entry>
6827 <entry><para>
6828 <computeroutput>/dev/input/by-path/platform-pcspkr-event-spkr</computeroutput>
6829 </para></entry>
6830 <entry><para>
6831 Direct host PC speaker use.
6832 </para></entry>
6833 </row>
6834 <row>
6835 <entry><para>
6836 2
6837 </para></entry>
6838 <entry><computeroutput>/dev/tty</computeroutput></entry>
6839 <entry><para>
6840 Uses the terminal association of the VM process. VM
6841 needs to be started on a virtual console.
6842 </para></entry>
6843 </row>
6844 <row>
6845 <entry><para>
6846 3
6847 </para></entry>
6848 <entry><para>
6849 <computeroutput>/dev/tty0</computeroutput> or
6850 <computeroutput>/dev/vc/0</computeroutput>
6851 </para></entry>
6852 <entry><para>
6853 Can only be used by user
6854 <computeroutput>root</computeroutput> or users with
6855 <computeroutput>cap_sys_tty_config</computeroutput>
6856 capability.
6857 </para></entry>
6858 </row>
6859 <row>
6860 <entry><para>
6861 9
6862 </para></entry>
6863 <entry><para>
6864 A user-specified console or evdev device path.
6865 </para></entry>
6866 <entry><para>
6867 As for codes 1 to 3, but with a custom device path.
6868 </para></entry>
6869 </row>
6870 <row>
6871 <entry><para>
6872 70
6873 </para></entry>
6874 <entry><para>
6875 <computeroutput>/dev/tty</computeroutput>
6876 </para></entry>
6877 <entry><para>
6878 Standard beep only. Loses frequency and length. See code
6879 2.
6880 </para></entry>
6881 </row>
6882 <row>
6883 <entry><para>
6884 79
6885 </para></entry>
6886 <entry><para>
6887 A user-specified terminal device path.
6888 </para></entry>
6889 <entry><para>
6890 As for code 70, but with a custom device path.
6891 </para></entry>
6892 </row>
6893 <row>
6894 <entry><para>
6895 100
6896 </para></entry>
6897 <entry><para>
6898 All of the above.
6899 </para></entry>
6900 <entry><para>
6901 Tries all the available codes.
6902 </para></entry>
6903 </row>
6904 </tbody>
6905 </tgroup>
6906 </table>
6907
6908 <para>
6909 To enable PC speaker passthrough use the following command:
6910 </para>
6911
6912<screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" N</screen>
6913
6914 <para>
6915 Replace <computeroutput>N</computeroutput> with the code
6916 representing the case you want to use. Changing this setting will
6917 take effect when the VM is started next. It is safe to enable PC
6918 speaker passthrough on all host OSes. It will only have an effect
6919 on Linux.
6920 </para>
6921
6922 <para>
6923 The VM log file, <computeroutput>VBox.log</computeroutput>, will
6924 contain lines with the prefix <computeroutput>PIT:
6925 speaker:</computeroutput> showing the PC speaker passthrough setup
6926 activities. It gives hints which device it picked or why it
6927 failed.
6928 </para>
6929
6930 <para>
6931 Enabling PC speaker passthrough for the VM is usually the simple
6932 part. The real difficulty is making sure that &product-name; can
6933 access the necessary device, because in a typical Linux install
6934 most of them can only be accessed by user
6935 <computeroutput>root</computeroutput>. You should follow the
6936 preferred way to persistently change this, such as by referring to
6937 your distribution's documentation. Since there are countless Linux
6938 distribution variants, we can only give the general hints that
6939 there is often a way to give the X11 session user access to
6940 additional devices, or you need to find a working solution using a
6941 udev configuration file. If everything fails you might try setting
6942 the permissions using a script which is run late enough in the
6943 host system startup.
6944 </para>
6945
6946 <para>
6947 Sometimes additional rules are applied by the kernel to limit
6948 access. For example, that the VM process must have the same
6949 controlling terminal as the device configured to be used for
6950 beeping, something which is often very difficult to achieve for
6951 GUI applications such as &product-name;. The table above contains
6952 some hints, but in general refer to the Linux documentation.
6953 </para>
6954
6955 <para>
6956 If you have trouble getting any beeps even if the device
6957 permissions are set up and VBox.log confirms that it uses evdev or
6958 console for the PC speaker control, check if your system has a PC
6959 speaker. Some systems do not have one. Other complications can
6960 arise from Linux rerouting the PC speaker output to a sound card.
6961 Check if the beeps are audible if you connect speakers to your
6962 sound card. Today almost all systems have one. Finally, check if
6963 the audio mixer control has a channel named "beep", which could be
6964 hidden in the mixer settings, and that it is not muted.
6965 </para>
6966
6967 </sect1>
6968
6969 <sect1 id="usbip">
6970
6971 <title>Accessing USB devices Exposed Over the Network with USB/IP</title>
6972
6973 <para>
6974 &product-name; supports passing through USB devices which are
6975 exposed over the network using the USB over IP protocol without
6976 the need to configure the client side provided by the kernel and
6977 usbip tools. Furthermore, this feature works with &product-name;
6978 running on any supported host, rather than just Linux alone, as is
6979 the case with the official client.
6980 </para>
6981
6982 <para>
6983 To enable support for passing through USB/IP devices, the device
6984 server exporting the devices must be added with the following
6985 command:
6986 </para>
6987
6988<screen>VBoxManage usbdevsource add "Unique name" --backend "USBIP" --address "Device server[:port]"</screen>
6989
6990 <para>
6991 USB devices exported on the device server are then accessible
6992 through the GUI or <command>VBoxManage</command>, like any USB
6993 devices attached locally. This can be used multiple times to
6994 access different device servers.
6995 </para>
6996
6997 <para>
6998 To remove a device server, the following command can be used:
6999 </para>
7000
7001<screen>VBoxManage usbdevsource remove "Unique name"</screen>
7002
7003 <sect2 id="usbip-setup-server">
7004
7005 <title>Setting up USB/IP Support on a Linux System</title>
7006
7007 <para>
7008 This section gives a brief overview on how to set up a Linux
7009 based system to act as a USB device server. The system on the
7010 server requires that the
7011 <computeroutput>usbip-core.ko</computeroutput> and
7012 <computeroutput>usbip-host.ko</computeroutput> kernel drivers
7013 are available, and that the USB/IP tools package is installed.
7014 The particular installation method for the necessary tools
7015 depends on which distribution is used. For example, for Debian
7016 based systems, the following command should be used to install
7017 the required tools:
7018 </para>
7019
7020<screen>apt-get install usbip-utils</screen>
7021
7022 <para>
7023 To check whether the necessary tools are already installed use
7024 the following command:
7025 </para>
7026
7027<screen>
7028$ usbip list -l
7029 </screen>
7030
7031 <para>
7032 This should produce output similar to that shown in the example
7033 below:
7034 </para>
7035
7036<screen>
7037 - busid 4-2 (0bda:0301)
7038 Realtek Semiconductor Corp. : multicard reader (0bda:0301)
7039
7040 - busid 5-1 (046d:c52b)
7041 Logitech, Inc. : Unifying Receiver (046d:c52b)
7042 </screen>
7043
7044 <para>
7045 If everything is installed, the USB/IP server needs to be
7046 started as <computeroutput>root</computeroutput> using the
7047 following command:
7048 </para>
7049
7050<screen>usbipd -D</screen>
7051
7052 <para>
7053 Refer to the documentation for the installed distribution to
7054 determine how to start the service when the system boots.
7055 </para>
7056
7057 <para>
7058 By default, no device on the server is exported. This must be
7059 done manually for each device. To export a device use the
7060 following command:
7061 </para>
7062
7063<screen>usbip bind -b "bus identifier"</screen>
7064
7065 <para>
7066 To export the multicard reader in the previous example:
7067 </para>
7068
7069<screen>usbip bind -b 4-2</screen>
7070
7071 </sect2>
7072
7073 <sect2 id="usbip-security">
7074
7075 <title>Security Considerations</title>
7076
7077 <para>
7078 The communication between the server and client is unencrypted
7079 and there is no authorization required to access exported
7080 devices. An attacker might sniff sensitive data or gain control
7081 over a device. To mitigate this risk, the device should be
7082 exposed over a local network to which only trusted clients have
7083 access. To access the device remotely over a public network, a
7084 VPN solution should be used to provide the required level of
7085 security protection.
7086 </para>
7087
7088 </sect2>
7089
7090 </sect1>
7091
7092 <sect1 id="hyperv-support">
7093
7094 <title>Using Hyper-V with &product-name;</title>
7095
7096 <para>
7097 &product-name; can be used on a Windows host where Hyper-V is
7098 running. This is an experimental feature.
7099 </para>
7100
7101 <para>
7102 No configuration is required. &product-name; detects Hyper-V
7103 automatically and uses Hyper-V as the virtualization engine for
7104 the host system. The CPU icon in the VM window status bar
7105 indicates that Hyper-V is being used.
7106 </para>
7107
7108 <note>
7109 <para>
7110 When using this feature, you might experience significant
7111 &product-name; performance degradation on some host systems.
7112 </para>
7113 </note>
7114
7115 </sect1>
7116
7117 <sect1 id="nested-virt">
7118
7119 <title>Nested Virtualization</title>
7120
7121 <para>
7122 &product-name; supports <emphasis>nested virtualization</emphasis>
7123 on host systems that run AMD CPUs. This feature enables the
7124 passthrough of hardware virtualization functions to the guest VM.
7125 That means that you can install a hypervisor, such as
7126 &product-name;, Oracle VM Server or KVM, on an &product-name;
7127 guest. You can then create and run VMs within the guest VM.
7128 </para>
7129
7130 <para>
7131 You can enable the nested virtualization feature in one of the
7132 following ways:
7133 </para>
7134
7135 <itemizedlist>
7136
7137 <listitem>
7138 <para>
7139 From the VirtualBox Manager, select the
7140 <emphasis role="bold">Enable Nested VT-x/AMD-V</emphasis>
7141 check box on the <emphasis role="bold">Processor</emphasis>
7142 tab. To disable the feature, deselect the check box.
7143 </para>
7144 </listitem>
7145
7146 <listitem>
7147 <para>
7148 Use the <option>--nested-hw-virt</option> option of the
7149 <command>VBoxManage modifyvm</command> command to enable or
7150 disable nested virtualization. See
7151 <xref linkend="vboxmanage-modifyvm"/>.
7152 </para>
7153 </listitem>
7154
7155 </itemizedlist>
7156
7157 </sect1>
7158
7159 <xi:include href="user_isomakercmd-man.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
7160
7161</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