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 <vm></screen></para>
|
---|
36 |
|
---|
37 | <para>where <computeroutput><vm></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
|
---|
94 | vga = 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 <pid>
|
---|
123 | VBoxManage 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 |
|
---|
179 | HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
|
---|
180 |
|
---|
181 | HKEY_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-<version>/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-<version>/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 | "<width>x<height>" 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
|
---|
561 | EndSection</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
|
---|
592 | VBoxManage 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
|
---|
598 | VBoxManage 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 > /sys/devices/system/cpu/cpu<id>/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<x></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
|
---|
761 | vga = 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 >width,height<</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"
|
---|
960 | VBoxManage setextradata "VM name"
|
---|
961 | "VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware"
|
---|
962 | VBoxManage 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"
|
---|
976 | VBoxManage setextradata "VM name"
|
---|
977 | "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware"
|
---|
978 | VBoxManage 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"
|
---|
992 | VBoxManage setextradata "VM name"
|
---|
993 | "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product"
|
---|
994 | VBoxManage 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
|
---|
1020 | VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f
|
---|
1021 | VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1
|
---|
1022 | VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0
|
---|
1023 | VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet
|
---|
1024 | VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet
|
---|
1025 | VBoxManage 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
|
---|
1054 | kernel.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" >> /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 <pid-of-VBoxSVC></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 <pid-of-VBoxSVC></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 <username> user.<username>
|
---|
1112 | projmod -s -K "project.max-sem-ids=(priv,2048,deny)" user.<username></screen>
|
---|
1113 |
|
---|
1114 | <para>Substitute "<username>" 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
|
---|
1144 | VBoxManage setextradata "VM name"
|
---|
1145 | "VBoxInternal/Devices/serial/0/Config/IOBase" 0x3f8
|
---|
1146 | VBoxManage setextradata "VM name"
|
---|
1147 | "VBoxInternal/Devices/serial/0/LUN#0/Driver" Char
|
---|
1148 | VBoxManage setextradata "VM name"
|
---|
1149 | "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Driver" NamedPipe
|
---|
1150 | VBoxManage setextradata "VM name"
|
---|
1151 | "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/Location" "\\.\pipe\vboxCOM1"
|
---|
1152 | VBoxManage 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
|
---|
1207 | VBoxManage 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 | <uniq name of interception rule>/HostIP" <IPv4>
|
---|
1281 | VBoxManage setextradata "VM name" \
|
---|
1282 | "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
|
---|
1283 | <uniq name of interception rule>/HostName" <name of host></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 | <uniq name of interception rule>/HostIP" <IPv4>
|
---|
1288 | VBoxManage setextradata "VM name" \
|
---|
1289 | "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \
|
---|
1290 | <uniq name of interception rule>/HostNamePattern" <hostpattern></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
|
---|
1297 | VBoxManage 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"
|
---|
1331 | VBoxManage setextradata "VM name"
|
---|
1332 | "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion" "BIOS Version"
|
---|
1333 | VBoxManage setextradata "VM name"
|
---|
1334 | "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate" "BIOS Release Date"
|
---|
1335 | VBoxManage setextradata "VM name"
|
---|
1336 | "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor" 1
|
---|
1337 | VBoxManage setextradata "VM name"
|
---|
1338 | "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor" 2
|
---|
1339 | VBoxManage setextradata "VM name"
|
---|
1340 | "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3
|
---|
1341 | VBoxManage setextradata "VM name"
|
---|
1342 | "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4
|
---|
1343 | VBoxManage setextradata "VM name"
|
---|
1344 | "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor" "System Vendor"
|
---|
1345 | VBoxManage setextradata "VM name"
|
---|
1346 | "VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct" "System Product"
|
---|
1347 | VBoxManage setextradata "VM name"
|
---|
1348 | "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion" "System Version"
|
---|
1349 | VBoxManage setextradata "VM name"
|
---|
1350 | "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "System Serial"
|
---|
1351 | VBoxManage setextradata "VM name"
|
---|
1352 | "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU" "System SKU"
|
---|
1353 | VBoxManage setextradata "VM name"
|
---|
1354 | "VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily" "System Family"
|
---|
1355 | VBoxManage 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>"<EMPTY>"</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:<value>"</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
|
---|
1599 | LINK CLASS MTU STATE BRIDGE OVER
|
---|
1600 | nge0 phys 1500 up -- --
|
---|
1601 | nge1 phys 1500 down -- --
|
---|
1602 | vboxvnic_template0 vnic 1500 up -- nge0
|
---|
1603 |
|
---|
1604 | $ dladm show-vnic
|
---|
1605 | LINK OVER SPEED MACADDRESS MACADDRTYPE VID
|
---|
1606 | vboxvnic_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;
|
---|
1643 | name="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 <path-to-directory></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
|
---|
1689 | VBoxManage 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 <VM-process-id></screen></para>
|
---|
1705 |
|
---|
1706 | <para>Core files produced by the VirtualBox CoreDumper are of the form
|
---|
1707 | <computeroutput>core.vb.<ProcessName>.<ProcessID></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
|
---|
2040 | svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
|
---|
2041 | svccfg -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 <Size in MB></screen>, on a per-VM basis extradata value with
|
---|
2123 | <screen>VBoxManage setextradata <VM-Name> VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></screen>
|
---|
2124 | or using a global extradata value with
|
---|
2125 | <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></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 <Size in MB></screen> or using a global
|
---|
2133 | extradata value with
|
---|
2134 | <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB <Size in MB></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 <Size in MB></screen> or using a global
|
---|
2139 | extradata value with
|
---|
2140 | <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB <Size in MB></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 <Size in MB></screen> can be used or using a global
|
---|
2145 | extradata value with
|
---|
2146 | <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB <Size in MB></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=<string[,stringN]></screen> or using a global
|
---|
2165 | extradata value with
|
---|
2166 | <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups <string[,stringN]></screen>
|
---|
2167 | </para>
|
---|
2168 |
|
---|
2169 | <para>To set the host isolation timeout via command line:
|
---|
2170 | <screen>--apimon-isln-timeout=<ms></screen> or using a global
|
---|
2171 | extradata value with
|
---|
2172 | <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS <ms></screen>
|
---|
2173 | </para>
|
---|
2174 |
|
---|
2175 | <para>To set the actual host isolation response via command line:
|
---|
2176 | <screen>--apimon-isln-response=<cmd></screen> or using a global
|
---|
2177 | extradata value with
|
---|
2178 | <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse <cmd></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>
|
---|