VirtualBox

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

最後變更 在這個檔案從42244是 41421,由 vboxsync 提交於 13 年 前

VBoxBalloonCtrl/VBoxWatchdog: Documentation.

檔案大小: 109.6 KB
 
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 </sect1>
1545
1546 <sect1 id="vboxbowsolaris11">
1547 <title>Installing the alternate bridged networking driver on Solaris 11
1548 hosts</title>
1549
1550 <para>Starting with VirtualBox 4.1, VirtualBox ships a new network filter
1551 driver that utilizes Solaris 11's Crossbow functionality. By default, this
1552 new driver is installed for Solaris 11 hosts (builds 159 and above) that
1553 has support for it.</para>
1554
1555 <para>To force installation of the older STREAMS based network filter
1556 driver, execute as root the following command before installing the
1557 VirtualBox package:</para>
1558
1559 <screen>touch /etc/vboxinst_vboxflt</screen>
1560
1561 <para>To force installation of the Crossbow based network filter driver,
1562 execute as root the following command before installing the VirtualBox
1563 package:</para>
1564
1565 <screen>touch /etc/vboxinst_vboxbow</screen>
1566
1567 <para>To check which driver is currently being used by VirtualBox,
1568 execute:</para>
1569
1570 <screen>modinfo | grep vbox</screen>
1571
1572 <para>If the output contains "vboxbow", it indicates VirtualBox is using
1573 the Crossbow network filter driver, while the name "vboxflt" indicates
1574 usage of the older STREAMS network filter.</para>
1575 </sect1>
1576
1577 <sect1 id="vboxbowvnictemplates">
1578 <title>VirtualBox VNIC templates for VLANs on Solaris 11 hosts</title>
1579
1580 <para>VirtualBox supports VNIC (Virtual Network Interface) templates for
1581 configuring VMs over VLANs.<footnote>
1582 <para>Support for Crossbow based bridged networking was introduced
1583 with VirtualBox 4.1 and requires Solaris 11 build 159 or above.</para>
1584 </footnote> A VirtualBox VNIC template is a VNIC whose name starts with
1585 "vboxvnic_template".</para>
1586
1587 <para>Here is an example of how to use a VNIC template to configure a VLAN
1588 for VMs. Create a VirtualBox VNIC template, by executing as root:</para>
1589
1590 <screen>dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0
1591</screen>
1592
1593 <para>This will create a temporary VNIC over interface "nge0" with the
1594 VLAN ID 23. To create VNIC templates that are persistent across host
1595 reboots, skip the <computeroutput>-t</computeroutput> parameter in the
1596 above command. You may check the current state of links using:</para>
1597
1598 <para><screen>$ dladm show-link
1599LINK CLASS MTU STATE BRIDGE OVER
1600nge0 phys 1500 up -- --
1601nge1 phys 1500 down -- --
1602vboxvnic_template0 vnic 1500 up -- nge0
1603
1604$ dladm show-vnic
1605LINK OVER SPEED MACADDRESS MACADDRTYPE VID
1606vboxvnic_template0 nge0 1000 2:8:20:25:12:75 random 23
1607</screen></para>
1608
1609 <para>Once the VNIC template is created, all VMs that need to be part of
1610 VLAN 23 over the physical interface "nge0" can use the same VNIC template.
1611 This makes managing VMs on VLANs simpler and efficient, as the VLAN
1612 details are not stored as part of every VM's configuration but rather
1613 picked from the VNIC template which can be modified anytime using
1614 <computeroutput>dladm</computeroutput>. Apart from the VLAN ID, VNIC
1615 templates can be created with additional properties such as bandwidth
1616 limits, CPU fanout etc. Refer to your Solaris network documentation on how
1617 to accomplish this. These additional properties, if any, are also applied
1618 to VMs which use the VNIC template.</para>
1619 </sect1>
1620
1621 <sect1 id="addhostonlysolaris">
1622 <title>Configuring multiple host-only network interfaces on Solaris
1623 hosts</title>
1624
1625 <para>By default VirtualBox provides you with one host-only network
1626 interface. Adding more host-only network interfaces on Solaris hosts
1627 requires manual configuration. Here's how to add two more host-only
1628 network interfaces.</para>
1629
1630 <para>You first need to stop all running VMs and unplumb all existing
1631 "vboxnet" interfaces. Execute the following commands as root:</para>
1632
1633 <screen>ifconfig vboxnet0 unplumb</screen>
1634
1635 <para>Once you make sure all vboxnet interfaces are unplumbed, remove the
1636 driver using:</para>
1637
1638 <para><screen>rem_drv vboxnet</screen>then edit the file
1639 <computeroutput>/platform/i86pc/kernel/drv/vboxnet.conf</computeroutput>
1640 and add a line for the new interfaces:</para>
1641
1642 <para><screen>name="vboxnet" parent="pseudo" instance=1;
1643name="vboxnet" parent="pseudo" instance=2;</screen>Add as many of these lines
1644 as required and make sure "instance" number is uniquely incremented. Next
1645 reload the vboxnet driver using:</para>
1646
1647 <para><screen>add_drv vboxnet</screen>Now plumb all the interfaces using
1648 <computeroutput>ifconfig vboxnetX plumb</computeroutput> (where X can be
1649 0, 1 or 2 in this case) and once plumbed you can then configure the
1650 interface like any other network interface.</para>
1651
1652 <para>To make your newly added interfaces' settings persistent across
1653 reboots you will need to edit the files
1654 <computeroutput>/etc/netmasks</computeroutput>, and if you are using NWAM
1655 <computeroutput>/etc/nwam/llp</computeroutput> and add the appropriate
1656 entries to set the netmask and static IP for each of those interfaces. The
1657 VirtualBox installer only updates these configuration files for the one
1658 "vboxnet0" interface it creates by default.</para>
1659 </sect1>
1660
1661 <sect1 id="solariscodedumper">
1662 <title>Configuring the VirtualBox CoreDumper on Solaris hosts</title>
1663
1664 <para>VirtualBox is capable of producing its own core files for extensive
1665 debugging when things go wrong. Currently this is only available on
1666 Solaris hosts.</para>
1667
1668 <para>The VirtualBox CoreDumper can be enabled using the following
1669 command:</para>
1670
1671 <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpEnabled 1</screen></para>
1672
1673 <para>You can specify which directory to use for core dumps with this
1674 command:</para>
1675
1676 <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir &lt;path-to-directory&gt;</screen>Make
1677 sure the directory you specify is on a volume with sufficient free space
1678 and that the VirtualBox process has sufficient permissions to write files
1679 to this directory. If you skip this command and don't specify any core
1680 dump directory, the current directory of the VirtualBox executable will be
1681 used (which would most likely fail when writing cores as they are
1682 protected with root permissions). It is recommended you explicitly set a
1683 core dump directory.</para>
1684
1685 <para>You must specify when the VirtualBox CoreDumper should be triggered.
1686 This is done using the following commands:</para>
1687
1688 <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpReplaceSystemDump 1
1689VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpLive 1</screen>At
1690 least one of the above two commands will have to be provided if you have
1691 enabled the VirtualBox CoreDumper.</para>
1692
1693 <para>Setting <computeroutput>CoreDumpReplaceSystemDump</computeroutput>
1694 sets up the VM to override the host's core dumping mechanism and in the
1695 event of any crash only the VirtualBox CoreDumper would produce the core
1696 file.</para>
1697
1698 <para>Setting <computeroutput>CoreDumpLive</computeroutput> sets up the VM
1699 to produce cores whenever the VM process receives a
1700 <computeroutput>SIGUSR2</computeroutput> signal. After producing the core
1701 file, the VM will not be terminated and will continue to run. You can thus
1702 take cores of the VM process using:</para>
1703
1704 <para><screen>kill -s SIGUSR2 &lt;VM-process-id&gt;</screen></para>
1705
1706 <para>Core files produced by the VirtualBox CoreDumper are of the form
1707 <computeroutput>core.vb.&lt;ProcessName&gt;.&lt;ProcessID&gt;</computeroutput>,
1708 e.g.<computeroutput>core.vb.VBoxHeadless.11321</computeroutput>.</para>
1709 </sect1>
1710
1711 <sect1 id="guitweaks">
1712 <title>Locking down the VirtualBox manager GUI</title>
1713
1714 <sect2>
1715 <title>GUI customization</title>
1716
1717 <para>There are several advanced customization settings for locking down
1718 the VirtualBox manager, that is, removing some features that the user
1719 should not see.</para>
1720
1721 <para><screen>VBoxManage setextradata global GUI/Customizations OPTION[,OPTION...]</screen></para>
1722
1723 <para>where <computeroutput>OPTION</computeroutput> is one of the
1724 following keywords:<glosslist>
1725 <glossentry>
1726 <glossterm><computeroutput>noSelector</computeroutput></glossterm>
1727
1728 <glossdef>
1729 <para>Don't allow to start the VirtualBox manager. Trying to do so
1730 will show a window containing a proper error message.</para>
1731 </glossdef>
1732 </glossentry>
1733
1734 <glossentry>
1735 <glossterm><computeroutput>noMenuBar</computeroutput></glossterm>
1736
1737 <glossdef>
1738 <para>VM windows will not contain a menu bar.</para>
1739 </glossdef>
1740 </glossentry>
1741
1742 <glossentry>
1743 <glossterm><computeroutput>noStatusBar</computeroutput></glossterm>
1744
1745 <glossdef>
1746 <para>VM windows will not contain a status bar.</para>
1747 </glossdef>
1748 </glossentry>
1749 </glosslist></para>
1750
1751 <para>To disable any GUI customization do <screen>VBoxManage setextradata global GUI/Customizations</screen></para>
1752 </sect2>
1753
1754 <sect2>
1755 <title>Host Key customization</title>
1756
1757 <para>To disable all host key combinations, open the preferences and
1758 change the host key to <emphasis>None</emphasis>. This might be useful
1759 when using VirtualBox in a kiosk mode.</para>
1760
1761 <para>To redefine or disable certain host key actions, use the following command:</para>
1762
1763 <screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...."</screen>
1764
1765 <para>The following list shows the possible host key actions together with their default
1766 host key shortcut. Setting an action to <emphasis>None</emphasis> will disable
1767 that host key action.</para>
1768 <table>
1769 <title>ignoreme</title>
1770 <tgroup cols="3">
1771 <tbody>
1772 <row>
1773 <entry><emphasis role="bold">Action</emphasis></entry>
1774 <entry><emphasis role="bold">Default Host Key</emphasis></entry>
1775 <entry><emphasis role="bold">Action</emphasis></entry>
1776 </row>
1777 <row>
1778 <entry>SettingsDialog</entry>
1779 <entry>S</entry>
1780 <entry>open the VM settings dialog</entry>
1781 </row>
1782 <row>
1783 <entry>TakeSnapshot</entry>
1784 <entry>S</entry>
1785 <entry>take a snapshot</entry>
1786 </row>
1787 <row>
1788 <entry>InformationsDialog</entry>
1789 <entry>N</entry>
1790 <entry>show the VM information dialog</entry>
1791 </row>
1792 <row>
1793 <entry>MouseIntegration</entry>
1794 <entry>I</entry>
1795 <entry>toggle mouse integration</entry>
1796 </row>
1797 <row>
1798 <entry>TypeCAD</entry>
1799 <entry>Del</entry>
1800 <entry>inject Ctrl+Alt+Del</entry>
1801 </row>
1802 <row>
1803 <entry>TypeCABS</entry>
1804 <entry>Backspace</entry>
1805 <entry>inject Ctrl+Alt+Backspace</entry>
1806 </row>
1807 <row>
1808 <entry>Pause</entry>
1809 <entry>P</entry>
1810 <entry>Pause the VM</entry>
1811 </row>
1812 <row>
1813 <entry>Reset</entry>
1814 <entry>R</entry>
1815 <entry>(hard) reset the guest</entry>
1816 </row>
1817 <row>
1818 <entry>Shutdown</entry>
1819 <entry>H</entry>
1820 <entry>press the ACPI power button</entry>
1821 </row>
1822 <row>
1823 <entry>Close</entry>
1824 <entry>Q</entry>
1825 <entry>show the VM close dialog</entry>
1826 </row>
1827 <row>
1828 <entry>FullscreenMode</entry>
1829 <entry>F</entry>
1830 <entry>switch the VM into fullscreen</entry>
1831 </row>
1832 <row>
1833 <entry>SeamlessMode</entry>
1834 <entry>L</entry>
1835 <entry>switch the VM into seamless mode</entry>
1836 </row>
1837 <row>
1838 <entry>ScaleMode</entry>
1839 <entry>C</entry>
1840 <entry>switch the VM into scale mode</entry>
1841 </row>
1842 <row>
1843 <entry>PopupMenu</entry>
1844 <entry>Home</entry>
1845 <entry>show popup menu in fullscreen / seamless mode</entry>
1846 </row>
1847 </tbody>
1848 </tgroup>
1849 </table>
1850
1851 <para>To disable the fullscreen mode as well as the seamless mode, use the following command:
1852 <screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</screen>
1853 </para>
1854
1855 </sect2>
1856 <sect2>
1857 <title>Action when terminating the VM</title>
1858
1859 <para>You can disallow certain actions when terminating a VM. To disallow specific actions, type:</para>
1860
1861 <para><screen>VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...]</screen></para>
1862
1863 <para>where <computeroutput>OPTION</computeroutput> is one of the
1864 following keywords:<glosslist>
1865 <glossentry>
1866 <glossterm><computeroutput>SaveState</computeroutput></glossterm>
1867
1868 <glossdef>
1869 <para>Don't allow the user to save the VM state when terminating
1870 the VM.</para>
1871 </glossdef>
1872 </glossentry>
1873
1874 <glossentry>
1875 <glossterm><computeroutput>Shutdown</computeroutput></glossterm>
1876
1877 <glossdef>
1878 <para>Don't allow the user to shutdown the VM by sending the ACPI
1879 power-off event to the guest.</para>
1880 </glossdef>
1881 </glossentry>
1882
1883 <glossentry>
1884 <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
1885
1886 <glossdef>
1887 <para>Don't allow the user to power off the VM.</para>
1888 </glossdef>
1889 </glossentry>
1890
1891 <glossentry>
1892 <glossterm><computeroutput>Restore</computeroutput></glossterm>
1893
1894 <glossdef>
1895 <para>Don't allow the user to return to the last snapshot when
1896 powering off the VM.</para>
1897 </glossdef>
1898 </glossentry>
1899 </glosslist></para>
1900
1901 <para>Any combination of the above is allowed. If all options are
1902 specified, the VM cannot be shut down at all.</para>
1903 </sect2>
1904 </sect1>
1905
1906 <sect1 id="vboxwebsrv-daemon">
1907 <title>Starting the VirtualBox web service automatically</title>
1908
1909 <para>The VirtualBox web service
1910 (<computeroutput>vboxwebsrv</computeroutput>) is used for controlling
1911 VirtualBox remotely. It is documented in detail in the VirtualBox Software
1912 Development Kit (SDK); please see <xref linkend="VirtualBoxAPI" />. As the
1913 client base using this interface is growing, we added start scripts for
1914 the various operation systems we support. The following sections describe
1915 how to use them. The VirtualBox web service is never started automatically
1916 as a result of a standard installation.</para>
1917
1918 <sect2 id="vboxwebsrv-linux">
1919 <title>Linux: starting the webservice via <computeroutput>init</computeroutput></title>
1920
1921 <para>On Linux, the web service can be automatically started during
1922 host boot by adding appropriate parameters to the file
1923 <computeroutput>/etc/default/virtualbox</computeroutput>.
1924 There is one mandatory parameter, <computeroutput>VBOXWEB_USER</computeroutput>,
1925 which must be set to the user which will later start the VMs. The
1926 paramters in the table below all start with <computeroutput>VBOXWEB_</computeroutput>
1927 (<computeroutput>VBOXWEB_HOST</computeroutput>,
1928 <computeroutput>VBOXWEB_PORT</computeroutput> etc.):
1929 <table>
1930 <title>ignored</title>
1931 <tgroup cols="3">
1932 <tbody>
1933 <row>
1934 <entry><emphasis role="bold">Parameter</emphasis></entry>
1935 <entry><emphasis role="bold">Description</emphasis></entry>
1936 <entry><emphasis role="bold">Default</emphasis></entry>
1937 </row>
1938 <row>
1939 <entry>USER</entry>
1940 <entry>The user as which the web service runs</entry>
1941 <entry></entry>
1942 </row>
1943 <row>
1944 <entry>HOST</entry>
1945 <entry>The host to bind the web service to</entry>
1946 <entry>localhost</entry>
1947 </row>
1948 <row>
1949 <entry>PORT</entry>
1950 <entry>The port to bind the web service to</entry>
1951 <entry>18083</entry>
1952 </row>
1953 <row>
1954 <entry>SSL_KEYFILE</entry>
1955 <entry>Server key and certificate file, PEM format</entry>
1956 <entry></entry>
1957 </row>
1958 <row>
1959 <entry>SSL_PASSWORDFILE</entry>
1960 <entry>File name for password to server key</entry>
1961 <entry></entry>
1962 </row>
1963 <row>
1964 <entry>SSL_CACERT</entry>
1965 <entry>CA certificate file, PEM format</entry>
1966 <entry></entry>
1967 </row>
1968 <row>
1969 <entry>SSL_CAPATH</entry>
1970 <entry>CA certificate path</entry>
1971 <entry></entry>
1972 </row>
1973 <row>
1974 <entry>SSL_DHFILE</entry>
1975 <entry>DH file name or DH key length in bits</entry>
1976 <entry></entry>
1977 </row>
1978 <row>
1979 <entry>SSL_RANDFILE</entry>
1980 <entry>File containing seed for random number generator</entry>
1981 <entry></entry>
1982 </row>
1983 <row>
1984 <entry>TIMEOUT</entry>
1985 <entry>Session timeout in seconds; 0 disables timeouts</entry>
1986 <entry>300</entry>
1987 </row>
1988 <row>
1989 <entry>CHECK_INTERVAL</entry>
1990 <entry>Frequency of timeout checks in seconds</entry>
1991 <entry>5</entry>
1992 </row>
1993 <row>
1994 <entry>THREADS</entry>
1995 <entry>Maximum number of worker threads to run in parallel</entry>
1996 <entry>100</entry>
1997 </row>
1998 <row>
1999 <entry>KEEPALIVE</entry>
2000 <entry>Maximum number of requests before a socket will be closed</entry>
2001 <entry>100</entry>
2002 </row>
2003 <row>
2004 <entry>LOGFILE</entry>
2005 <entry>Name of file to write log to</entry>
2006 <entry></entry>
2007 </row>
2008 <row>
2009 <entry>ROTATE</entry>
2010 <entry>Number of log files; 0 disables log rotation</entry>
2011 <entry>10</entry>
2012 </row>
2013 <row>
2014 <entry>LOGSIZE</entry>
2015 <entry>Maximum size of a log file in bytes to trigger rotation</entry>
2016 <entry>1MB</entry>
2017 </row>
2018 <row>
2019 <entry>LOGINTERVAL</entry>
2020 <entry>Maximum time interval in seconds to trigger log rotation</entry>
2021 <entry>1 day</entry>
2022 </row>
2023 </tbody>
2024 </tgroup>
2025 </table>
2026 </para>
2027
2028 <para>Setting the parameter <computeroutput>SSL_KEYFILE</computeroutput>
2029 enables the SSL/TLS support. Using encryption is strongly encouraged, as
2030 otherwise everything (including passwords) is transferred in clear
2031 text.</para>
2032 </sect2>
2033
2034 <sect2 id="vboxwebsrv-solaris">
2035 <title>Solaris: starting the web service via SMF</title>
2036
2037 <para>On Solaris hosts, the VirtualBox web service daemon is
2038 integrated into the SMF framework. You can change the parameters, but
2039 don't have to if the defaults below already match your needs:<screen>svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
2040svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
2041svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root</screen></para>
2042
2043 <para>The table in the previous section showing the parameter names and
2044 defaults also applies to Solaris. The parameter names must be changed
2045 to lowercase and a prefix of <computeroutput>config/</computeroutput>
2046 has to be added, e.g. <computeroutput>config/user</computeroutput> or
2047 <computeroutput>config/ssl_keyfile</computeroutput>. If you made any
2048 change, don't forget to run the following command to put the changes into
2049 effect immediately:<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen></para>
2050
2051 <para>If you forget the above command then the previous settings will
2052 be used when enabling the service. Check the current property settings
2053 with:<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen></para>
2054
2055 <para>When everything is configured correctly you can start the
2056 VirtualBox web service with the following command:<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen></para>
2057
2058 <para>For more information about SMF, please refer to the Solaris
2059 documentation.</para>
2060 </sect2>
2061
2062 <sect2 id="vboxwebsrv-osx">
2063 <title>Mac OS X: starting the webservice via launchd</title>
2064
2065 <para>On Mac OS X, launchd is used to start the VirtualBox webservice. An
2066 example configuration file can be found in
2067 <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>.
2068 It can be enabled by changing the
2069 <computeroutput>Disabled</computeroutput> key from
2070 <computeroutput>true</computeroutput> to
2071 <computeroutput>false</computeroutput>. To manually start the
2072 service use the following command: <screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
2073 For additional information on how launchd services could be
2074 configured see <literal><ulink
2075 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>
2076 </sect2>
2077 </sect1>
2078
2079 <sect1 id="vboxwatchdog">
2080 <title>VirtualBox Watchdog</title>
2081 <para>Starting with VirtualBox 4.2 the memory ballooning service formerly
2082 known as <computeroutput>VBoxBalloonCtrl</computeroutput> was renamed to
2083 VBoxWatchdog, which now incorporates several host services that are meant
2084 to be run in a server environment.</para>
2085
2086 <para>These services are: <itemizedlist>
2087 <listitem>
2088 <para>Memory ballooning control, which automatically takes care of
2089 a VM's configured memory balloon (see <xref linkend="guestadd-balloon" />
2090 for an introduction to memory ballooning). This especially is useful
2091 for server environments where VMs may dynamically require more or
2092 less memory during runtime.</para>
2093
2094 <para>The service periodically checks a VM's current memory balloon
2095 and its free guest RAM and automatically adjusts the current memory
2096 balloon by inflating or deflating it accordingly. This handling only
2097 applies to running VMs having recent Guest Additions installed.</para>
2098 </listitem>
2099 <listitem>
2100 <para>Host isolation detection, which provides a way to detect whether
2101 the host cannot reach the specific VirtualBox server instance anymore
2102 and take appropriate actions, such as shutting down, saving the
2103 current state or even powering down certain VMs.</para>
2104 </listitem>
2105 </itemizedlist></para>
2106
2107 <para>
2108 All configuration values can be either specified via command line or global
2109 extradata, whereas command line values always have a higher priority when set.
2110 Some of the configuration values also be be specified on a per-VM basis. So
2111 the overall lookup order is: command line, per-VM basis extradata (if available),
2112 global extradata.
2113 </para>
2114
2115 <sect2 id="vboxwatchdog-ballonctrl">
2116 <title>Memory ballooning control</title>
2117 <para>The memory ballooning control inflates and deflates the memory balloon
2118 of VMs based on the VMs free memory and the desired maximum balloon size.</para>
2119
2120 <para>To set up the memory ballooning control the maximum ballooning size a
2121 VM can reach needs to be set. This can be specified via command line with
2122 <screen>--balloon-max &lt;Size in MB&gt;</screen>, on a per-VM basis extradata value with
2123 <screen>VBoxManage setextradata &lt;VM-Name&gt; VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
2124 or using a global extradata value with
2125 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
2126 <note><para>If no maximum ballooning size is specified by at least one of
2127 the parameters above, no ballooning will be performed at all.</para></note>
2128 </para>
2129
2130 <para>Setting the ballooning increment in MB can be either done via
2131 command line with
2132 <screen>--balloon-inc &lt;Size in MB&gt;</screen> or using a global
2133 extradata value with
2134 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB &lt;Size in MB&gt;</screen>
2135 Default ballooning increment is 256 MB if not specified.</para>
2136
2137 <para>Same goes with the ballooning decrement: Via command line with
2138 <screen>--balloon-dec &lt;Size in MB&gt;</screen> or using a global
2139 extradata value with
2140 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB &lt;Size in MB&gt;</screen>
2141 Default ballooning decrement is 128 MB if not specified.</para>
2142
2143 <para>To define the lower limit in MB a balloon can be the command line with
2144 <screen>--balloon-lower-limit &lt;Size in MB&gt;</screen> can be used or using a global
2145 extradata value with
2146 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB &lt;Size in MB&gt;</screen>
2147 is available. Default lower limit is 128 if not specified.</para>
2148 </sect2>
2149
2150 <sect2 id="vboxwatchdog-hostisln">
2151 <title>Host isolation detection</title>
2152 <para>To detect whether a host is being isolated, that is, the host cannot
2153 reach the VirtualBox server instance anymore, the host needs to set an
2154 alternating value to a global extradata value within a time period. If
2155 this value is not set within that time period a timeout occurred and the
2156 so-called host isolation response will be performed to the VMs handled.
2157 Which VMs are handled can be controlled by defining VM groups and assigning
2158 VMs to those groups. By default no groups are set, meaning that all VMs
2159 on the server will be handled when no host response is received within
2160 30 seconds.</para>
2161
2162 <para>To set the groups handled by the host isolation detection via
2163 command line:
2164 <screen>--apimon-groups=&lt;string[,stringN]&gt;</screen> or using a global
2165 extradata value with
2166 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups &lt;string[,stringN]&gt;</screen>
2167 </para>
2168
2169 <para>To set the host isolation timeout via command line:
2170 <screen>--apimon-isln-timeout=&lt;ms&gt;</screen> or using a global
2171 extradata value with
2172 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS &lt;ms&gt;</screen>
2173 </para>
2174
2175 <para>To set the actual host isolation response via command line:
2176 <screen>--apimon-isln-response=&lt;cmd&gt;</screen> or using a global
2177 extradata value with
2178 <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse &lt;cmd&gt;</screen>
2179 The following response commands are available:
2180 <itemizedlist>
2181 <listitem>
2182 <para><computeroutput>none</computeroutput>, which does nothing.</para>
2183 </listitem>
2184 <listitem>
2185 <para><computeroutput>pause</computeroutput>, which pauses the
2186 execution of a VM.</para>
2187 </listitem>
2188 <listitem>
2189 <para><computeroutput>poweroff</computeroutput>, which shuts down
2190 the VM by pressing the virtual power button. The VM will not have
2191 the chance of saving any data or veto the shutdown process.</para>
2192 </listitem>
2193 <listitem>
2194 <para><computeroutput>save</computeroutput>, which saves the current
2195 machine state and powers off the VM afterwards. If saving the machine
2196 state fails the VM will be paused.</para>
2197 </listitem>
2198 <listitem>
2199 <para><computeroutput>shutdown</computeroutput>, which shuts down
2200 the VM in a gentle way by sending an <computeroutput>ACPI</computeroutput>
2201 shutdown event to the VM's operating system. The OS then has the
2202 chance of doing a clean shutdown.</para>
2203 </listitem>
2204 </itemizedlist>
2205 </para>
2206 </sect2>
2207
2208 <sect2 id="vboxwatchdog-moreinfo">
2209 <title>More information</title>
2210 <para>For more advanced options and parameters like verbose logging check
2211 the built-in command line help accessible with
2212 <computeroutput>--help</computeroutput>.</para>
2213 </sect2>
2214
2215 </sect1>
2216
2217 <sect1 id="otherextpacks">
2218 <title>Other extension packs</title>
2219
2220 <para>Starting with VirtualBox 4.2.0 there is another extension pack,
2221 <code>VNC</code>, which is open source and replaces the previous
2222 integration of the VNC remote access protocol. This is experimental code,
2223 and will be initially available in the VirtualBox source code package only.
2224 It is to a large portion code contributed by users, and is not supported
2225 in any way by Oracle.</para>
2226
2227 <para>The keyboard handling is severely limited, and only the US keyboard
2228 layout works. Other keyboard layouts will have at least some keys which
2229 produce the wrong results (often quite surprising effects), and for layouts
2230 which have significant differences to the US keyboard layout it is most
2231 likely unusable.</para>
2232
2233 <para>It is possible to install both the Oracle VM VirtualBox Extension
2234 Pack and VNC, but only one VRDE module can be active at any time. The
2235 following command switches to the VNC VRDE module in
2236 VNC:<screen>VBoxManage setproperty vrdeextpack VNC</screen></para>
2237
2238 <para>Configuring the remote access works very similarly to VRDP (see
2239 <xref linkend="vrde" />), with some limitations: VNC does not
2240 support specifying several port numbers, and the authentication is done
2241 differently. VNC can only deal with password authentication, and there
2242 is no option to use password hashes. This leaves no other choice than
2243 having a clear-text password in the VM configuration, which can be set with
2244 the following command:<screen>VBoxManage modifyvm VMNAME --vrdeproperty VNCPassword=secret</screen></para>
2245
2246 <para>The user is responsible for keeping this password secret, and it
2247 should be removed when a VM configuration is passed to another person,
2248 for whatever purpose. Some VNC servers claim to have "encrypted" passwords
2249 in the configuration. This is not true encryption, it is only concealing
2250 the passwords, which is exactly as secure as clear-text passwords.</para>
2251
2252 <para>The following command switches back to VRDP (if
2253 installed):<screen>VBoxManage setproperty vrdeextpack "Oracle VM VirtualBox Extension Pack"</screen></para>
2254 </sect1>
2255</chapter>
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette