VirtualBox

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

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

doc/manual: typos

File size: 113.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
4<chapter id="AdvancedTopics">
5 <title>Advanced topics</title>
6
7 <sect1 id="vboxsdl">
8 <title>VBoxSDL, the simplified VM displayer</title>
9
10 <sect2>
11 <title>Introduction</title>
12
13 <para>VBoxSDL is a simple graphical user interface (GUI) that lacks the
14 nice point-and-click support which VirtualBox, our main GUI, provides.
15 VBoxSDL is currently primarily used internally for debugging VirtualBox
16 and therefore not officially supported. Still, you may find it useful
17 for environments where the virtual machines are not necessarily
18 controlled by the same person that uses the virtual machine.<note>
19 <para>VBoxSDL is not available on the Mac OS X host platform.</para>
20 </note></para>
21
22 <para>As you can see in the following screenshot, VBoxSDL does indeed
23 only provide a simple window that contains only the "pure" virtual
24 machine, without menus or other controls to click upon and no additional
25 indicators of virtual machine activity:</para>
26
27 <para><mediaobject>
28 <imageobject>
29 <imagedata align="center" fileref="images/vbox-sdl.png"
30 width="10cm" />
31 </imageobject>
32 </mediaobject></para>
33
34 <para>To start a virtual machine with VBoxSDL instead of the VirtualBox
35 GUI, enter the following on a command line:<screen>VBoxSDL --startvm &lt;vm&gt;</screen></para>
36
37 <para>where <computeroutput>&lt;vm&gt;</computeroutput> is, as usual
38 with VirtualBox command line parameters, the name or UUID of an existing
39 virtual machine.</para>
40 </sect2>
41
42 <sect2>
43 <title>Secure labeling with VBoxSDL</title>
44
45 <para>When running guest operating systems in full screen mode, the guest
46 operating system usually has control over the whole screen. This could
47 present a security risk as the guest operating system might fool the
48 user into thinking that it is either a different system (which might
49 have a higher security level) or it might present messages on the screen
50 that appear to stem from the host operating system.</para>
51
52 <para>In order to protect the user against the above mentioned security
53 risks, the secure labeling feature has been developed. Secure labeling
54 is currently available only for VBoxSDL. When enabled, a portion of the
55 display area is reserved for a label in which a user defined message is
56 displayed. The label height in set to 20 pixels in VBoxSDL. The label
57 font color and background color can be optionally set as hexadecimal RGB
58 color values. The following syntax is used to enable secure
59 labeling:</para>
60
61 <screen>VBoxSDL --startvm "VM name"
62 --securelabel --seclabelfnt ~/fonts/arial.ttf
63 --seclabelsiz 14 --seclabelfgcol 00FF00 --seclabelbgcol 00FFFF</screen>
64
65 <para>In addition to enabling secure labeling, a TrueType font has to be
66 supplied. To use another font size than 12 point use the parameter
67 <computeroutput>--seclabelsiz</computeroutput>.</para>
68
69 <para>The label text can be set with <screen>VBoxManage setextradata "VM name" "VBoxSDL/SecureLabel" "The Label"</screen>
70 Changing this label will take effect immediately.</para>
71
72 <para>Typically, full screen resolutions are limited to certain
73 "standard" geometries such as 1024 x 768. Increasing this by twenty
74 lines is not usually feasible, so in most cases, VBoxSDL will chose the
75 next higher resolution, e.g. 1280 x 1024 and the guest's screen will not
76 cover the whole display surface. If VBoxSDL is unable to choose a higher
77 resolution, the secure label will be painted on top of the guest's
78 screen surface. In order to address the problem of the bottom part of
79 the guest screen being hidden, VBoxSDL can provide custom video modes to
80 the guest that are reduced by the height of the label. For Windows
81 guests and recent Solaris and Linux guests, the VirtualBox Guest
82 Additions automatically provide the reduced video modes. Additionally,
83 the VESA BIOS has been adjusted to duplicate its standard mode table
84 with adjusted resolutions. The adjusted mode IDs can be calculated using
85 the following formula:</para>
86
87 <screen>reduced_modeid = modeid + 0x30</screen>
88
89 <para>For example, in order to start Linux with 1024 x 748 x 16, the
90 standard mode 0x117 (1024 x 768 x 16) is used as a base. The Linux video
91 mode kernel parameter can then be calculated using:</para>
92
93 <screen>vga = 0x200 | 0x117 + 0x30
94vga = 839</screen>
95
96 <para>The reason for duplicating the standard modes instead of only
97 supplying the adjusted modes is that most guest operating systems
98 require the standard VESA modes to be fixed and refuse to start with
99 different modes.</para>
100
101 <para>When using the X.org VESA driver, custom modelines have to be
102 calculated and added to the configuration (usually in
103 <literal>/etc/X11/xorg.conf</literal>. A handy tool to determine
104 modeline entries can be found at <literal><ulink
105 url="http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html">http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html</ulink></literal>.)</para>
106 </sect2>
107
108 <sect2>
109 <title>Releasing modifiers with VBoxSDL on Linux</title>
110
111 <para>When switching from a X virtual terminal (VT) to another VT using
112 Ctrl-Alt-Fx while the VBoxSDL window has the input focus, the guest will
113 receive Ctrl and Alt keypress events without receiving the corresponding
114 key release events. This is an architectural limitation of Linux. In
115 order to reset the modifier keys, it is possible to send
116 <computeroutput>SIGUSR1</computeroutput> to the VBoxSDL main thread
117 (first entry in the <computeroutput>ps</computeroutput> list). For
118 example, when switching away to another VT and saving the virtual
119 machine from this terminal, the following sequence can be used to make
120 sure the VM is not saved with stuck modifiers:</para>
121
122 <para><screen>kill -usr1 &lt;pid&gt;
123VBoxManage controlvm "Windows 2000" savestate</screen></para>
124 </sect2>
125 </sect1>
126
127 <sect1>
128 <title id="autologon">Automated guest logons</title>
129
130 <para>VirtualBox provides Guest Addition modules for Windows, Linux and
131 Solaris to enable automated logons on the guest.</para>
132
133 <para>When a guest operating system is running in a virtual machine, it
134 might be desirable to perform coordinated and automated logons using
135 credentials from a master logon system. (With "credentials", we are
136 referring to logon information consisting of user name, password and
137 domain name, where each value might be empty.)</para>
138
139 <sect2 id="autologon_win">
140 <title>Automated Windows guest logons</title>
141
142 <para>Since Windows NT, Windows has provided a modular system logon
143 subsystem ("Winlogon") which can be customized and extended by means of
144 so-called GINA modules (Graphical Identification and Authentication).
145 With Windows Vista and Windows 7, the GINA modules were replaced with a
146 new mechanism called "credential providers". The VirtualBox Guest
147 Additions for Windows come with both, a GINA and a credential provider
148 module, and therefore enable any Windows guest to perform automated
149 logons.</para>
150
151 <para>To activate the VirtualBox GINA or credential provider module,
152 install the Guest Additions with using the command line switch
153 <computeroutput>/with_autologon</computeroutput>. All the following
154 manual steps required for installing these modules will be then done by
155 the installer.</para>
156
157 <para>To manually install the VirtualBox GINA module, extract the Guest
158 Additions (see <xref linkend="windows-guest-file-extraction" />) and
159 copy the file <computeroutput>VBoxGINA.dll</computeroutput> to the
160 Windows <computeroutput>SYSTEM32</computeroutput> directory. Then, in
161 the registry, create the following key: <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen>
162 with a value of <computeroutput>VBoxGINA.dll</computeroutput>.</para>
163
164 <note>
165 <para>The VirtualBox GINA module is implemented as a wrapper around
166 the standard Windows GINA module
167 (<computeroutput>MSGINA.DLL</computeroutput>). As a result, it will
168 most likely not work correctly with 3rd party GINA modules.</para>
169 </note>
170
171 <para>To manually install the VirtualBox credential provider module,
172 extract the Guest Additions (see <xref
173 linkend="windows-guest-file-extraction" />) and copy the file
174 <computeroutput>VBoxCredProv.dll</computeroutput> to the Windows
175 <computeroutput>SYSTEM32</computeroutput> directory. Then, in the
176 registry, create the following keys:<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
177 Authentication\Credential Providers\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
178
179HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
180
181HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32</screen></para>
182
183 <para>with all default values (the key named
184 <computeroutput>(Default)</computeroutput> in each key) set to
185 <computeroutput>VBoxCredProv</computeroutput>. After that a new string
186 named <screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen>
187 with a value of <computeroutput>Apartment</computeroutput> has to be
188 created.</para>
189
190 <para>To set credentials, use the following command on a
191 <emphasis>running</emphasis> VM:</para>
192
193 <screen>VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</screen>
194
195 <para>While the VM is running, the credentials can be queried by the
196 VirtualBox logon modules (GINA or credential provider) using the
197 VirtualBox Guest Additions device driver. When Windows is in "logged
198 out" mode, the logon modules will constantly poll for credentials and if
199 they are present, a logon will be attempted. After retrieving the
200 credentials, the logon modules will erase them so that the above command
201 will have to be repeated for subsequent logons.</para>
202
203 <para>For security reasons, credentials are not stored in any persistent
204 manner and will be lost when the VM is reset. Also, the credentials are
205 "write-only", i.e. there is no way to retrieve the credentials from the
206 host side. Credentials can be reset from the host side by setting empty
207 values.</para>
208
209 <para>Depending on the particular variant of the Windows guest, the
210 following restrictions apply: <orderedlist>
211 <listitem>
212 <para>For <emphasis role="bold">Windows XP guests,</emphasis> the
213 logon subsystem needs to be configured to use the classic logon
214 dialog as the VirtualBox GINA module does not support the XP-style
215 welcome dialog.</para>
216 </listitem>
217
218 <listitem>
219 <para>For <emphasis role="bold">Windows Vista and Windows 7
220 guests,</emphasis> the logon subsystem does not support the
221 so-called Secure Attention Sequence
222 (<computeroutput>CTRL+ALT+DEL</computeroutput>). As a result, the
223 guest's group policy settings need to be changed to not use the
224 Secure Attention Sequence. Also, the user name given is only
225 compared to the true user name, not the user friendly name. This
226 means that when you rename a user, you still have to supply the
227 original user name (internally, Windows never renames user
228 accounts).</para>
229 </listitem>
230
231 <listitem>
232 <para>Auto-logon handling of the built-in Windows Remote Desktop
233 Service (formerly known as Terminal Services) is disabled by
234 default. To enable it, create the registry key <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen>
235 with a <computeroutput>DWORD</computeroutput> value of
236 <computeroutput>1</computeroutput>.</para>
237 </listitem>
238 </orderedlist></para>
239
240 <para>The following command forces VirtualBox to keep the credentials
241 after they were read by the guest and on VM reset: <screen>VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</screen>Note
242 that this is a potential security risk as a malicious application
243 running on the guest could request this information using the proper
244 interface.</para>
245 </sect2>
246
247 <sect2 id="autologon_unix">
248 <title>Automated Linux/Unix guest logons</title>
249
250 <para>Starting with version 3.2, VirtualBox provides a custom PAM module
251 (Pluggable Authentication Module) which can be used to perform automated
252 guest logons on platforms which support this framework. Virtually all
253 modern Linux/Unix distributions rely on PAM.</para>
254
255 <para>The <computeroutput>pam_vbox.so</computeroutput> module itself
256 <emphasis role="bold">does not</emphasis> do an actual verification of
257 the credentials passed to the guest OS; instead it relies on other
258 modules such as <computeroutput>pam_unix.so</computeroutput> or
259 <computeroutput>pam_unix2.so</computeroutput> down in the PAM stack to
260 do the actual validation using the credentials retrieved by
261 <computeroutput>pam_vbox.so</computeroutput>. Therefore
262 <computeroutput>pam_vbox.so</computeroutput> has to be on top of the
263 authentication PAM service list.</para>
264
265 <note>
266 <para>The <computeroutput>pam_vbox.so</computeroutput> only supports
267 the <computeroutput>auth</computeroutput> primitive. Other primitives
268 such as <computeroutput>account</computeroutput>,
269 <computeroutput>session</computeroutput> or
270 <computeroutput>password</computeroutput> are not supported.</para>
271 </note>
272
273 <para>The <computeroutput>pam_vbox.so</computeroutput> module is shipped
274 as part of the Guest Additions but it is not installed and/or activated
275 on the guest OS by default. In order to install it, it has to be copied
276 from
277 <computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/lib/VBoxGuestAdditions/</computeroutput>
278 to the security modules directory, usually
279 <computeroutput>/lib/security/</computeroutput> on 32-bit guest Linuxes
280 or <computeroutput>/lib64/security/</computeroutput> on 64-bit ones.
281 Please refer to your guest OS documentation for the correct PAM module
282 directory.</para>
283
284 <para>For example, to use <computeroutput>pam_vbox.so</computeroutput>
285 with a Ubuntu Linux guest OS and GDM (the GNOME Desktop Manager) to
286 logon users automatically with the credentials passed by the host, the
287 guest OS has to be configured like the following:</para>
288
289 <orderedlist>
290 <listitem>
291 <para>The <computeroutput>pam_vbox.so</computeroutput> module has to
292 be copied to the security modules directory, in this case it is
293 <computeroutput>/lib/security</computeroutput>.</para>
294 </listitem>
295
296 <listitem>
297 <para>Edit the PAM configuration file for GDM found at
298 <computeroutput>/etc/pam.d/gdm</computeroutput>, adding the line
299 <computeroutput>auth requisite pam_vbox.so</computeroutput> at the
300 top. Additionaly, in most Linux distributions there is a file called
301 <computeroutput>/etc/pam.d/common-auth</computeroutput>. This file
302 is included in many other services (like the GDM file mentioned
303 above). There you also have to add the line <computeroutput>auth
304 requisite pam_vbox.so</computeroutput>.</para>
305 </listitem>
306
307 <listitem>
308 <para>If authentication against the shadow database using
309 <computeroutput>pam_unix.so</computeroutput> or
310 <computeroutput>pam_unix2.so</computeroutput> is desired, the
311 argument <computeroutput>try_first_pass</computeroutput> for
312 <computeroutput>pam_unix.so</computeroutput> or
313 <computeroutput>use_first_pass</computeroutput> for
314 <computeroutput>pam_unix2.so</computeroutput> is needed in order to
315 pass the credentials from the VirtualBox module to the shadow
316 database authentication module. For Ubuntu, this needs to be added
317 to <computeroutput>/etc/pam.d/common-auth</computeroutput>, to the
318 end of the line referencing
319 <computeroutput>pam_unix.so</computeroutput>. This argument tells
320 the PAM module to use credentials already present in the stack, i.e.
321 the ones provided by the VirtualBox PAM module.</para>
322 </listitem>
323 </orderedlist>
324
325 <para><warning>
326 <para>An incorrectly configured PAM stack can effectively prevent
327 you from logging into your guest system!</para>
328 </warning></para>
329
330 <para>To make deployment easier, you can pass the argument
331 <computeroutput>debug</computeroutput> right after the
332 <computeroutput>pam_vbox.so</computeroutput> statement. Debug log output
333 will then be recorded using syslog.</para>
334
335 <para><note>
336 <para>By default, pam_vbox will not wait for credentials to arrive
337 from the host, in other words: When a login prompt is shown (for
338 example by GDM/KDM or the text console) and pam_vbox does not yet
339 have credentials it does not wait until they arrive. Instead the
340 next module in the PAM stack (depending on the PAM configuration)
341 will have the chance for authentication.</para>
342 </note></para>
343
344 <para>Starting with VirtualBox 4.1.4 pam_vbox supports various guest
345 property parameters which all reside in
346 <computeroutput>/VirtualBox/GuestAdd/PAM/</computeroutput>. These
347 parameters allow pam_vbox to wait for credentials to be provided by the
348 host and optionally can show a message while waiting for those. The
349 following guest properties can be set:</para>
350
351 <orderedlist>
352 <listitem>
353 <para><computeroutput>CredsWait</computeroutput>: Set to "1" if
354 pam_vbox should start waiting until credentials arrive from the
355 host. Until then no other authentication methods such as manually
356 logging in will be available. If this property is empty or get
357 deleted no waiting for credentials will be performed and pam_vbox
358 will act like before (see paragraph above). This property must be
359 set read-only for the guest
360 (<computeroutput>RDONLYGUEST</computeroutput>).</para>
361 </listitem>
362
363 <listitem>
364 <para><computeroutput>CredsWaitAbort</computeroutput>: Aborts waiting
365 for credentials when set to any value. Can be set from host and the
366 guest.</para>
367 </listitem>
368
369 <listitem>
370 <para><computeroutput>CredsWaitTimeout</computeroutput>: Timeout (in
371 seconds) to let pam_vbox wait for credentials to arrive. When no
372 credentials arrive within this timeout, authentication of pam_vbox
373 will be set to failed and the next PAM module in chain will be
374 asked. If this property is not specified, set to "0" or an invalid
375 value, an infinite timeout will be used. This property must be set
376 read-only for the guest
377 (<computeroutput>RDONLYGUEST</computeroutput>).</para>
378 </listitem>
379 </orderedlist>
380
381 <para>To customize pam_vbox further there are the following guest
382 properties:</para>
383
384 <orderedlist>
385 <listitem>
386 <para><computeroutput>CredsMsgWaiting</computeroutput>: Custom
387 message showed while pam_vbox is waiting for credentials from the
388 host. This property must be set read-only for the guest
389 (<computeroutput>RDONLYGUEST</computeroutput>).</para>
390 </listitem>
391
392 <listitem>
393 <para><computeroutput>CredsMsgWaitTimeout</computeroutput>: Custom
394 message showed when waiting for credentials by pam_vbox timed out,
395 e.g. did not arrive within time. This property must be set read-only
396 for the guest (<computeroutput>RDONLYGUEST</computeroutput>).</para>
397 </listitem>
398 </orderedlist>
399
400 <para><note>
401 <para>If a pam_vbox guest property does not have set the right flags
402 (<computeroutput>RDONLYGUEST</computeroutput>) this property will be
403 ignored then and - depending on the property - a default value will
404 be set. This can result in pam_vbox not waiting for credentials.
405 Consult the appropriate syslog file for more information and use the
406 <computeroutput>debug</computeroutput> option.</para>
407 </note></para>
408 </sect2>
409 </sect1>
410
411 <sect1>
412 <title>Advanced configuration for Windows guests</title>
413
414 <sect2 id="sysprep">
415 <title>Automated Windows system preparation</title>
416
417 <para>Beginning with Windows NT 4.0, Microsoft offers a "system
418 preparation" tool (in short: Sysprep) to prepare a Windows system for
419 deployment or redistribution. Whereas Windows 2000 and XP ship with
420 Sysprep on the installation medium, the tool also is available for
421 download on the Microsoft web site. In a standard installation of
422 Windows Vista and 7, Sysprep is already included. Sysprep mainly
423 consists of an executable called
424 <computeroutput>sysprep.exe</computeroutput> which is invoked by the
425 user to put the Windows installation into preparation mode.</para>
426
427 <para>Starting with VirtualBox 3.2.2, the Guest Additions offer a way to
428 launch a system preparation on the guest operating system in an
429 automated way, controlled from the host system. To achieve that, see
430 <xref linkend="guestadd-guestcontrol" /> for using the feature with the
431 special identifier <computeroutput>sysprep</computeroutput> as the
432 program to execute, along with the user name
433 <computeroutput>sysprep</computeroutput> and password
434 <computeroutput>sysprep</computeroutput> for the credentials. Sysprep
435 then gets launched with the required system rights.</para>
436
437 <note>
438 <para>Specifying the location of "sysprep.exe" is <emphasis
439 role="bold">not possible</emphasis> -- instead the following paths are
440 used (based on the operating system): <itemizedlist>
441 <listitem>
442 <para><computeroutput>C:\sysprep\sysprep.exe</computeroutput>
443 for Windows NT 4.0, 2000 and XP</para>
444 </listitem>
445
446 <listitem>
447 <para><computeroutput>%WINDIR%\System32\Sysprep\sysprep.exe</computeroutput>
448 for Windows Vista, 2008 Server and 7</para>
449 </listitem>
450 </itemizedlist> The Guest Additions will automatically use the
451 appropriate path to execute the system preparation tool.</para>
452 </note>
453 </sect2>
454 </sect1>
455
456 <sect1>
457 <title>Advanced configuration for Linux and Solaris guests</title>
458
459 <sect2>
460 <title>Manual setup of selected guest services on Linux</title>
461
462 <para>The VirtualBox Guest Additions contain several different drivers.
463 If for any reason you do not wish to set them all up, you can install
464 the Guest Additions using the following command:</para>
465
466 <screen> sh ./VBoxLinuxAdditions.run no_setup</screen>
467
468 <para>After this, you will need to at least compile the kernel modules
469 by running the command <screen> /usr/lib/VBoxGuestAdditions/vboxadd setup</screen>
470 as root (you will need to replace <emphasis>lib</emphasis> by
471 <emphasis>lib64</emphasis> on some 64bit guests), and on older guests
472 without the udev service you will need to add the
473 <emphasis>vboxadd</emphasis> service to the default runlevel to ensure
474 that the modules get loaded.</para>
475
476 <para>To setup the time synchronization service, run the command
477 <screen> /usr/lib/VBoxGuestAdditions/vboxadd-service setup</screen> and
478 add the service vboxadd-service to the default runlevel. To set up the
479 X11 and OpenGL part of the Guest Additions, run the command <screen> /usr/lib/VBoxGuestAdditions/vboxadd-x11 setup</screen>
480 (you do not need to enable any services for this).</para>
481
482 <para>To recompile the guest kernel modules, use this command: <screen> /usr/lib/VBoxGuestAdditions/vboxadd setup</screen>
483 After compilation you should reboot your guest to ensure that the new
484 modules are actually used.</para>
485 </sect2>
486
487 <sect2 id="guestxorgsetup">
488 <title>Guest graphics and mouse driver setup in depth</title>
489
490 <para>This section assumes that you are familiar with configuring the
491 X.Org server using xorg.conf and optionally the newer mechanisms using
492 hal or udev and xorg.conf.d. If not you can learn about them by studying
493 the documentation which comes with X.Org.</para>
494
495 <para>The VirtualBox Guest Additions come with drivers for X.Org
496 versions <itemizedlist>
497 <listitem>
498 X11R6.8/X11R6.9 and XFree86 version 4.3 (vboxvideo_drv_68.o and vboxmouse_drv_68.o)
499 </listitem>
500
501 <listitem>
502 X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so)
503 </listitem>
504
505 <listitem>
506 X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so)
507 </listitem>
508
509 <listitem>
510 X.Org Server versions 1.3 and later (vboxvideo_drv_13.so and vboxmouse_drv_13.so and so on).
511 </listitem>
512 </itemizedlist> By default these drivers can be found in the
513 directory</para>
514
515 <para><computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/lib/VBoxGuestAdditions</computeroutput></para>
516
517 <para>and the correct versions for the X server are symbolically linked
518 into the X.Org driver directories.</para>
519
520 <para>For graphics integration to work correctly, the X server must load
521 the vboxvideo driver (many recent X server versions look for it
522 automatically if they see that they are running in VirtualBox) and for
523 an optimal user experience the guest kernel drivers must be loaded and
524 the Guest Additions tool VBoxClient must be running as a client in the X
525 session. For mouse integration to work correctly, the guest kernel
526 drivers must be loaded and in addition, in X servers from X.Org X11R6.8
527 to X11R7.1 and in XFree86 version 4.3 the right vboxmouse driver must be
528 loaded and associated with /dev/mouse or /dev/psaux; in X.Org server 1.3
529 or later a driver for a PS/2 mouse must be loaded and the right
530 vboxmouse driver must be associated with /dev/vboxguest.</para>
531
532 <para>The VirtualBox guest graphics driver can use any graphics
533 configuration for which the virtual resolution fits into the virtual
534 video memory allocated to the virtual machine (minus a small amount used
535 by the guest driver) as described in <xref
536 linkend="settings-display" />. The driver will offer a range of standard
537 modes at least up to the default guest resolution for all active guest
538 monitors. In X.Org Server 1.3 and later the default mode can be changed
539 by setting the output property VBOX_MODE to
540 "&lt;width&gt;x&lt;height&gt;" for any guest monitor. When VBoxClient
541 and the kernel drivers are active this is done automatically when the
542 host requests a mode change. The driver for older versions can only
543 receive new modes by querying the host for requests at regular
544 intervals.</para>
545
546 <para>With pre-1.3 X Servers you can also add your own modes to the X
547 server configuration file. You simply need to add them to the "Modes"
548 list in the "Display" subsection of the "Screen" section. For example,
549 the section shown here has a custom 2048x800 resolution mode
550 added:</para>
551
552 <screen>Section "Screen"
553 Identifier "Default Screen"
554 Device "VirtualBox graphics card"
555 Monitor "Generic Monitor"
556 DefaultDepth 24
557 SubSection "Display"
558 Depth 24
559 Modes "2048x800" "800x600" "640x480"
560 EndSubSection
561EndSection</screen>
562 </sect2>
563 </sect1>
564
565 <sect1 id="cpuhotplug">
566 <title>CPU hot-plugging</title>
567
568 <para>With virtual machines running modern server operating systems,
569 VirtualBox supports CPU hot-plugging.<footnote>
570 <para>Support for CPU hot-plugging was introduced with VirtualBox
571 3.2.</para>
572 </footnote> Whereas on a physical computer this would mean that a CPU
573 can be added or removed while the machine is running, VirtualBox supports
574 adding and removing virtual CPUs while a virtual machine is
575 running.</para>
576
577 <para>CPU hot-plugging works only with guest operating systems that
578 support it. So far this applies only to Linux and Windows Server 2008 x64
579 Data Center Edition. Windows supports only hot-add while Linux supports
580 hot-add and hot-remove but to use this feature with more than 8 CPUs a
581 64bit Linux guest is required.</para>
582
583 <para>At this time, CPU hot-plugging requires using the VBoxManage
584 command-line interface. First, hot-plugging needs to be enabled for a
585 virtual machine:<screen>VBoxManage modifyvm "VM name" --cpuhotplug on</screen></para>
586
587 <para>After that, the --cpus option specifies the maximum number of CPUs
588 that the virtual machine can have:<screen>VBoxManage modifyvm "VM name" --cpus 8</screen>When
589 the VM is off, you can then add and remove virtual CPUs with the modifyvm
590 --plugcpu and --unplugcpu subcommands, which take the number of the
591 virtual CPU as a parameter, like this:<screen>VBoxManage modifyvm "VM name" --plugcpu 3
592VBoxManage modifyvm "VM name" --unplugcpu 3</screen>Note that CPU 0 can never
593 be removed.</para>
594
595 <para>While the VM is running, CPUs can be added with the
596 <computeroutput>controlvm plugcpu/unplugcpu</computeroutput> commands
597 instead:<screen>VBoxManage controlvm "VM name" plugcpu 3
598VBoxManage controlvm "VM name" unplugcpu 3</screen></para>
599
600 <para>See <xref linkend="vboxmanage-modifyvm" /> and <xref
601 linkend="vboxmanage-controlvm" /> for details.</para>
602
603 <para>With Linux guests, the following applies: To prevent ejection while
604 the CPU is still used it has to be ejected from within the guest before.
605 The Linux Guest Additions contain a service which receives hot-remove
606 events and ejects the CPU. Also, after a CPU is added to the VM it is not
607 automatically used by Linux. The Linux Guest Additions service will take
608 care of that if installed. If not a CPU can be started with the following
609 command:<screen>echo 1 &gt; /sys/devices/system/cpu/cpu&lt;id&gt;/online</screen></para>
610 </sect1>
611
612 <sect1 id="pcipassthrough">
613 <title>PCI passthrough</title>
614
615 <para>When running on Linux hosts, with a recent enough kernel (at least
616 version <computeroutput>2.6.31</computeroutput>) experimental host PCI
617 devices passthrough is available.<footnote>
618 <para>Experimental support for PCI passthrough was introduced with
619 VirtualBox 4.1.</para>
620 </footnote></para>
621
622 <note>
623 <para>The PCI passthrough module is shipped as a VirtualBox extension
624 package, which must be installed separately. See <xref
625 linkend="intro-installing" /> for more information.</para>
626 </note>
627
628 <para>Essentially this feature allows to directly use physical PCI devices
629 on the host by the guest even if host doesn't have drivers for this
630 particular device. Both, regular PCI and some PCI Express cards, are
631 supported. AGP and certain PCI Express cards are not supported at the
632 moment if they rely on GART (Graphics Address Remapping Table) unit
633 programming for texture management as it does rather nontrivial operations
634 with pages remapping interfering with IOMMU. This limitation may be lifted
635 in future releases.</para>
636
637 <para>To be fully functional, PCI passthrough support in VirtualBox
638 depends upon an IOMMU hardware unit which is not yet too widely available.
639 If the device uses bus mastering (i.e. it performs DMA to the OS memory on
640 its own), then an IOMMU is required, otherwise such DMA transactions may
641 write to the wrong physical memory address as the device DMA engine is
642 programmed using a device-specific protocol to perform memory
643 transactions. The IOMMU functions as translation unit mapping physical
644 memory access requests from the device using knowledge of the guest
645 physical address to host physical addresses translation rules.</para>
646
647 <para>Intel's solution for IOMMU is marketed as "Intel Virtualization
648 Technology for Directed I/O" (VT-d), and AMD's one is called AMD-Vi. So
649 please check if your motherboard datasheet has appropriate technology.
650 Even if your hardware doesn't have a IOMMU, certain PCI cards may work
651 (such as serial PCI adapters), but the guest will show a warning on boot
652 and the VM execution will terminate if the guest driver will attempt to
653 enable card bus mastering.</para>
654
655 <para>It is very common that the BIOS or the host OS disables the IOMMU by
656 default. So before any attempt to use it please make sure that
657 <orderedlist>
658 <listitem>
659 <para>Your motherboard has an IOMMU unit.</para>
660 </listitem>
661
662 <listitem>
663 <para>Your CPU supports the IOMMU.</para>
664 </listitem>
665
666 <listitem>
667 <para>The IOMMU is enabled in the BIOS.</para>
668 </listitem>
669
670 <listitem>
671 <para>The VM must run with VT-x/AMD-V and nested paging
672 enabled.</para>
673 </listitem>
674
675 <listitem>
676 <para>Your Linux kernel was compiled with IOMMU support (including
677 DMA remapping, see <computeroutput>CONFIG_DMAR</computeroutput>
678 kernel compilation option). The PCI stub driver
679 (<computeroutput>CONFIG_PCI_STUB</computeroutput>) is required as
680 well.</para>
681 </listitem>
682
683 <listitem>
684 <para>Your Linux kernel recognizes and uses the IOMMU unit
685 (<computeroutput>intel_iommu=on</computeroutput> boot option could
686 be needed). Search for DMAR and PCI-DMA in kernel boot log.</para>
687 </listitem>
688 </orderedlist></para>
689
690 <para>Once you made sure that the host kernel supports the IOMMU, the next
691 step is to select the PCI card and attach it to the guest. To figure out
692 the list of available PCI devices, use the
693 <computeroutput>lspci</computeroutput> command. The output will look like
694 this <screen>
695 01:00.0 VGA compatible controller: ATI Technologies Inc Cedar PRO [Radeon HD 5450]
696 01:00.1 Audio device: ATI Technologies Inc Manhattan HDMI Audio [Mobility Radeon HD 5000 Series]
697 02:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168B PCI Express Gigabit Ethernet controller (rev 03)
698 03:00.0 SATA controller: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
699 03:00.1 IDE interface: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
700 06:00.0 VGA compatible controller: nVidia Corporation G86 [GeForce 8500 GT] (rev a1)
701 </screen> The first column is a PCI address (in format
702 <computeroutput>bus:device.function</computeroutput>). This address could
703 be used to identify the device for further operations. For example, to
704 attach a PCI network controller on the system listed above to the second
705 PCI bus in the guest, as device 5, function 0, use the following command:
706 <screen>VBoxManage modifyvm "VM name" --pciattach 02:00.0@01:05.0</screen>
707 To detach same device, use <screen>VBoxManage modifyvm "VM name" --pcidetach 02:00.0</screen>
708 Please note that both host and guest could freely assign a different PCI
709 address to the card attached during runtime, so those addresses only apply
710 to the address of the card at the moment of attachment (host), and during
711 BIOS PCI init (guest).</para>
712
713 <para>If the virtual machine has a PCI device attached, certain
714 limitations apply: <orderedlist>
715 <listitem>
716 Only PCI cards with non-shared interrupts (such as using MSI on host) are supported at the moment.
717 </listitem>
718
719 <listitem>
720 No guest state can be reliably saved/restored (as the internal state of the PCI card could not be retrieved).
721 </listitem>
722
723 <listitem>
724 Teleportation (live migration) doesn't work (for the same reason).
725 </listitem>
726
727 <listitem>
728 No lazy physical memory allocation. The host will preallocate the whole RAM required for the VM on startup (as we cannot catch physical hardware accesses to the physical memory).
729 </listitem>
730 </orderedlist></para>
731 </sect1>
732
733 <sect1>
734 <title>Advanced display configuration</title>
735
736 <sect2>
737 <title>Custom VESA resolutions</title>
738
739 <para>Apart from the standard VESA resolutions, the VirtualBox VESA BIOS
740 allows you to add up to 16 custom video modes which will be reported to
741 the guest operating system. When using Windows guests with the
742 VirtualBox Guest Additions, a custom graphics driver will be used
743 instead of the fallback VESA solution so this information does not
744 apply.</para>
745
746 <para>Additional video modes can be configured for each VM using the
747 extra data facility. The extra data key is called
748 <literal>CustomVideoMode&lt;x&gt;</literal> with <literal>x</literal>
749 being a number from 1 to 16. Please note that modes will be read from 1
750 until either the following number is not defined or 16 is reached. The
751 following example adds a video mode that corresponds to the native
752 display resolution of many notebook computers:</para>
753
754 <screen>VBoxManage setextradata "VM name" "CustomVideoMode1" "1400x1050x16"</screen>
755
756 <para>The VESA mode IDs for custom video modes start at
757 <literal>0x160</literal>. In order to use the above defined custom video
758 mode, the following command line has be supplied to Linux:</para>
759
760 <screen>vga = 0x200 | 0x160
761vga = 864</screen>
762
763 <para>For guest operating systems with VirtualBox Guest Additions, a
764 custom video mode can be set using the video mode hint feature.</para>
765 </sect2>
766
767 <sect2>
768 <title>Configuring the maximum resolution of guests when using the
769 graphical frontend</title>
770
771 <para>When guest systems with the Guest Additions installed are started
772 using the graphical frontend (the normal VirtualBox application), they
773 will not be allowed to use screen resolutions greater than the host's
774 screen size unless the user manually resizes them by dragging the
775 window, switching to full screen or seamless mode or sending a video mode
776 hint using VBoxManage. This behavior is what most users will want, but
777 if you have different needs, it is possible to change it by issuing one
778 of the following commands from the command line:</para>
779
780 <screen>VBoxManage setextradata global GUI/MaxGuestResolution any</screen>
781
782 <para>will remove all limits on guest resolutions.</para>
783
784 <screen>VBoxManage setextradata global GUI/MaxGuestResolution &gt;width,height&lt;</screen>
785
786 <para>manually specifies a maximum resolution.</para>
787
788 <screen>VBoxManage setextradata global GUI/MaxGuestResolution auto</screen>
789
790 <para>restores the default settings. Note that these settings apply
791 globally to all guest systems, not just to a single machine.</para>
792 </sect2>
793 </sect1>
794
795 <sect1>
796 <title>Advanced storage configuration</title>
797
798 <sect2 id="rawdisk">
799 <title>Using a raw host hard disk from a guest</title>
800
801 <para>Starting with version 1.4, as an alternative to using virtual disk
802 images (as described in detail in <xref linkend="storage" />),
803 VirtualBox can also present either entire physical hard disks or
804 selected partitions thereof as virtual disks to virtual machines.</para>
805
806 <para>With VirtualBox, this type of access is called "raw hard disk
807 access"; it allows a guest operating system to access its virtual hard
808 disk without going through the host OS file system. The actual
809 performance difference for image files vs. raw disk varies greatly
810 depending on the overhead of the host file system, whether dynamically
811 growing images are used, and on host OS caching strategies. The caching
812 indirectly also affects other aspects such as failure behavior, i.e.
813 whether the virtual disk contains all data written before a host OS
814 crash. Consult your host OS documentation for details on this.</para>
815
816 <para><warning>
817 <para>Raw hard disk access is for expert users only. Incorrect use
818 or use of an outdated configuration can lead to <emphasis
819 role="bold">total loss of data </emphasis>on the physical disk. Most
820 importantly, <emphasis>do not</emphasis> attempt to boot the
821 partition with the currently running host operating system in a
822 guest. This will lead to severe data corruption.</para>
823 </warning></para>
824
825 <para>Raw hard disk access -- both for entire disks and individual
826 partitions -- is implemented as part of the VMDK image format support.
827 As a result, you will need to create a special VMDK image file which
828 defines where the data will be stored. After creating such a special
829 VMDK image, you can use it like a regular virtual disk image. For
830 example, you can use the VirtualBox Manager (<xref linkend="vdis" />)
831 or <computeroutput>VBoxManage</computeroutput> to assign the image to a
832 virtual machine.</para>
833
834 <sect3>
835 <title>Access to entire physical hard disk</title>
836
837 <para>While this variant is the simplest to set up, you must be aware
838 that this will give a guest operating system direct and full access to
839 an <emphasis>entire physical disk</emphasis>. If your
840 <emphasis>host</emphasis> operating system is also booted from this
841 disk, please take special care to not access the partition from the
842 guest at all. On the positive side, the physical disk can be
843 repartitioned in arbitrary ways without having to recreate the image
844 file that gives access to the raw disk.</para>
845
846 <para>To create an image that represents an entire physical hard disk
847 (which will not contain any actual data, as this will all be stored on
848 the physical disk), on a Linux host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
849 -rawdisk /dev/sda</screen>This creates the image
850 <code>/path/to/file.vmdk</code> (must be absolute), and all data will
851 be read and written from <code>/dev/sda</code>.</para>
852
853 <para>On a Windows host, instead of the above device specification,
854 use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host, instead
855 of the above device specification use e.g. <code>/dev/disk1</code>.
856 Note that on OS X you can only get access to an entire disk if no
857 volume is mounted from it.</para>
858
859 <para>Creating the image requires read/write access for the given
860 device. Read/write access is also later needed when using the image
861 from a virtual machine. On some host platforms (e.g. Windows Vista
862 and later), raw disk access may be restricted and not permitted by
863 the host OS in some situations.</para>
864
865 <para>Just like with regular disk images, this does not automatically
866 attach the newly created image to a virtual machine. This can be done
867 with e.g. <screen>VBoxManage storageattach WindowsXP --storagectl "IDE Controller"
868 --port 0 --device 0 --type hdd --medium /path/to/file.vmdk</screen>When
869 this is done the selected virtual machine will boot from the specified
870 physical disk.</para>
871 </sect3>
872
873 <sect3>
874 <title>Access to individual physical hard disk partitions</title>
875
876 <para>This "raw partition support" is quite similar to the "full hard
877 disk" access described above. However, in this case, any partitioning
878 information will be stored inside the VMDK image, so you can e.g.
879 install a different boot loader in the virtual hard disk without
880 affecting the host's partitioning information. While the guest will be
881 able to <emphasis>see</emphasis> all partitions that exist on the
882 physical disk, access will be filtered in that reading from partitions
883 for which no access is allowed the partitions will only yield zeroes,
884 and all writes to them are ignored.</para>
885
886 <para>To create a special image for raw partition support (which will
887 contain a small amount of data, as already mentioned), on a Linux
888 host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
889 -rawdisk /dev/sda -partitions 1,5</screen></para>
890
891 <para>As you can see, the command is identical to the one for "full
892 hard disk" access, except for the additional
893 <computeroutput>-partitions</computeroutput> parameter. This example
894 would create the image <code>/path/to/file.vmdk</code> (which, again,
895 must be absolute), and partitions 1 and 5 of <code>/dev/sda</code>
896 would be made accessible to the guest.</para>
897
898 <para>VirtualBox uses the same partition numbering as your Linux host.
899 As a result, the numbers given in the above example would refer to the
900 first primary partition and the first logical drive in the extended
901 partition, respectively.</para>
902
903 <para>On a Windows host, instead of the above device specification,
904 use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host, instead
905 of the above device specification use e.g. <code>/dev/disk1</code>.
906 Note that on OS X you can only use partitions which are not mounted
907 (eject the respective volume first). Partition numbers are the same on
908 Linux, Windows and Mac OS X hosts.</para>
909
910 <para>The numbers for the list of partitions can be taken from the
911 output of<screen>VBoxManage internalcommands listpartitions -rawdisk /dev/sda</screen>The
912 output lists the partition types and sizes to give the user enough
913 information to identify the partitions necessary for the guest.</para>
914
915 <para>Images which give access to individual partitions are specific
916 to a particular host disk setup. You cannot transfer these images to
917 another host; also, whenever the host partitioning changes, the image
918 <emphasis>must be recreated</emphasis>.</para>
919
920 <para>Creating the image requires read/write access for the given
921 device. Read/write access is also later needed when using the image
922 from a virtual machine. If this is not feasible, there is a special
923 variant for raw partition access (currently only available on Linux
924 hosts) that avoids having to give the current user access to the
925 entire disk. To set up such an image, use<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
926 -rawdisk /dev/sda -partitions 1,5 -relative</screen>When used from a
927 virtual machine, the image will then refer not to the entire disk, but
928 only to the individual partitions (in the example
929 <code>/dev/sda1</code> and <code>/dev/sda5</code>). As a consequence,
930 read/write access is only required for the affected partitions, not
931 for the entire disk. During creation however, read-only access to the
932 entire disk is required to obtain the partitioning information.</para>
933
934 <para>In some configurations it may be necessary to change the MBR
935 code of the created image, e.g. to replace the Linux boot loader that
936 is used on the host by another boot loader. This allows e.g. the guest
937 to boot directly to Windows, while the host boots Linux from the
938 "same" disk. For this purpose the
939 <computeroutput>-mbr</computeroutput> parameter is provided. It
940 specifies a file name from which to take the MBR code. The partition
941 table is not modified at all, so a MBR file from a system with totally
942 different partitioning can be used. An example of this is<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
943 -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr</screen>The modified
944 MBR will be stored inside the image, not on the host disk.</para>
945
946 <para>The created image can be attached to a storage controller in a
947 VM configuration as usual.</para>
948 </sect3>
949 </sect2>
950
951 <sect2 id="changevpd">
952 <title>Configuring the hard disk vendor product data (VPD)</title>
953
954 <para>VirtualBox reports vendor product data for its virtual hard disks
955 which consist of hard disk serial number, firmware revision and model
956 number. These can be changed using the following commands:</para>
957
958 <screen>VBoxManage setextradata "VM name"
959 "VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial"
960VBoxManage setextradata "VM name"
961 "VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware"
962VBoxManage setextradata "VM name"
963 "VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model"</screen>
964
965 <para>The serial number is a 20 byte alphanumeric string, the firmware
966 revision an 8 byte alphanumeric string and the model number a 40 byte
967 alphanumeric string. Instead of "Port0" (referring to the first port),
968 specify the desired SATA hard disk port.</para>
969
970 <para>The above commands apply to virtual machines with an AHCI (SATA)
971 controller. The commands for virtual machines with an IDE controller
972 are:</para>
973
974 <screen>VBoxManage setextradata "VM name"
975 "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial"
976VBoxManage setextradata "VM name"
977 "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware"
978VBoxManage setextradata "VM name"
979 "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model"</screen>
980
981 <para>For hard disks it's also possible to mark the
982 drive as having a non-rotational medium with:</para>
983
984 <screen>VBoxManage setextradata "VM name"
985 "VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1"</screen>
986
987 <para>Additional three parameters are needed for CD/DVD drives to report
988 the vendor product data:</para>
989
990 <screen>VBoxManage setextradata "VM name"
991 "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor"
992VBoxManage setextradata "VM name"
993 "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product"
994VBoxManage setextradata "VM name"
995 "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIRevision" "revision"</screen>
996
997 <para>The vendor id is an 8 byte alphanumeric string, the product id an
998 16 byte alphanumeric string and the revision a 4 byte alphanumeric
999 string. Instead of "Port0" (referring to the first port), specify the
1000 desired SATA hard disk port.</para>
1001 </sect2>
1002
1003 <sect2>
1004 <title id="iscsi-intnet">Access iSCSI targets via Internal
1005 Networking</title>
1006
1007 <para>As an experimental feature, VirtualBox allows for accessing an
1008 iSCSI target running in a virtual machine which is configured for using
1009 Internal Networking mode. Please see <xref linkend="storage-iscsi" />;
1010 <xref linkend="network_internal" />; and <xref
1011 linkend="vboxmanage-storageattach" /> for additional information.</para>
1012
1013 <para>The IP stack accessing Internal Networking must be configured in
1014 the virtual machine which accesses the iSCSI target. A free static IP
1015 and a MAC address not used by other virtual machines must be chosen. In
1016 the example below, adapt the name of the virtual machine, the MAC
1017 address, the IP configuration and the Internal Networking name
1018 ("MyIntNet") according to your needs. The following seven commands must
1019 first be issued:<screen>VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Trusted 1
1020VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f
1021VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1
1022VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0
1023VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet
1024VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet
1025VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen></para>
1026
1027 <para>Finally the iSCSI disk must be attached with the
1028 <computeroutput>--intnet</computeroutput> option to tell the iSCSI
1029 initiator to use internal networking:<screen>VBoxManage storageattach ... --medium iscsi
1030 --server 10.0.9.30 --target iqn.2008-12.com.sun:sampletarget --intnet</screen></para>
1031
1032 <para>Compared to a "regular" iSCSI setup, IP address of the target
1033 <emphasis>must</emphasis> be specified as a numeric IP address, as there
1034 is no DNS resolver for internal networking.</para>
1035
1036 <para>The virtual machine with the iSCSI target should be started before
1037 the VM using it is powered on. If a virtual machine using an iSCSI disk
1038 is started without having the iSCSI target powered up, it can take up to
1039 200 seconds to detect this situation. The VM will fail to power
1040 up.</para>
1041 </sect2>
1042 </sect1>
1043
1044 <sect1>
1045 <title>Launching more than 128 VMs on Linux hosts</title>
1046
1047 <para>Linux hosts have a fixed number of IPC semaphores IDs per process
1048 preventing users from starting substantially many VMs. The exact number
1049 may vary with each Linux distribution. While trying to launch more VMs you
1050 would be shown a "Cannot create IPC semaphore" error. In order to run more
1051 VMs, you will need to increase the semaphore ID limit of the VBoxSVC
1052 process. Find the current semaphore limits imposed by the kernel by
1053 executing as root:<screen>#/sbin/sysctl kernel.sem
1054kernel.sem = 250 32000 32 128</screen></para>
1055
1056 <para>The "kernel.sem" parameter bundles together 4 values, the one we are
1057 interested in is called "SEMMNI", the maximum number of semaphore IDs
1058 which is 128 in the above example. Increase this semaphore ID limit by
1059 executing as root:<screen>echo "kernel.sem = 250 32000 32 2048" &gt;&gt; /etc/sysctl.conf
1060/sbin/sysctl -p</screen></para>
1061
1062 <para>The above commands will add the new limits to the config file, thus
1063 making the effect persistent across reboots, and will activate the new
1064 limits into the currently running kernel.</para>
1065 </sect1>
1066
1067 <sect1>
1068 <title>Launching more than 120 VMs on Solaris hosts</title>
1069
1070 <para>Solaris hosts have a fixed number of IPC semaphores IDs per process
1071 preventing users from starting more than 120 VMs. While trying to launch
1072 more VMs you would be shown a "Cannot create IPC semaphore" error. In
1073 order to run more VMs, you will need to increase the semaphore ID limit of
1074 the VBoxSVC process.</para>
1075
1076 <sect2>
1077 <title>Temporary solution while VirtualBox is running</title>
1078
1079 <para>Execute as root the <computeroutput>prctl</computeroutput> command
1080 as shown below for the currently running VBoxSVC process. The process ID
1081 of VBoxSVC can be obtained using the <computeroutput>ps</computeroutput>
1082 command.</para>
1083
1084 <screen>prctl -r -n project.max-sem-ids -v 2048 &lt;pid-of-VBoxSVC&gt;</screen>
1085
1086 <para>This will immediately increase the semaphore limit of the
1087 currently running VBoxSVC process and allow you to launch more VMs.
1088 However, this change is not persistent and will be lost when VBoxSVC
1089 terminates.</para>
1090 </sect2>
1091
1092 <sect2>
1093 <title>Persistent solution, requires user to re-login</title>
1094
1095 <para>If the user running VirtualBox is root, execute the following
1096 command:</para>
1097
1098 <screen>prctl -n project.max-sem-ids -v 2048 -r -i project user.root</screen>
1099
1100 <para>From this point, starting new processes will have the increased
1101 limit of 2048. You may then re-login or close all VMs and restart
1102 VBoxSVC. You can check the current VBoxSVC semaphore ID limit using the
1103 following command:</para>
1104
1105 <screen>prctl -n project.max-sem-ids -i process &lt;pid-of-VBoxSVC&gt;</screen>
1106
1107 <para>If the user running VirtualBox is not root, you must add the
1108 property to the user's default project. Create the default project and
1109 set the limit by executing as root:</para>
1110
1111 <screen>projadd -U &lt;username&gt; user.&lt;username&gt;
1112projmod -s -K "project.max-sem-ids=(priv,2048,deny)" user.&lt;username&gt;</screen>
1113
1114 <para>Substitute "&lt;username&gt;" with the name of the user running
1115 VirtualBox. Then re-login as this user to be able to run more than 120
1116 VMs.</para>
1117 </sect2>
1118 </sect1>
1119
1120 <sect1>
1121 <title>Legacy commands for using serial ports</title>
1122
1123 <para>Starting with version 1.4, VirtualBox provided support for virtual
1124 serial ports, which, at the time, was rather complicated to set up with a
1125 sequence of <computeroutput>VBoxManage setextradata</computeroutput>
1126 statements. Since version 1.5, that way of setting up serial ports is no
1127 longer necessary and <emphasis>deprecated.</emphasis> To set up virtual
1128 serial ports, use the methods now described in <xref
1129 linkend="serialports" />.<note>
1130 <para>For backwards compatibility, the old
1131 <computeroutput>setextradata</computeroutput> statements, whose
1132 description is retained below from the old version of the manual, take
1133 <emphasis>precedence</emphasis> over the new way of configuring serial
1134 ports. As a result, if configuring serial ports the new way doesn't
1135 work, make sure the VM in question does not have old configuration
1136 data such as below still active.</para>
1137 </note></para>
1138
1139 <para>The old sequence of configuring a serial port used the following 6
1140 commands:</para>
1141
1142 <screen>VBoxManage setextradata "VM name"
1143 "VBoxInternal/Devices/serial/0/Config/IRQ" 4
1144VBoxManage setextradata "VM name"
1145 "VBoxInternal/Devices/serial/0/Config/IOBase" 0x3f8
1146VBoxManage setextradata "VM name"
1147 "VBoxInternal/Devices/serial/0/LUN#0/Driver" Char
1148VBoxManage setextradata "VM name"
1149 "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Driver" NamedPipe
1150VBoxManage setextradata "VM name"
1151 "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/Location" "\\.\pipe\vboxCOM1"
1152VBoxManage setextradata "VM name"
1153 "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/IsServer" 1</screen>
1154
1155 <para>This sets up a serial port in the guest with the default settings
1156 for COM1 (IRQ 4, I/O address 0x3f8) and the
1157 <computeroutput>Location</computeroutput> setting assumes that this
1158 configuration is used on a Windows host, because the Windows named pipe
1159 syntax is used. Keep in mind that on Windows hosts a named pipe must
1160 always start with <computeroutput>\\.\pipe\</computeroutput>. On Linux the
1161 same config settings apply, except that the path name for the
1162 <computeroutput>Location</computeroutput> can be chosen more freely. Local
1163 domain sockets can be placed anywhere, provided the user running
1164 VirtualBox has the permission to create a new file in the directory. The
1165 final command above defines that VirtualBox acts as a server, i.e. it
1166 creates the named pipe itself instead of connecting to an already existing
1167 one.</para>
1168 </sect1>
1169
1170 <sect1 id="changenat">
1171 <title>Fine-tuning the VirtualBox NAT engine</title>
1172
1173 <sect2>
1174 <title>Configuring the address of a NAT network interface</title>
1175
1176 <para>In NAT mode, the guest network interface is assigned to the IPv4
1177 range <computeroutput>10.0.x.0/24</computeroutput> by default where
1178 <computeroutput>x</computeroutput> corresponds to the instance of the
1179 NAT interface +2. So <computeroutput>x</computeroutput> is 2 when there
1180 is only one NAT instance active. In that case the guest is assigned to
1181 the address <computeroutput>10.0.2.15</computeroutput>, the gateway is
1182 set to <computeroutput>10.0.2.2</computeroutput> and the name server can
1183 be found at <computeroutput>10.0.2.3</computeroutput>.</para>
1184
1185 <para>If, for any reason, the NAT network needs to be changed, this can
1186 be achieved with the following command:</para>
1187
1188 <screen>VBoxManage modifyvm "VM name" --natnet1 "192.168/16"</screen>
1189
1190 <para>This command would reserve the network addresses from
1191 <computeroutput>192.168.0.0</computeroutput> to
1192 <computeroutput>192.168.254.254</computeroutput> for the first NAT
1193 network instance of "VM name". The guest IP would be assigned to
1194 <computeroutput>192.168.0.15</computeroutput> and the default gateway
1195 could be found at <computeroutput>192.168.0.2</computeroutput>.</para>
1196 </sect2>
1197
1198 <sect2 id="nat-adv-tftp">
1199 <title>Configuring the boot server (next server) of a NAT network
1200 interface</title>
1201
1202 <para>For network booting in NAT mode, by default VirtualBox uses a
1203 built-in TFTP server at the IP address 10.0.2.3. This default behavior
1204 should work fine for typical remote-booting scenarios. However, it is
1205 possible to change the boot server IP and the location of the boot image
1206 with the following commands: <screen>VBoxManage modifyvm "VM name" --nattftpserver1 10.0.2.2
1207VBoxManage modifyvm "VM name" --nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</screen></para>
1208 </sect2>
1209
1210 <sect2 id="nat-adv-settings">
1211 <title>Tuning TCP/IP buffers for NAT</title>
1212
1213 <para>The VirtualBox NAT stack performance is often determined by its
1214 interaction with the host's TCP/IP stack and the size of several buffers
1215 (<computeroutput>SO_RCVBUF</computeroutput> and
1216 <computeroutput>SO_SNDBUF</computeroutput>). For certain setups users
1217 might want to adjust the buffer size for a better performance. This can
1218 by achieved using the following commands (values are in kilobytes and
1219 can range from 8 to 1024): <screen>VBoxManage modifyvm "VM name" --natsettings1 16000,128,128,0,0</screen>
1220 This example illustrates tuning the NAT settings. The first parameter is
1221 the MTU, then the size of the socket's send buffer and the size of the
1222 socket's receive buffer, the initial size of the TCP send window, and
1223 lastly the initial size of the TCP receive window. Note that specifying
1224 zero means fallback to the default value.</para>
1225
1226 <para>Each of these buffers has a default size of 64KB and default MTU
1227 is 1500.</para>
1228 </sect2>
1229
1230 <sect2>
1231 <title>Binding NAT sockets to a specific interface</title>
1232
1233 <para>By default, VirtualBox's NAT engine will route TCP/IP packets
1234 through the default interface assigned by the host's TCP/IP stack. (The
1235 technical reason for this is that the NAT engine uses sockets for
1236 communication.) If, for some reason, you want to change this behavior,
1237 you can tell the NAT engine to bind to a particular IP address instead.
1238 Use the following command: <screen>VBoxManage modifyvm "VM name" --natbindip1 "10.45.0.2"</screen></para>
1239
1240 <para>After this, all outgoing traffic will be sent through the
1241 interface with the IP address 10.45.0.2. Please make sure that this
1242 interface is up and running prior to this assignment.</para>
1243 </sect2>
1244
1245 <sect2 id="nat-adv-dns">
1246 <title>Enabling DNS proxy in NAT mode</title>
1247
1248 <para>The NAT engine by default offers the same DNS servers to the guest
1249 that are configured on the host. In some scenarios, it can be desirable
1250 to hide the DNS server IPs from the guest, for example when this
1251 information can change on the host due to expiring DHCP leases. In this
1252 case, you can tell the NAT engine to act as DNS proxy using the
1253 following command: <screen>VBoxManage modifyvm "VM name" --natdnsproxy1 on</screen></para>
1254 </sect2>
1255
1256 <sect2 id="nat_host_resolver_proxy">
1257 <title>Using the host's resolver as a DNS proxy in NAT mode</title>
1258
1259 <para>For resolving network names, the DHCP server of the NAT engine
1260 offers a list of registered DNS servers of the host. If for some reason
1261 you need to hide this DNS server list and use the host's resolver
1262 settings, thereby forcing the VirtualBox NAT engine to intercept DNS
1263 requests and forward them to host's resolver, use the following command:
1264 <screen>VBoxManage modifyvm "VM name" --natdnshostresolver1 on</screen>
1265 Note that this setting is similar to the DNS proxy mode, however whereas
1266 the proxy mode just forwards DNS requests to the appropriate servers,
1267 the resolver mode will interpret the DNS requests and use the host's DNS
1268 API to query the information and return it to the guest.</para>
1269
1270 <sect3 id="nat_host_resolver_name_intercepting">
1271 <title>User-defined host name resolving</title>
1272 <para>In some cases it might be useful to intercept the name resolving mechanism,
1273 providing a user-defined IP address on a particular DNS request. The intercepting
1274 mechanism allows the user to map not only a single host but domains and even more
1275 complex namings conventions if required.</para>
1276 <para>
1277 The following command sets a rule for mapping a name to a specified IP:</para>
1278 <screen>VBoxManage setextradata "VM name" \
1279 "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
1280 &lt;uniq name of interception rule&gt;/HostIP" &lt;IPv4&gt;
1281VBoxManage setextradata "VM name" \
1282 "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
1283 &lt;uniq name of interception rule&gt;/HostName" &lt;name of host&gt;</screen>
1284 <para>The following command sets a rule for mapping a pattern name to a specified IP:</para>
1285 <screen>VBoxManage setextradata "VM name" \
1286 "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
1287 &lt;uniq name of interception rule&gt;/HostIP" &lt;IPv4&gt;
1288VBoxManage setextradata "VM name" \
1289 "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
1290 &lt;uniq name of interception rule&gt;/HostNamePattern" &lt;hostpattern&gt;</screen>
1291 <para>The host pattern may include <computeroutput>"|", "?" and "*"</computeroutput>.</para>
1292 <para>This example demonstrates how to instruct the host-resolver mechanism to resolve
1293 all domain and probably some mirrors of www.blocked-site.info site with IP 127.0.0.1:</para>
1294 <screen>VBoxManage setextradata "VM name" \
1295 "VBoxInternal/Devices/e1000/0/LUN#0/Config/HostResolverMappings/ \
1296 all_blocked_site/HostIP" 127.0.0.1
1297VBoxManage setextradata "VM name" \
1298 "VBoxInternal/Devices/e1000/0/LUN#0/Config/HostResolverMappings/ \
1299 all_blocked_site/HostNamePattern" "*.blocked-site.*|*.fb.org"</screen>
1300 <note><para>The host resolver mechanism should be enabled to use user-defined
1301 mapping rules (please see
1302 <xref linkend="nat_host_resolver_proxy" /> for more details).</para></note>
1303 </sect3>
1304 </sect2>
1305
1306 <sect2 id="nat-adv-alias">
1307 <title>Configuring aliasing of the NAT engine</title>
1308
1309 <para>By default, the NAT core uses aliasing and uses random ports when
1310 generating an alias for a connection. This works well for the most
1311 protocols like SSH, FTP and so on. Though some protocols might need a
1312 more transparent behavior or may depend on the real port number the
1313 packet was sent from. It is possible to change the NAT mode via the
1314 VBoxManage frontend with the following commands: <screen>VBoxManage modifyvm "VM name" --nataliasmode1 proxyonly</screen>
1315 and <screen>VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</screen>
1316 The first example disables aliasing and switches NAT into transparent
1317 mode, the second example enforces preserving of port values. These modes
1318 can be combined if necessary.</para>
1319 </sect2>
1320 </sect1>
1321
1322 <sect1 id="changedmi">
1323 <title>Configuring the BIOS DMI information</title>
1324
1325 <para>The DMI data VirtualBox provides to guests can be changed for a
1326 specific VM. Use the following commands to configure the DMI BIOS
1327 information:</para>
1328
1329 <screen>VBoxManage setextradata "VM name"
1330 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor" "BIOS Vendor"
1331VBoxManage setextradata "VM name"
1332 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion" "BIOS Version"
1333VBoxManage setextradata "VM name"
1334 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate" "BIOS Release Date"
1335VBoxManage setextradata "VM name"
1336 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor" 1
1337VBoxManage setextradata "VM name"
1338 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor" 2
1339VBoxManage setextradata "VM name"
1340 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3
1341VBoxManage setextradata "VM name"
1342 "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4
1343VBoxManage setextradata "VM name"
1344 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor" "System Vendor"
1345VBoxManage setextradata "VM name"
1346 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct" "System Product"
1347VBoxManage setextradata "VM name"
1348 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion" "System Version"
1349VBoxManage setextradata "VM name"
1350 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "System Serial"
1351VBoxManage setextradata "VM name"
1352 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU" "System SKU"
1353VBoxManage setextradata "VM name"
1354 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily" "System Family"
1355VBoxManage setextradata "VM name"
1356 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid"
1357 "9852bf98-b83c-49db-a8de-182c42c7226b"</screen>
1358
1359 <para>If a DMI string is not set, the default value of VirtualBox is used.
1360 To set an empty string use
1361 <computeroutput>"&lt;EMPTY&gt;"</computeroutput>.</para>
1362
1363 <para>Note that in the above list, all quoted parameters (DmiBIOSVendor,
1364 DmiBIOSVersion but not DmiBIOSReleaseMajor) are expected to be strings. If
1365 such a string is a valid number, the parameter is treated as number and
1366 the VM will most probably refuse to start with an
1367 <computeroutput>VERR_CFGM_NOT_STRING</computeroutput> error. In that case,
1368 use <computeroutput>"string:&lt;value&gt;"</computeroutput>, for instance
1369 <screen>VBoxManage setextradata "VM name"
1370 "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "string:1234"</screen></para>
1371
1372 <para>Changing this information can be necessary to provide the DMI
1373 information of the host to the guest to prevent Windows from asking for a
1374 new product key. On Linux hosts the DMI BIOS information can be obtained
1375 with <screen>dmidecode -t0</screen>and the DMI system information can be
1376 obtained with <screen>dmidecode -t1</screen></para>
1377 </sect1>
1378
1379 <sect1 id="changeacpicust">
1380 <title>Configuring the custom ACPI table</title>
1381
1382 <para>VirtualBox can be configured to present an custom ACPI table to
1383 the guest. Use the following command to configure this:</para>
1384
1385 <screen>VBoxManage setextradata "VM name"
1386 "VBoxInternal/Devices/acpi/0/Config/CustomTable" "/path/to/table.bin"</screen>
1387
1388 <para>Configuring a custom ACPI table can prevent Windows
1389 Vista and Windows 7 from asking for a new product key. On Linux hosts,
1390 one of the host tables can be read from
1391 <filename>/sys/firmware/acpi/tables/</filename>.</para>
1392 </sect1>
1393
1394 <sect1>
1395 <title>Fine-tuning timers and time synchronization</title>
1396
1397 <sect2 id="changetscmode">
1398 <title>Configuring the guest time stamp counter (TSC) to reflect guest
1399 execution</title>
1400
1401 <para>By default, VirtualBox keeps all sources of time visible to the
1402 guest synchronized to a single time source, the monotonic host time.
1403 This reflects the assumptions of many guest operating systems, which
1404 expect all time sources to reflect "wall clock" time. In special
1405 circumstances it may be useful however to make the TSC (time stamp
1406 counter) in the guest reflect the time actually spent executing the
1407 guest.</para>
1408
1409 <para>This special TSC handling mode can be enabled on a per-VM basis,
1410 and for best results must be used only in combination with hardware
1411 virtualization. To enable this mode use the following command:</para>
1412
1413 <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution" 1</screen>
1414
1415 <para>To revert to the default TSC handling mode use:</para>
1416
1417 <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution"</screen>
1418
1419 <para>Note that if you use the special TSC handling mode with a guest
1420 operating system which is very strict about the consistency of time
1421 sources you may get a warning or error message about the timing
1422 inconsistency. It may also cause clocks to become unreliable with some
1423 guest operating systems depending on how they use the TSC.</para>
1424 </sect2>
1425
1426 <sect2 id="warpguest">
1427 <title>Accelerate or slow down the guest clock</title>
1428
1429 <para>For certain purposes it can be useful to accelerate or to slow
1430 down the (virtual) guest clock. This can be achieved as follows:</para>
1431
1432 <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 200</screen>
1433
1434 <para>The above example will double the speed of the guest clock
1435 while</para>
1436
1437 <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 50</screen>
1438
1439 <para>will halve the speed of the guest clock. Note that changing the
1440 rate of the virtual clock can confuse the guest and can even lead to
1441 abnormal guest behavior. For instance, a higher clock rate means shorter
1442 timeouts for virtual devices with the result that a slightly increased
1443 response time of a virtual device due to an increased host load can
1444 cause guest failures. Note further that any time synchronization
1445 mechanism will frequently try to resynchronize the guest clock with the
1446 reference clock (which is the host clock if the VirtualBox Guest
1447 Additions are active). Therefore any time synchronization should be
1448 disabled if the rate of the guest clock is changed as described above
1449 (see <xref linkend="changetimesync" />).</para>
1450 </sect2>
1451
1452 <sect2 id="changetimesync">
1453 <title>Tuning the Guest Additions time synchronization
1454 parameters</title>
1455
1456 <para>The VirtualBox Guest Additions ensure that the guest's system time
1457 is synchronized with the host time. There are several parameters which
1458 can be tuned. The parameters can be set for a specific VM using the
1459 following command:</para>
1460
1461 <screen>VBoxManage guestproperty set "VM name" "/VirtualBox/GuestAdd/VBoxService/PARAMETER" VALUE</screen>
1462
1463 <para>where <computeroutput>PARAMETER</computeroutput> is one of the
1464 following:</para>
1465
1466 <para><glosslist>
1467 <glossentry>
1468 <glossterm><computeroutput>--timesync-interval</computeroutput></glossterm>
1469
1470 <glossdef>
1471 <para>Specifies the interval at which to synchronize the time
1472 with the host. The default is 10000 ms (10 seconds).</para>
1473 </glossdef>
1474 </glossentry>
1475
1476 <glossentry>
1477 <glossterm><computeroutput>--timesync-min-adjust</computeroutput></glossterm>
1478
1479 <glossdef>
1480 <para>The minimum absolute drift value measured in milliseconds
1481 to make adjustments for. The default is 1000 ms on OS/2 and 100
1482 ms elsewhere.</para>
1483 </glossdef>
1484 </glossentry>
1485
1486 <glossentry>
1487 <glossterm><computeroutput>--timesync-latency-factor</computeroutput></glossterm>
1488
1489 <glossdef>
1490 <para>The factor to multiply the time query latency with to
1491 calculate the dynamic minimum adjust time. The default is 8
1492 times, that means in detail: Measure the time it takes to
1493 determine the host time (the guest has to contact the VM host
1494 service which may take some time), multiply this value by 8 and
1495 do an adjustment only if the time difference between host and
1496 guest is bigger than this value. Don't do any time adjustment
1497 otherwise.</para>
1498 </glossdef>
1499 </glossentry>
1500
1501 <glossentry>
1502 <glossterm><computeroutput>--timesync-max-latency</computeroutput></glossterm>
1503
1504 <glossdef>
1505 <para>The max host timer query latency to accept. The default is
1506 250 ms.</para>
1507 </glossdef>
1508 </glossentry>
1509
1510 <glossentry>
1511 <glossterm><computeroutput>--timesync-set-threshold</computeroutput></glossterm>
1512
1513 <glossdef>
1514 <para>The absolute drift threshold, given as milliseconds where
1515 to start setting the time instead of trying to smoothly adjust
1516 it. The default is 20 minutes.</para>
1517 </glossdef>
1518 </glossentry>
1519
1520 <glossentry>
1521 <glossterm><computeroutput>--timesync-set-start</computeroutput></glossterm>
1522
1523 <glossdef>
1524 <para>Set the time when starting the time sync service.</para>
1525 </glossdef>
1526 </glossentry>
1527
1528 <glossentry>
1529 <glossterm><computeroutput>--timesync-set-on-restore
1530 0|1</computeroutput></glossterm>
1531
1532 <glossdef>
1533 <para>Set the time after the VM was restored from a saved state
1534 when passing 1 as parameter (default). Disable by passing 0. In
1535 the latter case, the time will be adjusted smoothly which can
1536 take a long time.</para>
1537 </glossdef>
1538 </glossentry>
1539 </glosslist></para>
1540
1541 <para>All these parameters can be specified as command line parameters
1542 to VBoxService as well.</para>
1543 </sect2>
1544
1545 <sect2 id="disabletimesync">
1546
1547 <title>Disabling the Guest Additions time synchronization</title>
1548
1549 <para>Once installed and started, the VirtualBox Guest Additions will
1550 try to synchronize the guest time with the host time. This can be
1551 prevented by forbidding the guest service from reading the host
1552 clock:</para>
1553
1554 <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</screen>
1555
1556 </sect2>
1557
1558 </sect1>
1559
1560 <sect1 id="vboxbowsolaris11">
1561 <title>Installing the alternate bridged networking driver on Solaris 11
1562 hosts</title>
1563
1564 <para>Starting with VirtualBox 4.1, VirtualBox ships a new network filter
1565 driver that utilizes Solaris 11's Crossbow functionality. By default, this
1566 new driver is installed for Solaris 11 hosts (builds 159 and above) that
1567 has support for it.</para>
1568
1569 <para>To force installation of the older STREAMS based network filter
1570 driver, execute as root the following command before installing the
1571 VirtualBox package:</para>
1572
1573 <screen>touch /etc/vboxinst_vboxflt</screen>
1574
1575 <para>To force installation of the Crossbow based network filter driver,
1576 execute as root the following command before installing the VirtualBox
1577 package:</para>
1578
1579 <screen>touch /etc/vboxinst_vboxbow</screen>
1580
1581 <para>To check which driver is currently being used by VirtualBox,
1582 execute:</para>
1583
1584 <screen>modinfo | grep vbox</screen>
1585
1586 <para>If the output contains "vboxbow", it indicates VirtualBox is using
1587 the Crossbow network filter driver, while the name "vboxflt" indicates
1588 usage of the older STREAMS network filter.</para>
1589 </sect1>
1590
1591 <sect1 id="vboxbowvnictemplates">
1592 <title>VirtualBox VNIC templates for VLANs on Solaris 11 hosts</title>
1593
1594 <para>VirtualBox supports VNIC (Virtual Network Interface) templates for
1595 configuring VMs over VLANs.<footnote>
1596 <para>Support for Crossbow based bridged networking was introduced
1597 with VirtualBox 4.1 and requires Solaris 11 build 159 or above.</para>
1598 </footnote> A VirtualBox VNIC template is a VNIC whose name starts with
1599 "vboxvnic_template".</para>
1600
1601 <para>Here is an example of how to use a VNIC template to configure a VLAN
1602 for VMs. Create a VirtualBox VNIC template, by executing as root:</para>
1603
1604 <screen>dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0
1605</screen>
1606
1607 <para>This will create a temporary VNIC over interface "nge0" with the
1608 VLAN ID 23. To create VNIC templates that are persistent across host
1609 reboots, skip the <computeroutput>-t</computeroutput> parameter in the
1610 above command. You may check the current state of links using:</para>
1611
1612 <para><screen>$ dladm show-link
1613LINK CLASS MTU STATE BRIDGE OVER
1614nge0 phys 1500 up -- --
1615nge1 phys 1500 down -- --
1616vboxvnic_template0 vnic 1500 up -- nge0
1617
1618$ dladm show-vnic
1619LINK OVER SPEED MACADDRESS MACADDRTYPE VID
1620vboxvnic_template0 nge0 1000 2:8:20:25:12:75 random 23
1621</screen></para>
1622
1623 <para>Once the VNIC template is created, all VMs that need to be part of
1624 VLAN 23 over the physical interface "nge0" can use the same VNIC template.
1625 This makes managing VMs on VLANs simpler and efficient, as the VLAN
1626 details are not stored as part of every VM's configuration but rather
1627 picked from the VNIC template which can be modified anytime using
1628 <computeroutput>dladm</computeroutput>. Apart from the VLAN ID, VNIC
1629 templates can be created with additional properties such as bandwidth
1630 limits, CPU fanout etc. Refer to your Solaris network documentation on how
1631 to accomplish this. These additional properties, if any, are also applied
1632 to VMs which use the VNIC template.</para>
1633 </sect1>
1634
1635 <sect1 id="addhostonlysolaris">
1636 <title>Configuring multiple host-only network interfaces on Solaris
1637 hosts</title>
1638
1639 <para>By default VirtualBox provides you with one host-only network
1640 interface. Adding more host-only network interfaces on Solaris hosts
1641 requires manual configuration. Here's how to add two more host-only
1642 network interfaces.</para>
1643
1644 <para>You first need to stop all running VMs and unplumb all existing
1645 "vboxnet" interfaces. Execute the following commands as root:</para>
1646
1647 <screen>ifconfig vboxnet0 unplumb</screen>
1648
1649 <para>Once you make sure all vboxnet interfaces are unplumbed, remove the
1650 driver using:</para>
1651
1652 <para><screen>rem_drv vboxnet</screen>then edit the file
1653 <computeroutput>/platform/i86pc/kernel/drv/vboxnet.conf</computeroutput>
1654 and add a line for the new interfaces:</para>
1655
1656 <para><screen>name="vboxnet" parent="pseudo" instance=1;
1657name="vboxnet" parent="pseudo" instance=2;</screen>Add as many of these lines
1658 as required and make sure "instance" number is uniquely incremented. Next
1659 reload the vboxnet driver using:</para>
1660
1661 <para><screen>add_drv vboxnet</screen>Now plumb all the interfaces using
1662 <computeroutput>ifconfig vboxnetX plumb</computeroutput> (where X can be
1663 0, 1 or 2 in this case) and once plumbed you can then configure the
1664 interface like any other network interface.</para>
1665
1666 <para>To make your newly added interfaces' settings persistent across
1667 reboots you will need to edit the files
1668 <computeroutput>/etc/netmasks</computeroutput>, and if you are using NWAM
1669 <computeroutput>/etc/nwam/llp</computeroutput> and add the appropriate
1670 entries to set the netmask and static IP for each of those interfaces. The
1671 VirtualBox installer only updates these configuration files for the one
1672 "vboxnet0" interface it creates by default.</para>
1673 </sect1>
1674
1675 <sect1 id="solariscodedumper">
1676 <title>Configuring the VirtualBox CoreDumper on Solaris hosts</title>
1677
1678 <para>VirtualBox is capable of producing its own core files for extensive
1679 debugging when things go wrong. Currently this is only available on
1680 Solaris hosts.</para>
1681
1682 <para>The VirtualBox CoreDumper can be enabled using the following
1683 command:</para>
1684
1685 <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpEnabled 1</screen></para>
1686
1687 <para>You can specify which directory to use for core dumps with this
1688 command:</para>
1689
1690 <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir &lt;path-to-directory&gt;</screen>Make
1691 sure the directory you specify is on a volume with sufficient free space
1692 and that the VirtualBox process has sufficient permissions to write files
1693 to this directory. If you skip this command and don't specify any core
1694 dump directory, the current directory of the VirtualBox executable will be
1695 used (which would most likely fail when writing cores as they are
1696 protected with root permissions). It is recommended you explicitly set a
1697 core dump directory.</para>
1698
1699 <para>You must specify when the VirtualBox CoreDumper should be triggered.
1700 This is done using the following commands:</para>
1701
1702 <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpReplaceSystemDump 1
1703VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpLive 1</screen>At
1704 least one of the above two commands will have to be provided if you have
1705 enabled the VirtualBox CoreDumper.</para>
1706
1707 <para>Setting <computeroutput>CoreDumpReplaceSystemDump</computeroutput>
1708 sets up the VM to override the host's core dumping mechanism and in the
1709 event of any crash only the VirtualBox CoreDumper would produce the core
1710 file.</para>
1711
1712 <para>Setting <computeroutput>CoreDumpLive</computeroutput> sets up the VM
1713 to produce cores whenever the VM process receives a
1714 <computeroutput>SIGUSR2</computeroutput> signal. After producing the core
1715 file, the VM will not be terminated and will continue to run. You can thus
1716 take cores of the VM process using:</para>
1717
1718 <para><screen>kill -s SIGUSR2 &lt;VM-process-id&gt;</screen></para>
1719
1720 <para>Core files produced by the VirtualBox CoreDumper are of the form
1721 <computeroutput>core.vb.&lt;ProcessName&gt;.&lt;ProcessID&gt;</computeroutput>,
1722 for example <computeroutput>core.vb.VBoxHeadless.11321</computeroutput>.</para>
1723 </sect1>
1724
1725 <sect1 id="guitweaks">
1726 <title>Locking down the VirtualBox manager GUI</title>
1727
1728 <sect2>
1729 <title>GUI customization</title>
1730
1731 <para>There are several advanced customization settings for locking down
1732 the VirtualBox manager, that is, removing some features that the user
1733 should not see.</para>
1734
1735 <para><screen>VBoxManage setextradata global GUI/Customizations OPTION[,OPTION...]</screen></para>
1736
1737 <para>where <computeroutput>OPTION</computeroutput> is one of the
1738 following keywords:<glosslist>
1739 <glossentry>
1740 <glossterm><computeroutput>noSelector</computeroutput></glossterm>
1741
1742 <glossdef>
1743 <para>Don't allow to start the VirtualBox manager. Trying to do so
1744 will show a window containing a proper error message.</para>
1745 </glossdef>
1746 </glossentry>
1747
1748 <glossentry>
1749 <glossterm><computeroutput>noMenuBar</computeroutput></glossterm>
1750
1751 <glossdef>
1752 <para>VM windows will not contain a menu bar.</para>
1753 </glossdef>
1754 </glossentry>
1755
1756 <glossentry>
1757 <glossterm><computeroutput>noStatusBar</computeroutput></glossterm>
1758
1759 <glossdef>
1760 <para>VM windows will not contain a status bar.</para>
1761 </glossdef>
1762 </glossentry>
1763 </glosslist></para>
1764
1765 <para>To disable any GUI customization do <screen>VBoxManage setextradata global GUI/Customizations</screen></para>
1766 </sect2>
1767
1768 <sect2>
1769 <title>Host Key customization</title>
1770
1771 <para>To disable all host key combinations, open the preferences and
1772 change the host key to <emphasis>None</emphasis>. This might be useful
1773 when using VirtualBox in a kiosk mode.</para>
1774
1775 <para>To redefine or disable certain host key actions, use the following command:</para>
1776
1777 <screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...."</screen>
1778
1779 <para>The following list shows the possible host key actions together with their default
1780 host key shortcut. Setting an action to <emphasis>None</emphasis> will disable
1781 that host key action.</para>
1782 <table>
1783 <title>ignoreme</title>
1784 <tgroup cols="3">
1785 <tbody>
1786 <row>
1787 <entry><emphasis role="bold">Action</emphasis></entry>
1788 <entry><emphasis role="bold">Default Host Key</emphasis></entry>
1789 <entry><emphasis role="bold">Action</emphasis></entry>
1790 </row>
1791 <row>
1792 <entry>SettingsDialog</entry>
1793 <entry>S</entry>
1794 <entry>open the VM settings dialog</entry>
1795 </row>
1796 <row>
1797 <entry>TakeSnapshot</entry>
1798 <entry>S</entry>
1799 <entry>take a snapshot</entry>
1800 </row>
1801 <row>
1802 <entry>InformationsDialog</entry>
1803 <entry>N</entry>
1804 <entry>show the VM information dialog</entry>
1805 </row>
1806 <row>
1807 <entry>MouseIntegration</entry>
1808 <entry>I</entry>
1809 <entry>toggle mouse integration</entry>
1810 </row>
1811 <row>
1812 <entry>TypeCAD</entry>
1813 <entry>Del</entry>
1814 <entry>inject Ctrl+Alt+Del</entry>
1815 </row>
1816 <row>
1817 <entry>TypeCABS</entry>
1818 <entry>Backspace</entry>
1819 <entry>inject Ctrl+Alt+Backspace</entry>
1820 </row>
1821 <row>
1822 <entry>Pause</entry>
1823 <entry>P</entry>
1824 <entry>Pause the VM</entry>
1825 </row>
1826 <row>
1827 <entry>Reset</entry>
1828 <entry>R</entry>
1829 <entry>(hard) reset the guest</entry>
1830 </row>
1831 <row>
1832 <entry>Shutdown</entry>
1833 <entry>H</entry>
1834 <entry>press the ACPI power button</entry>
1835 </row>
1836 <row>
1837 <entry>Close</entry>
1838 <entry>Q</entry>
1839 <entry>show the VM close dialog</entry>
1840 </row>
1841 <row>
1842 <entry>FullscreenMode</entry>
1843 <entry>F</entry>
1844 <entry>switch the VM into fullscreen</entry>
1845 </row>
1846 <row>
1847 <entry>SeamlessMode</entry>
1848 <entry>L</entry>
1849 <entry>switch the VM into seamless mode</entry>
1850 </row>
1851 <row>
1852 <entry>ScaleMode</entry>
1853 <entry>C</entry>
1854 <entry>switch the VM into scale mode</entry>
1855 </row>
1856 <row>
1857 <entry>PopupMenu</entry>
1858 <entry>Home</entry>
1859 <entry>show popup menu in fullscreen / seamless mode</entry>
1860 </row>
1861 </tbody>
1862 </tgroup>
1863 </table>
1864
1865 <para>To disable the fullscreen mode as well as the seamless mode, use the following command:
1866 <screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</screen>
1867 </para>
1868
1869 </sect2>
1870 <sect2>
1871 <title>Action when terminating the VM</title>
1872
1873 <para>You can disallow certain actions when terminating a VM. To disallow specific actions, type:</para>
1874
1875 <para><screen>VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...]</screen></para>
1876
1877 <para>where <computeroutput>OPTION</computeroutput> is one of the
1878 following keywords:<glosslist>
1879 <glossentry>
1880 <glossterm><computeroutput>SaveState</computeroutput></glossterm>
1881
1882 <glossdef>
1883 <para>Don't allow the user to save the VM state when terminating
1884 the VM.</para>
1885 </glossdef>
1886 </glossentry>
1887
1888 <glossentry>
1889 <glossterm><computeroutput>Shutdown</computeroutput></glossterm>
1890
1891 <glossdef>
1892 <para>Don't allow the user to shutdown the VM by sending the ACPI
1893 power-off event to the guest.</para>
1894 </glossdef>
1895 </glossentry>
1896
1897 <glossentry>
1898 <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
1899
1900 <glossdef>
1901 <para>Don't allow the user to power off the VM.</para>
1902 </glossdef>
1903 </glossentry>
1904
1905 <glossentry>
1906 <glossterm><computeroutput>Restore</computeroutput></glossterm>
1907
1908 <glossdef>
1909 <para>Don't allow the user to return to the last snapshot when
1910 powering off the VM.</para>
1911 </glossdef>
1912 </glossentry>
1913 </glosslist></para>
1914
1915 <para>Any combination of the above is allowed. If all options are
1916 specified, the VM cannot be shut down at all.</para>
1917 </sect2>
1918 </sect1>
1919
1920 <sect1 id="vboxwebsrv-daemon">
1921 <title>Starting the VirtualBox web service automatically</title>
1922
1923 <para>The VirtualBox web service
1924 (<computeroutput>vboxwebsrv</computeroutput>) is used for controlling
1925 VirtualBox remotely. It is documented in detail in the VirtualBox Software
1926 Development Kit (SDK); please see <xref linkend="VirtualBoxAPI" />. As the
1927 client base using this interface is growing, we added start scripts for
1928 the various operation systems we support. The following sections describe
1929 how to use them. The VirtualBox web service is never started automatically
1930 as a result of a standard installation.</para>
1931
1932 <sect2 id="vboxwebsrv-linux">
1933 <title>Linux: starting the webservice via <computeroutput>init</computeroutput></title>
1934
1935 <para>On Linux, the web service can be automatically started during
1936 host boot by adding appropriate parameters to the file
1937 <computeroutput>/etc/default/virtualbox</computeroutput>.
1938 There is one mandatory parameter, <computeroutput>VBOXWEB_USER</computeroutput>,
1939 which must be set to the user which will later start the VMs. The
1940 paramters in the table below all start with <computeroutput>VBOXWEB_</computeroutput>
1941 (<computeroutput>VBOXWEB_HOST</computeroutput>,
1942 <computeroutput>VBOXWEB_PORT</computeroutput> etc.):
1943 <table>
1944 <title>ignored</title>
1945 <tgroup cols="3">
1946 <tbody>
1947 <row>
1948 <entry><emphasis role="bold">Parameter</emphasis></entry>
1949 <entry><emphasis role="bold">Description</emphasis></entry>
1950 <entry><emphasis role="bold">Default</emphasis></entry>
1951 </row>
1952 <row>
1953 <entry>USER</entry>
1954 <entry>The user as which the web service runs</entry>
1955 <entry></entry>
1956 </row>
1957 <row>
1958 <entry>HOST</entry>
1959 <entry>The host to bind the web service to</entry>
1960 <entry>localhost</entry>
1961 </row>
1962 <row>
1963 <entry>PORT</entry>
1964 <entry>The port to bind the web service to</entry>
1965 <entry>18083</entry>
1966 </row>
1967 <row>
1968 <entry>SSL_KEYFILE</entry>
1969 <entry>Server key and certificate file, PEM format</entry>
1970 <entry></entry>
1971 </row>
1972 <row>
1973 <entry>SSL_PASSWORDFILE</entry>
1974 <entry>File name for password to server key</entry>
1975 <entry></entry>
1976 </row>
1977 <row>
1978 <entry>SSL_CACERT</entry>
1979 <entry>CA certificate file, PEM format</entry>
1980 <entry></entry>
1981 </row>
1982 <row>
1983 <entry>SSL_CAPATH</entry>
1984 <entry>CA certificate path</entry>
1985 <entry></entry>
1986 </row>
1987 <row>
1988 <entry>SSL_DHFILE</entry>
1989 <entry>DH file name or DH key length in bits</entry>
1990 <entry></entry>
1991 </row>
1992 <row>
1993 <entry>SSL_RANDFILE</entry>
1994 <entry>File containing seed for random number generator</entry>
1995 <entry></entry>
1996 </row>
1997 <row>
1998 <entry>TIMEOUT</entry>
1999 <entry>Session timeout in seconds; 0 disables timeouts</entry>
2000 <entry>300</entry>
2001 </row>
2002 <row>
2003 <entry>CHECK_INTERVAL</entry>
2004 <entry>Frequency of timeout checks in seconds</entry>
2005 <entry>5</entry>
2006 </row>
2007 <row>
2008 <entry>THREADS</entry>
2009 <entry>Maximum number of worker threads to run in parallel</entry>
2010 <entry>100</entry>
2011 </row>
2012 <row>
2013 <entry>KEEPALIVE</entry>
2014 <entry>Maximum number of requests before a socket will be closed</entry>
2015 <entry>100</entry>
2016 </row>
2017 <row>
2018 <entry>LOGFILE</entry>
2019 <entry>Name of file to write log to</entry>
2020 <entry></entry>
2021 </row>
2022 <row>
2023 <entry>ROTATE</entry>
2024 <entry>Number of log files; 0 disables log rotation</entry>
2025 <entry>10</entry>
2026 </row>
2027 <row>
2028 <entry>LOGSIZE</entry>
2029 <entry>Maximum size of a log file in bytes to trigger rotation</entry>
2030 <entry>1MB</entry>
2031 </row>
2032 <row>
2033 <entry>LOGINTERVAL</entry>
2034 <entry>Maximum time interval in seconds to trigger log rotation</entry>
2035 <entry>1 day</entry>
2036 </row>
2037 </tbody>
2038 </tgroup>
2039 </table>
2040 </para>
2041
2042 <para>Setting the parameter <computeroutput>SSL_KEYFILE</computeroutput>
2043 enables the SSL/TLS support. Using encryption is strongly encouraged, as
2044 otherwise everything (including passwords) is transferred in clear
2045 text.</para>
2046 </sect2>
2047
2048 <sect2 id="vboxwebsrv-solaris">
2049 <title>Solaris: starting the web service via SMF</title>
2050
2051 <para>On Solaris hosts, the VirtualBox web service daemon is
2052 integrated into the SMF framework. You can change the parameters, but
2053 don't have to if the defaults below already match your needs:<screen>svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
2054svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
2055svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root</screen></para>
2056
2057 <para>The table in the previous section showing the parameter names and
2058 defaults also applies to Solaris. The parameter names must be changed
2059 to lowercase and a prefix of <computeroutput>config/</computeroutput>
2060 has to be added, e.g. <computeroutput>config/user</computeroutput> or
2061 <computeroutput>config/ssl_keyfile</computeroutput>. If you made any
2062 change, don't forget to run the following command to put the changes into
2063 effect immediately:<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen></para>
2064
2065 <para>If you forget the above command then the previous settings will
2066 be used when enabling the service. Check the current property settings
2067 with:<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen></para>
2068
2069 <para>When everything is configured correctly you can start the
2070 VirtualBox web service with the following command:<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen></para>
2071
2072 <para>For more information about SMF, please refer to the Solaris
2073 documentation.</para>
2074 </sect2>
2075
2076 <sect2 id="vboxwebsrv-osx">
2077 <title>Mac OS X: starting the webservice via launchd</title>
2078
2079 <para>On Mac OS X, launchd is used to start the VirtualBox webservice. An
2080 example configuration file can be found in
2081 <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>.
2082 It can be enabled by changing the
2083 <computeroutput>Disabled</computeroutput> key from
2084 <computeroutput>true</computeroutput> to
2085 <computeroutput>false</computeroutput>. To manually start the
2086 service use the following command: <screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
2087 For additional information on how launchd services could be
2088 configured see <literal><ulink
2089 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></literal>.</para>
2090 </sect2>
2091 </sect1>
2092
2093 <sect1 id="vboxwatchdog">
2094 <title>VirtualBox Watchdog</title>
2095 <para>Starting with VirtualBox 4.2 the memory ballooning service formerly
2096 known as <computeroutput>VBoxBalloonCtrl</computeroutput> was renamed to
2097 VBoxWatchdog, which now incorporates several host services that are meant
2098 to be run in a server environment.</para>
2099
2100 <para>These services are: <itemizedlist>
2101 <listitem>
2102 <para>Memory ballooning control, which automatically takes care of
2103 a VM's configured memory balloon (see <xref linkend="guestadd-balloon" />
2104 for an introduction to memory ballooning). This especially is useful
2105 for server environments where VMs may dynamically require more or
2106 less memory during runtime.</para>
2107
2108 <para>The service periodically checks a VM's current memory balloon
2109 and its free guest RAM and automatically adjusts the current memory
2110 balloon by inflating or deflating it accordingly. This handling only
2111 applies to running VMs having recent Guest Additions installed.</para>
2112 </listitem>
2113 <listitem>
2114 <para>Host isolation detection, which provides a way to detect whether
2115 the host cannot reach the specific VirtualBox server instance anymore
2116 and take appropriate actions, such as shutting down, saving the
2117 current state or even powering down certain VMs.</para>
2118 </listitem>
2119 </itemizedlist></para>
2120
2121 <para>
2122 All configuration values can be either specified via command line or global
2123 extradata, whereas command line values always have a higher priority when set.
2124 Some of the configuration values also be be specified on a per-VM basis. So
2125 the overall lookup order is: command line, per-VM basis extradata (if available),
2126 global extradata.
2127 </para>
2128
2129 <sect2 id="vboxwatchdog-ballonctrl">
2130 <title>Memory ballooning control</title>
2131 <para>The memory ballooning control inflates and deflates the memory balloon
2132 of VMs based on the VMs free memory and the desired maximum balloon size.</para>
2133
2134 <para>To set up the memory ballooning control the maximum ballooning size a
2135 VM can reach needs to be set. This can be specified via command line with
2136 <screen>--balloon-max &lt;Size in MB&gt;</screen>, on a per-VM basis extradata value with
2137 <screen>VBoxManage setextradata &lt;VM-Name&gt; VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
2138 or using a global extradata value with
2139 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
2140 <note><para>If no maximum ballooning size is specified by at least one of
2141 the parameters above, no ballooning will be performed at all.</para></note>
2142 </para>
2143
2144 <para>Setting the ballooning increment in MB can be either done via
2145 command line with
2146 <screen>--balloon-inc &lt;Size in MB&gt;</screen> or using a global
2147 extradata value with
2148 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB &lt;Size in MB&gt;</screen>
2149 Default ballooning increment is 256 MB if not specified.</para>
2150
2151 <para>Same goes with the ballooning decrement: Via command line with
2152 <screen>--balloon-dec &lt;Size in MB&gt;</screen> or using a global
2153 extradata value with
2154 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB &lt;Size in MB&gt;</screen>
2155 Default ballooning decrement is 128 MB if not specified.</para>
2156
2157 <para>To define the lower limit in MB a balloon can be the command line with
2158 <screen>--balloon-lower-limit &lt;Size in MB&gt;</screen> can be used or using a global
2159 extradata value with
2160 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB &lt;Size in MB&gt;</screen>
2161 is available. Default lower limit is 128 if not specified.</para>
2162 </sect2>
2163
2164 <sect2 id="vboxwatchdog-hostisln">
2165 <title>Host isolation detection</title>
2166 <para>To detect whether a host is being isolated, that is, the host cannot
2167 reach the VirtualBox server instance anymore, the host needs to set an
2168 alternating value to a global extradata value within a time period. If
2169 this value is not set within that time period a timeout occurred and the
2170 so-called host isolation response will be performed to the VMs handled.
2171 Which VMs are handled can be controlled by defining VM groups and assigning
2172 VMs to those groups. By default no groups are set, meaning that all VMs
2173 on the server will be handled when no host response is received within
2174 30 seconds.</para>
2175
2176 <para>To set the groups handled by the host isolation detection via
2177 command line:
2178 <screen>--apimon-groups=&lt;string[,stringN]&gt;</screen> or using a global
2179 extradata value with
2180 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups &lt;string[,stringN]&gt;</screen>
2181 </para>
2182
2183 <para>To set the host isolation timeout via command line:
2184 <screen>--apimon-isln-timeout=&lt;ms&gt;</screen> or using a global
2185 extradata value with
2186 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS &lt;ms&gt;</screen>
2187 </para>
2188
2189 <para>To set the actual host isolation response via command line:
2190 <screen>--apimon-isln-response=&lt;cmd&gt;</screen> or using a global
2191 extradata value with
2192 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse &lt;cmd&gt;</screen>
2193 The following response commands are available:
2194 <itemizedlist>
2195 <listitem>
2196 <para><computeroutput>none</computeroutput>, which does nothing.</para>
2197 </listitem>
2198 <listitem>
2199 <para><computeroutput>pause</computeroutput>, which pauses the
2200 execution of a VM.</para>
2201 </listitem>
2202 <listitem>
2203 <para><computeroutput>poweroff</computeroutput>, which shuts down
2204 the VM by pressing the virtual power button. The VM will not have
2205 the chance of saving any data or veto the shutdown process.</para>
2206 </listitem>
2207 <listitem>
2208 <para><computeroutput>save</computeroutput>, which saves the current
2209 machine state and powers off the VM afterwards. If saving the machine
2210 state fails the VM will be paused.</para>
2211 </listitem>
2212 <listitem>
2213 <para><computeroutput>shutdown</computeroutput>, which shuts down
2214 the VM in a gentle way by sending an <computeroutput>ACPI</computeroutput>
2215 shutdown event to the VM's operating system. The OS then has the
2216 chance of doing a clean shutdown.</para>
2217 </listitem>
2218 </itemizedlist>
2219 </para>
2220 </sect2>
2221
2222 <sect2 id="vboxwatchdog-moreinfo">
2223 <title>More information</title>
2224 <para>For more advanced options and parameters like verbose logging check
2225 the built-in command line help accessible with
2226 <computeroutput>--help</computeroutput>.</para>
2227 </sect2>
2228
2229 </sect1>
2230
2231 <sect1 id="otherextpacks">
2232 <title>Other extension packs</title>
2233
2234 <para>Starting with VirtualBox 4.2.0 there is another extension pack,
2235 <code>VNC</code>, which is open source and replaces the previous
2236 integration of the VNC remote access protocol. This is experimental code,
2237 and will be initially available in the VirtualBox source code package only.
2238 It is to a large portion code contributed by users, and is not supported
2239 in any way by Oracle.</para>
2240
2241 <para>The keyboard handling is severely limited, and only the US keyboard
2242 layout works. Other keyboard layouts will have at least some keys which
2243 produce the wrong results (often quite surprising effects), and for layouts
2244 which have significant differences to the US keyboard layout it is most
2245 likely unusable.</para>
2246
2247 <para>It is possible to install both the Oracle VM VirtualBox Extension
2248 Pack and VNC, but only one VRDE module can be active at any time. The
2249 following command switches to the VNC VRDE module in
2250 VNC:<screen>VBoxManage setproperty vrdeextpack VNC</screen></para>
2251
2252 <para>Configuring the remote access works very similarly to VRDP (see
2253 <xref linkend="vrde" />), with some limitations: VNC does not
2254 support specifying several port numbers, and the authentication is done
2255 differently. VNC can only deal with password authentication, and there
2256 is no option to use password hashes. This leaves no other choice than
2257 having a clear-text password in the VM configuration, which can be set with
2258 the following command:<screen>VBoxManage modifyvm VMNAME --vrdeproperty VNCPassword=secret</screen></para>
2259
2260 <para>The user is responsible for keeping this password secret, and it
2261 should be removed when a VM configuration is passed to another person,
2262 for whatever purpose. Some VNC servers claim to have "encrypted" passwords
2263 in the configuration. This is not true encryption, it is only concealing
2264 the passwords, which is exactly as secure as clear-text passwords.</para>
2265
2266 <para>The following command switches back to VRDP (if
2267 installed):<screen>VBoxManage setproperty vrdeextpack "Oracle VM VirtualBox Extension Pack"</screen></para>
2268 </sect1>
2269
2270 <sect1 id="autostart">
2271 <title>Starting virtual machines during system boot</title>
2272
2273 <para>Starting with VirtualBox 4.2.0 it is possible to start VMs automatically during
2274 system boot on Linux and Mac OS X for all users. </para>
2275
2276 <sect2 id="autostart-linux">
2277 <title>Linux: starting the autostart service via <computeroutput>init</computeroutput></title>
2278
2279 <para>On Linux, the autostart service is activated by setting two variables in
2280 <computeroutput>/etc/default/virtualbox</computeroutput>.
2281 The first one is <computeroutput>VBOXAUTOSTART_DB</computeroutput> which
2282 contains an absolute path to the autostart database directory.
2283 The directory should have write access for every user who should be able to
2284 start virtual machines automatically. Furthermore the directory should have the
2285 sticky bit set.
2286 The second variable is <computeroutput>VBOXAUTOSTART_CONFIG</computeroutput>
2287 which points the service to the autostart configuration file which is used
2288 during boot to determine whether to allow individual users to start a VM
2289 automatically and configure startup delays.
2290 The config file can be placed in <computeroutput>/etc/vbox</computeroutput>
2291 and contains several options. One is <computeroutput>default_policy</computeroutput>
2292 which controls whether the autostart service allows or denies to start a VM
2293 for users which are not in the exception list.
2294 The exception list starts with <computeroutput>exception_list</computeroutput>
2295 and contains a comma seperated list with usernames. Furthermore a separate
2296 startup delay can be configured for every user to avoid overloading the host.
2297 A sample configuration is given below:</para>
2298
2299 <para><screen>
2300# Default policy is to deny starting a VM, the other option is "allow".
2301default_policy = deny
2302# Users which are allowed are given below.
2303# If the default policy is to allow starting a VM is not allowed for the users below.
2304exception_list = bob, alice, joe
2305
2306bob = 30 # Bobs machines will be started 30 seconds after the autostart service started
2307alice = 180 # Alice machines will be started 180 seconds after the autostart service started
2308joe = 240 # Joes machines will be started 240 seconds after the autostart service started
2309 </screen></para>
2310
2311 <para>Every user who wants to enable autostart for individual machines
2312 has to set the path to the autostart database directory with
2313 <screen>VBoxManage setproperty autostartdbpath &lt;Autostart directory&gt;</screen>
2314 </para>
2315 </sect2>
2316
2317 <sect2 id="autostart-osx">
2318 <title>Mac OS X: starting the autostart service via launchd</title>
2319
2320 <para>On Mac OS X, launchd is used to start the VirtualBox autostart service. An
2321 example configuration file can be found in
2322 <computeroutput>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</computeroutput>.
2323 To enable the service copy the file to <computeroutput>/Library/LaunchDaemons</computeroutput> and change the
2324 <computeroutput>Disabled</computeroutput> key from
2325 <computeroutput>true</computeroutput> to
2326 <computeroutput>false</computeroutput>. Furthermore replace the second parameter
2327 to an existing configuration file which has the same format as on Linux (see <xref linkend="autostart-linux" />).
2328 To manually start the service use the following command:
2329 <screen>launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist</screen>
2330 For additional information on how launchd services could be
2331 configured see <literal><ulink
2332 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></literal>.</para>
2333 </sect2>
2334 </sect1>
2335</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