VirtualBox

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

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

doc/manual: cosmetical fixes

File size: 53.0 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
4<chapter id="Troubleshooting">
5 <title>Troubleshooting</title>
6
7 <para>This chapter provides answers to commonly asked questions. In order to
8 improve your user experience with VirtualBox, it is recommended to read this
9 section to learn more about common pitfalls and get recommendations on how
10 to use the product.</para>
11
12 <sect1>
13 <title>Procedures and tools</title>
14
15 <sect2>
16 <title>Categorizing and isolating problems</title>
17
18 <para>More often than not, a virtualized guest behaves like a physical
19 system. Any problems that a physical machine would encounter, a virtual
20 machine will encounter as well. If, for example, Internet connectivity
21 is lost due to external issues, virtual machines will be affected just
22 as much as physical ones.</para>
23
24 <para>If a true VirtualBox problem is encountered, it helps to
25 categorize and isolate the problem first. Here are some of the questions
26 that should be answered before reporting a problem:<orderedlist>
27 <listitem>
28 <para>Is the problem specific to a certain guest OS? Specific
29 release of a guest OS? Especially with Linux guest related
30 problems, the issue may be specific to a certain distribution and
31 version of Linux.</para>
32 </listitem>
33
34 <listitem>
35 <para>Is the problem specific to a certain host OS? Problems are
36 usually not host OS specific (because most of the VirtualBox code
37 base is shared across all supported platforms), but especially in
38 the areas of networking and USB support, there are significant
39 differences between host platforms. Some GUI related issues are
40 also host specific.</para>
41 </listitem>
42
43 <listitem>
44 <para>Is the problem specific to certain host hardware? This
45 category of issues is typically related to the host CPU. Because
46 of significant differences between VT-x and AMD-V, problems may be
47 specific to one or the other technology. The exact CPU model may
48 also make a difference (even for software virtualization) because
49 different CPUs support different features, which may affect
50 certain aspects of guest CPU operation.</para>
51 </listitem>
52
53 <listitem>
54 <para>Is the problem specific to a certain virtualization mode?
55 Some problems may only occur in software virtualization mode,
56 others may be specific to hardware virtualization.</para>
57 </listitem>
58
59 <listitem>
60 <para>Is the problem specific to guest SMP? That is, is it related
61 to the number of virtual CPUs (VCPUs) in the guest? Using more
62 than one CPU usually significantly affects the internal operation
63 of a guest OS.</para>
64 </listitem>
65
66 <listitem>
67 <para>Is the problem specific to the Guest Additions? In some
68 cases, this is a given (e.g., a shared folders problem), in other
69 cases it may be less obvious (for example, display problems). And
70 if the problem is Guest Additions specific, is it also specific to
71 a certain version of the Additions?</para>
72 </listitem>
73
74 <listitem>
75 <para>Is the problem specific to a certain environment? Some
76 problems are related to a particular environment external to the
77 VM; this usually involves network setup. Certain configurations of
78 external servers such as DHCP or PXE may expose problems which do
79 not occur with other, similar servers.</para>
80 </listitem>
81
82 <listitem>
83 <para>Is the problem a regression? Knowing that an issue is a
84 regression usually makes it significantly easier to find the
85 solution. In this case, it is crucial to know which version is
86 affected and which is not.</para>
87 </listitem>
88 </orderedlist></para>
89 </sect2>
90
91 <sect2>
92 <title>Collecting debugging information</title>
93
94 <para>For problem determination, it is often important to collect
95 debugging information which can be analyzed by VirtualBox support. This
96 section contains information about what kind of information can be
97 obtained.</para>
98
99 <para>Every time VirtualBox starts up a VM, a so-called <emphasis
100 role="bold">"release log file"</emphasis> is created containing lots of
101 information about the VM configuration and runtime events. The log file
102 is called <computeroutput><literal>VBox.log</literal></computeroutput>
103 and resides in the VM log file folder. Typically this will be a
104 directory like this:<screen>$HOME/.VirtualBox/Machines/{machinename}/Logs</screen>When
105 starting a VM, the configuration file of the last run will be renamed to
106 <computeroutput>.1</computeroutput>, up to
107 <computeroutput>.3</computeroutput>. Sometimes when there is a problem,
108 it is useful to have a look at the logs. Also when requesting support
109 for VirtualBox, supplying the corresponding log file is
110 mandatory.</para>
111
112 <para>For convenience, for each virtual machine, the VirtualBox main
113 window can show these logs in a window. To access it, select a virtual
114 machine from the list on the left and select "Show logs..." from the
115 "Machine" window.</para>
116
117 <para>The release log file (VBox.log) contains a wealth of diagnostic
118 information, such as Host OS type and version, VirtualBox version and
119 build (32-bit or 64-bit), a complete dump of the guest's configuration
120 (CFGM), detailed information about the host CPU type and supported
121 features, whether hardware virtualization is enabled, information about
122 VT-x/AMD-V setup, state transitions (creating, running, paused,
123 stopping, etc.), guest BIOS messages, guest Additions messages, device
124 specific log entries and at the end of execution, final guest state and
125 condensed statistics.</para>
126
127 <para>In case of crashes, it is very important to collect <emphasis
128 role="bold">crash dumps</emphasis>. This is true for both host and guest
129 crashes. For information about enabling core dumps on Linux, Solaris,
130 and OS X systems, refer to the core dump article on the VirtualBox
131 website.<footnote>
132 <para><ulink
133 url="http://www.virtualbox.org/wiki/Core_dump">http://www.virtualbox.org/wiki/Core_dump</ulink>.</para>
134 </footnote></para>
135
136 <para>For network related problems, it is often helpful to capture a
137 trace of network traffic. If the traffic is routed through an adapter on
138 the host, it is possible to use Wireshark or a similar tool to capture
139 the traffic there. However, this often also includes a lot of traffic
140 unrelated to the VM.</para>
141
142 <para>VirtualBox provides an ability to capture network traffic only on
143 a specific VM's network adapter. Refer to the network tracing article on
144 the VirtualBox website<footnote>
145 <para><ulink
146 url="http://www.virtualbox.org/wiki/Network_tips">http://www.virtualbox.org/wiki/Network_tips</ulink>.</para>
147 </footnote> for information on enabling this capture. Note that the
148 trace files created by VirtualBox are in .pcap format and can be easily
149 analyzed with Wireshark.</para>
150 </sect2>
151
152 <sect2>
153 <title>The built-in VM debugger</title>
154
155 <para>VirtualBox includes a built-in VM debugger, which advanced users
156 may find useful. This debugger allows the user to examine, and to some
157 extent, control, the VM state.<note>
158 <para>Use the VM debugger at your own risk. There is no support for
159 it, and the following documentation is only made available for
160 advanced users with a very high level of familiarity with the
161 x86/AMD64 machine instruction set, as well as detailed knowledge of
162 the PC architecture. A degree of familiarity with the internals of
163 the guest OS in question is not required, but may be very
164 helpful.</para>
165 </note></para>
166
167 <para>The VM debugger is available in all regular production versions of
168 VirtualBox, but it is disabled by default because the average user will
169 have little use for it. There are two ways to access the
170 debugger:<itemizedlist>
171 <listitem>
172 <para>A debugger console window displayed alongside the VM</para>
173 </listitem>
174
175 <listitem>
176 <para>Via the <computeroutput>telnet</computeroutput> protocol at
177 port 5000</para>
178 </listitem>
179 </itemizedlist></para>
180
181 <para>The debugger can be enabled in two ways:<itemizedlist>
182 <listitem>
183 <para>Start the <computeroutput>VirtualBox</computeroutput>
184 process with a <computeroutput>--dbg</computeroutput>,
185 <computeroutput>--debug</computeroutput>, or
186 <computeroutput>--debug-command-line</computeroutput> argument.
187 See the VirtualBox usage help for details. Note that these
188 arguments are only useful when a VM is started immediately, using
189 the <computeroutput>--startvm</computeroutput> argument.</para>
190 </listitem>
191
192 <listitem>
193 <para>Set the
194 <computeroutput>VBOX_GUI_DBG_ENABLED</computeroutput> or
195 <computeroutput>VBOX_GUI_DBG_AUTO_SHOW</computeroutput>
196 environment variable to an arbitrary value before launching the
197 VirtualBox process. Setting these variables (only their presence
198 is checked) is effective even when the first VirtualBox process is
199 the VM selector window. VMs subsequently launched from the
200 selector will have the debugger enabled.</para>
201 </listitem>
202 </itemizedlist></para>
203
204 <para>A new 'Debug' menu entry will be added to the VirtualBox
205 application. This menu allows the user to open the debugger
206 console.</para>
207
208 <para>The VM debugger command syntax is loosely modeled on Microsoft and
209 IBM debuggers used on DOS, OS/2 and Windows. Users familiar with symdeb,
210 CodeView, or the OS/2 kernel debugger will find the VirtualBox VM
211 debugger familiar.</para>
212
213 <para>The most important command is
214 <computeroutput>help</computeroutput>. This will print brief usage help
215 for all debugger commands. The set of commands supported by the VM
216 debugger changes frequently and the
217 <computeroutput>help</computeroutput> command is always
218 up-to-date.</para>
219
220 <para>A brief summary of frequently used commands follows:<itemizedlist>
221 <listitem>
222 <para><computeroutput>stop</computeroutput> -- stops the VM
223 execution and enables single stepping</para>
224 </listitem>
225
226 <listitem>
227 <para><computeroutput>g</computeroutput> -- continue VM
228 execution</para>
229 </listitem>
230
231 <listitem>
232 <para><computeroutput>t</computeroutput> -- single step an
233 instruction</para>
234 </listitem>
235
236 <listitem>
237 <para><computeroutput>rg/rh/r</computeroutput> -- print the
238 guest/hypervisor/current registers</para>
239 </listitem>
240
241 <listitem>
242 <para><computeroutput>kg/kh/k</computeroutput> -- print the
243 guest/hypervisor/current call stack</para>
244 </listitem>
245
246 <listitem>
247 <para><computeroutput>da/db/dw/dd/dq</computeroutput> -- print
248 memory contents as ASCII/bytes/words/dwords/qwords</para>
249 </listitem>
250
251 <listitem>
252 <para><computeroutput>u</computeroutput> -- unassemble
253 memory</para>
254 </listitem>
255
256 <listitem>
257 <para><computeroutput>dg</computeroutput> -- print the guest's
258 GDT</para>
259 </listitem>
260
261 <listitem>
262 <para><computeroutput>di</computeroutput> -- print the guest's
263 IDT</para>
264 </listitem>
265
266 <listitem>
267 <para><computeroutput>dl</computeroutput> -- print the guest's
268 LDT</para>
269 </listitem>
270
271 <listitem>
272 <para><computeroutput>dt</computeroutput> -- print the guest's
273 TSS</para>
274 </listitem>
275
276 <listitem>
277 <para><computeroutput>dp*</computeroutput> -- print the guest's
278 page table structures</para>
279 </listitem>
280
281 <listitem>
282 <para><computeroutput>bp/br</computeroutput> -- set a
283 normal/recompiler breakpoint</para>
284 </listitem>
285
286 <listitem>
287 <para><computeroutput>bl</computeroutput> -- list
288 breakpoints</para>
289 </listitem>
290
291 <listitem>
292 <para><computeroutput>bc</computeroutput> -- clear a
293 breakpoint</para>
294 </listitem>
295 </itemizedlist></para>
296
297 <para>See the built-in <computeroutput>help</computeroutput> for other
298 available commands.</para>
299
300 <para>The VM debugger supports symbolic debugging, although symbols for
301 guest code are often not available. For Solaris guests, the
302 <computeroutput>detect</computeroutput> command automatically determines
303 the guest OS version and locates kernel symbols in guest's memory.
304 Symbolic debugging is then available. For Linux guests, the
305 <computeroutput>detect</computeroutput> commands also determines the
306 guest OS version, but there are no symbols in the guest's memory. Kernel
307 symbols are available in the file
308 <computeroutput>/proc/kallsyms</computeroutput> on Linux guests. This
309 file must be copied to the host, for example using
310 <computeroutput>scp</computeroutput>. The
311 <computeroutput>loadmap</computeroutput> debugger command can be used to
312 make the symbol information available to the VM debugger. Note that the
313 <computeroutput>kallsyms</computeroutput> file contains the symbols for
314 the currently loaded modules; if the guest's configuration changes, the
315 symbols will change as well and must be updated.</para>
316
317 <para>For all guests, a simple way to verify that the correct symbols
318 are loaded is the <computeroutput>k</computeroutput> command. The guest
319 is normally idling and it should be clear from the symbolic information
320 that the guest operating system's idle loop is being executed.</para>
321
322 <para>Another group of debugger commands is the set of
323 <computeroutput>info</computeroutput> commands. Running
324 <computeroutput>info help</computeroutput> provides complete usage
325 information. The information commands provide ad-hoc data pertinent to
326 various emulated devices and aspects of the VMM. There is no general
327 guideline for using the <computeroutput>info</computeroutput> commands,
328 the right command to use depends entirely on the problem being
329 investigated. Some of the info commands are:<itemizedlist>
330 <listitem>
331 <para><computeroutput>cfgm</computeroutput> -- print a branch of
332 the configuration tree</para>
333 </listitem>
334
335 <listitem>
336 <para><computeroutput>cpuid</computeroutput> -- display the guest
337 CPUID leaves</para>
338 </listitem>
339
340 <listitem>
341 <para><computeroutput>ioport</computeroutput> -- print registered
342 I/O port ranges</para>
343 </listitem>
344
345 <listitem>
346 <para><computeroutput>mmio</computeroutput> -- print registered
347 MMIO ranges</para>
348 </listitem>
349
350 <listitem>
351 <para><computeroutput>mode</computeroutput> -- print the current
352 paging mode</para>
353 </listitem>
354
355 <listitem>
356 <para><computeroutput>pit</computeroutput> -- print the i8254 PIT
357 state</para>
358 </listitem>
359
360 <listitem>
361 <para><computeroutput>pic</computeroutput> -- print the i8259A PIC
362 state</para>
363 </listitem>
364
365 <listitem>
366 <para><computeroutput>ohci/ehci</computeroutput> -- print a subset
367 of the OHCI/EHCI USB controller state</para>
368 </listitem>
369
370 <listitem>
371 <para><computeroutput>pcnet0</computeroutput> -- print the PCnet
372 state</para>
373 </listitem>
374
375 <listitem>
376 <para><computeroutput>vgatext</computeroutput> -- print the
377 contents of the VGA framebuffer formatted as standard text
378 mode</para>
379 </listitem>
380
381 <listitem>
382 <para><computeroutput>timers</computeroutput> -- print all VM
383 timers</para>
384 </listitem>
385 </itemizedlist></para>
386
387 <para>The output of the <computeroutput>info</computeroutput> commands
388 generally requires in-depth knowledge of the emulated device and/or
389 VirtualBox VMM internals. However, when used properly, the information
390 provided can be invaluable.</para>
391 </sect2>
392 </sect1>
393
394 <sect1>
395 <title>General</title>
396
397 <sect2 id="configPeriodicFlush">
398 <title>Guest shows IDE/SATA errors for file-based images on slow host
399 file system</title>
400
401 <para>Occasionally, some host file systems provide very poor writing
402 performance and as a consequence cause the guest to time out IDE/SATA
403 commands. This is normal behavior and should normally cause no real
404 problems, as the guest should repeat commands that have timed out.
405 However some guests (e.g. some Linux versions) have severe problems if a
406 write to an image file takes longer than about 15 seconds. Some file
407 systems however require more than a minute to complete a single write,
408 if the host cache contains a large amount of data that needs to be
409 written.</para>
410
411 <para>The symptom for this problem is that the guest can no longer
412 access its files during large write or copying operations, usually
413 leading to an immediate hang of the guest.</para>
414
415 <para>In order to work around this problem (the true fix is to use a
416 faster file system that doesn't exhibit such unacceptable write
417 performance), it is possible to flush the image file after a certain
418 amount of data has been written. This interval is normally infinite, but
419 can be configured individually for each disk of a VM.</para>
420
421 <para>For IDE disks use the following command:</para>
422
423 <screen>VBoxManage setextradata "VM name"
424 "VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/FlushInterval" [b]</screen>
425
426 <para>For SATA disks use the following command:</para>
427
428 <screen>VBoxManage setextradata "VM name"
429 "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/FlushInterval" [b]</screen>
430
431 <para>The value [x] that selects the disk for IDE is 0 for the master
432 device on the first channel, 1 for the slave device on the first
433 channel, 2 for the master device on the second channel or 3 for the
434 master device on the second channel. For SATA use values between 0 and
435 29. Only disks support this configuration option; it must not be set for
436 CD/DVD drives.</para>
437
438 <para>The unit of the interval [b] is the number of bytes written since
439 the last flush. The value for it must be selected so that the occasional
440 long write delays do not occur. Since the proper flush interval depends
441 on the performance of the host and the host filesystem, finding the
442 optimal value that makes the problem disappear requires some
443 experimentation. Values between 1000000 and 10000000 (1 to 10 megabytes)
444 are a good starting point. Decreasing the interval both decreases the
445 probability of the problem and the write performance of the guest.
446 Setting the value unnecessarily low will cost performance without
447 providing any benefits. An interval of 1 will cause a flush for each
448 write operation and should solve the problem in any case, but has a
449 severe write performance penalty.</para>
450
451 <para>Providing a value of 0 for [b] is treated as an infinite flush
452 interval, effectively disabling this workaround. Removing the extra data
453 key by specifying no value for [b] has the same effect.</para>
454 </sect2>
455
456 <sect2>
457 <title>Responding to guest IDE/SATA flush requests</title>
458
459 <para>If desired, the virtual disk images can be flushed when the guest
460 issues the IDE FLUSH CACHE command. Normally these requests are ignored
461 for improved performance. The parameters below are only accepted for
462 disk drives. They must not be set for DVD drives.</para>
463
464 <para>To enable flushing for IDE disks, issue the following
465 command:</para>
466
467 <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/IgnoreFlush" 0</screen>
468
469 <para>The value [x] that selects the disk is 0 for the master device on
470 the first channel, 1 for the slave device on the first channel, 2 for
471 the master device on the second channel or 3 for the master device on
472 the second channel.</para>
473
474 <para>To enable flushing for SATA disks, issue the following
475 command:</para>
476
477 <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/IgnoreFlush" 0</screen>
478
479 <para>The value [x] that selects the disk can be a value between 0 and
480 29.</para>
481
482 <para>Note that this doesn't affect the flushes performed according to
483 the configuration described in <xref linkend="configPeriodicFlush"
484 xrefstyle="template: %n" />. Restoring the default of ignoring flush
485 commands is possible by setting the value to 1 or by removing the
486 key.</para>
487 </sect2>
488 </sect1>
489
490 <sect1>
491 <title>Windows guests</title>
492
493 <sect2>
494 <title>Windows bluescreens after changing VM configuration</title>
495
496 <para>Changing certain virtual machine settings can cause Windows guests
497 to fail during start up with a bluescreen. This may happen if you change
498 VM settings after installing Windows, or if you copy a disk image with
499 an already installed Windows to a newly created VM which has settings
500 that differ from the original machine.</para>
501
502 <para>This applies in particular to the following settings:<itemizedlist>
503 <listitem>
504 <para>The ACPI and I/O APIC settings should never be changed after
505 installing Windows. Depending on the presence of these hardware
506 features, the Windows installation program chooses special kernel
507 and device driver versions and will fail to startup should these
508 hardware features be removed. (Enabling them for a Windows VM
509 which was installed without them does not cause any harm. However,
510 Windows will not use these features in this case.)</para>
511 </listitem>
512
513 <listitem>
514 <para>Changing the storage controller hardware will cause bootup
515 failures as well. This might also apply to you if you copy a disk
516 image from an older version of VirtualBox to a virtual machine
517 created with a newer VirtualBox version; the default subtype of
518 IDE controller hardware was changed from PIIX3 to PIIX4 with
519 VirtualBox 2.2. Make sure these settings are identical.</para>
520 </listitem>
521 </itemizedlist></para>
522 </sect2>
523
524 <sect2>
525 <title>Windows 0x101 bluescreens with SMP enabled (IPI timeout)</title>
526
527 <para>If a VM is configured to have more than one processor (symmetrical
528 multiprocessing, SMP), some configurations of Windows guests crash with
529 an 0x101 error message, indicating a timeout for inter-processor
530 interrupts (IPIs). These interrupts synchronize memory management
531 between processors.</para>
532
533 <para>According to Microsoft, this is due to a race condition in
534 Windows. A hotfix is available.<footnote>
535 <para>See <ulink
536 url="http://support.microsoft.com/kb/955076">http://support.microsoft.com/kb/955076</ulink>.</para>
537 </footnote> If this does not help, please reduce the number of virtual
538 processors to 1.</para>
539 </sect2>
540
541 <sect2>
542 <title>Windows 2000 installation failures</title>
543
544 <para>When installing Windows 2000 guests, you might run into one of the
545 following issues:</para>
546
547 <itemizedlist>
548 <listitem>
549 <para>Installation reboots, usually during component
550 registration.</para>
551 </listitem>
552
553 <listitem>
554 <para>Installation fills the whole hard disk with empty log
555 files.</para>
556 </listitem>
557
558 <listitem>
559 <para>Installation complains about a failure installing
560 <literal>msgina.dll</literal>.</para>
561 </listitem>
562 </itemizedlist>
563
564 <para>These problems are all caused by a bug in the hard disk driver of
565 Windows 2000. After issuing a hard disk request, there is a race
566 condition in the Windows driver code which leads to corruption if the
567 operation completes too fast, i.e. the hardware interrupt from the IDE
568 controller arrives too soon. With physical hardware, there is a
569 guaranteed delay in most systems so the problem is usually hidden there
570 (however it should be possible to reproduce it on physical hardware as
571 well). In a virtual environment, it is possible for the operation to be
572 done immediately (especially on very fast systems with multiple CPUs)
573 and the interrupt is signaled sooner than on a physical system. The
574 solution is to introduce an artificial delay before delivering such
575 interrupts. This delay can be configured for a VM using the following
576 command:</para>
577
578 <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/piix3ide/0/Config/IRQDelay" 1</screen>
579
580 <para>This sets the delay to one millisecond. In case this doesn't help,
581 increase it to a value between 1 and 5 milliseconds. Please note that
582 this slows down disk performance. After installation, you should be able
583 to remove the key (or set it to 0).</para>
584 </sect2>
585
586 <sect2>
587 <title>How to record bluescreen information from Windows guests</title>
588
589 <para>When Windows guests run into a kernel crash, they display the
590 infamous bluescreen. Depending on how Windows is configured, the
591 information will remain on the screen until the machine is restarted or
592 it will reboot automatically. During installation, Windows is usually
593 configured to reboot automatically. With automatic reboots, there is no
594 chance to record the bluescreen information which might be important for
595 problem determination.</para>
596
597 <para>VirtualBox provides a method of halting a guest when it wants to
598 perform a reset. In order to enable this feature, issue the following
599 command:</para>
600
601 <para><screen>VBoxManage setextradata "VM name" "VBoxInternal/PDM/HaltOnReset" 1</screen></para>
602 </sect2>
603
604 <sect2>
605 <title>No networking in Windows Vista guests</title>
606
607 <para>Unfortunately, with Vista, Microsoft dropped support for the
608 virtual AMD PCNet card that we are providing to virtual machines. As a
609 result, after installation, Vista guests initially have no networking.
610 VirtualBox therefore ships a driver for that card with the Windows Guest
611 Additions; see <xref linkend="vista_networking" />.</para>
612
613 <para>Starting with version 1.6.0 VirtualBox can emulate an Intel E1000
614 network device which is supported by Vista without any third-party
615 drivers.</para>
616 </sect2>
617
618 <sect2>
619 <title>Windows guests may cause a high CPU load</title>
620
621 <para>Several background applications of Windows guests, especially
622 virus scanners, are known to increases the CPU load notably even if the
623 guest appears to be idle. We recommend to deactivate virus scanners
624 within virtualized guests if possible.</para>
625 </sect2>
626
627 <sect2 id="win7_audio">
628 <title>No audio in Windows Vista (64-bit) and Windows 7 guests</title>
629
630 <para>32-bit Windows 7 does not ship with drivers for our emulated audio
631 hardware (AC'97). However, running Windows Update should solve the
632 problem by getting an appropriate driver for it automatically. After
633 that update followed by a reboot you should have working audio.</para>
634
635 <para>For the 64-bit versions of Windows Vista and 7 you have to
636 download the Realtek AC'97 drivers to enable audio.</para>
637
638 <para>See <ulink
639 url="http://www.realtek.com.tw/downloads">http://www.realtek.com.tw/downloads</ulink>
640 for download instructions.</para>
641 </sect2>
642 <sect2>
643 <title>Long delays when accessing shared folders</title>
644 <para>The performance for accesses to shared folders from a Windows guest
645 might be decreased due to delays during the resolution of the VirtualBox
646 shared folders name service. To fix these delays, add the following entries
647 to the file
648 <computeroutput>\windows\system32\drivers\etc\lmhosts</computeroutput>
649 of the Windows guest:</para>
650 <screen>255.255.255.255 VBOXSVR #PRE
651255.255.255.255 VBOXSRV #PRE</screen>
652 <para>After doing this change, a reboot of the guest is required.</para>
653 </sect2>
654
655 </sect1>
656
657 <sect1>
658 <title>Linux and X11 guests</title>
659
660 <sect2>
661 <title>Linux guests may cause a high CPU load</title>
662
663 <para>Some Linux guests may cause a high CPU load even if the guest
664 system appears to be idle. This can be caused by a high timer frequency
665 of the guest kernel. Some Linux distributions, for example Fedora, ship
666 a Linux kernel configured for a timer frequency of <emphasis
667 role="bold"> 1000Hz</emphasis>. We recommend to recompile the guest
668 kernel and to select a timer frequency of 100Hz.</para>
669
670 <para>Linux kernels shipped with Red Hat Enterprise Linux (RHEL) as of
671 release 4.7 and 5.1 as well as kernels of related Linux distributions
672 (for instance CentOS and Oracle Enterprise Linux) support a kernel
673 parameter <emphasis>divider=N</emphasis>. Hence, such kernels support a
674 lower timer frequency without recompilation. We suggest to add the
675 kernel parameter <emphasis>divider=10</emphasis> to select a guest
676 kernel timer frequency of 100Hz.</para>
677 </sect2>
678
679 <sect2>
680 <title>AMD Barcelona CPUs</title>
681
682 <para>Most Linux-based guests will fail with AMD Phenoms or
683 Barcelona-level Opterons due to a bug in the Linux kernel. Enable the
684 I/O-APIC to work around the problem (see <xref
685 linkend="settings-general-advanced" />).</para>
686 </sect2>
687
688 <sect2 id="trouble-linux-buggy">
689 <title>Buggy Linux 2.6 kernel versions</title>
690
691 <para>The following bugs in Linux kernels prevent them from executing
692 correctly in VirtualBox, causing VM boot crashes:<itemizedlist>
693 <listitem>
694 <para>The Linux kernel version 2.6.18 (and some 2.6.17 versions)
695 introduced a race condition that can cause boot crashes in
696 VirtualBox. Please use a kernel version 2.6.19 or later.</para>
697 </listitem>
698
699 <listitem>
700 <para>With hardware virtualization and the I/O APIC enabled,
701 kernels before 2.6.24-rc6 may panic on boot with the following
702 message:<screen>Kernel panic - not syncing: IO-APIC + timer doesn't work! Boot with
703apic=debug and send a report. Then try booting with the 'noapic' option</screen></para>
704
705 <para>If you see this message, either disable hardware
706 virtualization or the I/O APIC (see <xref
707 linkend="settings-system" />), or upgrade the guest to a newer
708 kernel.<footnote>
709 <para>See <ulink
710 url="http://www.mail-archive.com/[email protected]/msg30813.html">http://www.mail-archive.com/[email protected]/msg30813.html</ulink>
711 for details about the kernel fix.</para>
712 </footnote></para>
713 </listitem>
714 </itemizedlist></para>
715 </sect2>
716
717 <sect2>
718 <title>Shared clipboard, auto-resizing and seamless desktop in X11
719 guests</title>
720
721 <para>Guest desktop services in guests running the X11 window system
722 (Solaris, Linux and others) are provided by a guest service called
723 <computeroutput>VBoxClient</computeroutput>, which runs under the ID of
724 the user who started the desktop session and is automatically started
725 using the following command lines <screen>VBoxClient --clipboard
726VBoxClient --display
727VBoxClient --seamless</screen> when your X11 user session is started
728 if you are using a common desktop environment (Gnome, KDE and others).
729 If a particular desktop service is not working correctly, it is worth
730 checking whether the process which should provide it is running.</para>
731
732 <para>The <computeroutput>VBoxClient</computeroutput> processes create
733 files in the user's home directory with names of the form
734 <computeroutput>.vboxclient-*.pid</computeroutput> when they are running
735 in order to prevent a given service from being started twice. It can
736 happen due to misconfiguration that these files are created owned by
737 root and not deleted when the services are stopped, which will prevent
738 them from being started in future sessions. If the services cannot be
739 started, you may wish to check whether these files still exist.</para>
740 </sect2>
741 </sect1>
742
743 <sect1>
744 <title>Windows hosts</title>
745
746 <sect2>
747 <title>VBoxSVC out-of-process COM server issues</title>
748
749 <para>VirtualBox makes use of the Microsoft Component Object Model (COM)
750 for inter- and intra-process communication. This allows VirtualBox to
751 share a common configuration among different virtual machine processes
752 and provide several user interface options based on a common
753 architecture. All global status information and configuration is
754 maintained by the process <computeroutput>VBoxSVC.exe</computeroutput>,
755 which is an out-of-process COM server. Whenever a VirtualBox process is
756 started, it requests access to the COM server and Windows automatically
757 starts the process. Note that it should never be started by the end
758 user.</para>
759
760 <para>When the last process disconnects from the COM server, it will
761 terminate itself after some seconds. The VirtualBox configuration (XML
762 files) is maintained and owned by the COM server and the files are
763 locked whenever the server runs.</para>
764
765 <para>In some cases - such as when a virtual machine is terminated
766 unexpectedly - the COM server will not notice that the client is
767 disconnected and stay active for a longer period (10 minutes or so)
768 keeping the configuration files locked. In other rare cases the COM
769 server might experience an internal error and subsequently other
770 processes fail to initialize it. In these situations, it is recommended
771 to use the Windows task manager to kill the process
772 <computeroutput>VBoxSVC.exe</computeroutput>.</para>
773 </sect2>
774
775 <sect2>
776 <title>CD/DVD changes not recognized</title>
777
778 <para>In case you have assigned a physical CD/DVD drive to a guest and
779 the guest does not notice when the medium changes, make sure that the
780 Windows media change notification (MCN) feature is not turned off. This
781 is represented by the following key in the Windows registry:<screen><literal>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Cdrom\Autorun</literal></screen>Certain
782 applications may disable this key against Microsoft's advice. If it is
783 set to 0, change it to 1 and reboot your system. VirtualBox relies on
784 Windows notifying it of media changes.</para>
785 </sect2>
786
787 <sect2>
788 <title>Sluggish response when using Microsoft RDP client</title>
789
790 <para>If connecting to a Virtual Machine via the Microsoft RDP client
791 (called Remote Desktop Connection), there can be large delays between
792 input (moving the mouse over a menu is the most obvious situation) and
793 output. This is because this RDP client collects input for a certain
794 time before sending it to the VRDP server built into VirtualBox.</para>
795
796 <para>The interval can be decreased by setting a Windows registry key to
797 smaller values than the default of 100. The key does not exist initially
798 and must be of type DWORD. The unit for its values is milliseconds.
799 Values around 20 are suitable for low-bandwidth connections between the
800 RDP client and server. Values around 4 can be used for a gigabit
801 Ethernet connection. Generally values below 10 achieve a performance
802 that is very close to that of the local input devices and screen of the
803 host on which the Virtual Machine is running.</para>
804
805 <para>Depending whether the setting should be changed for an individual
806 user or for the system, either</para>
807
808 <screen>HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client\Min Send Interval</screen>
809
810 <para>or</para>
811
812 <screen>HKEY_LOCAL_MACHINE\Software\Microsoft\Terminal Server Client\Min Send Interval</screen>
813
814 <para>can be set appropriately.</para>
815 </sect2>
816
817 <sect2>
818 <title>Running an iSCSI initiator and target on a single system</title>
819
820 <para>Deadlocks can occur on a Windows host when attempting to access an
821 iSCSI target running in a guest virtual machine with an iSCSI initiator
822 (e.g. Microsoft iSCSI Initiator) that is running on the host. This is
823 caused by a flaw in the Windows cache manager component, and causes
824 sluggish host system response for several minutes, followed by a
825 "Delayed Write Failed" error message in the system tray or in a separate
826 message window. The guest is blocked during that period and may show
827 error messages or become unstable.</para>
828
829 <para>Setting the environment variable
830 <computeroutput>VBOX_DISABLE_HOST_DISK_CACHE</computeroutput> to 1 will
831 enable a workaround for this problem until Microsoft addresses the
832 issue. For example, open a command prompt window and start VirtualBox
833 like this:</para>
834
835 <screen>set VBOX_DISABLE_HOST_DISK_CACHE=1
836VirtualBox</screen>
837
838 <para>While this will decrease guest disk performance (especially
839 writes), it does not affect the performance of other applications
840 running on the host.</para>
841 </sect2>
842 </sect1>
843
844 <sect1>
845 <title>Linux hosts</title>
846
847 <sect2 id="linuxkernelmodulefailstoload">
848 <title>Linux kernel module refuses to load</title>
849
850 <para>If the VirtualBox kernel module
851 (<computeroutput>vboxdrv</computeroutput>) refuses to load, i.e. you get
852 an "Error inserting vboxdrv: Invalid argument", check (as root) the
853 output of the <computeroutput>dmesg</computeroutput> command to find out
854 why the load failed. The most common reasons are:</para>
855
856 <itemizedlist>
857 <listitem>
858 <para>With Linux 2.6.19 and higher, the NMI watchdog may be active.
859 Add <computeroutput>nmi_watchdog=0</computeroutput> to the kernel
860 command line (e.g. in your grub configuration) and reboot. With the
861 Debian and Ubuntu installation modules, execute <computeroutput>sudo
862 dpkg-reconfigure virtualbox</computeroutput> again.</para>
863 </listitem>
864
865 <listitem>
866 <para>The kernel disagrees about the version of the gcc used to
867 compile the module. Make sure that you use the same compiler as used
868 to build the kernel.</para>
869 </listitem>
870 </itemizedlist>
871 </sect2>
872
873 <sect2>
874 <title>Linux host CD/DVD drive not found</title>
875
876 <para>If you have configured a virtual machine to use the host's CD/DVD
877 drive, but this does not appear to work, make sure that the current user
878 has permission to access the corresponding Linux device file
879 (<computeroutput>/dev/hdc</computeroutput> or
880 <computeroutput>/dev/scd0</computeroutput> or
881 <computeroutput>/dev/cdrom</computeroutput> or similar). On most
882 distributions, the user must be added to a corresponding group (usually
883 called <computeroutput>cdrom</computeroutput> or
884 <computeroutput>cdrw</computeroutput>).</para>
885 </sect2>
886
887 <sect2>
888 <title>Linux host CD/DVD drive not found (older distributions)</title>
889
890 <para>On older Linux distributions, if your CD/DVD device has a
891 different name, VirtualBox may be unable to find it. On older Linux
892 hosts, VirtualBox performs the following steps to locate your CD/DVD
893 drives:</para>
894
895 <para><orderedlist>
896 <listitem>
897 <para>VirtualBox examines if the environment variable
898 <computeroutput>VBOX_CDROM</computeroutput> is defined (see
899 below). If so, VirtualBox omits all the following checks.</para>
900 </listitem>
901
902 <listitem>
903 <para>VirtualBox tests if
904 <computeroutput>/dev/cdrom</computeroutput> works.</para>
905 </listitem>
906
907 <listitem>
908 <para>In addition, VirtualBox checks if any CD/DVD drives are
909 currently mounted by checking
910 <computeroutput>/etc/mtab</computeroutput>.</para>
911 </listitem>
912
913 <listitem>
914 <para>In addition, VirtualBox checks if any of the entries in
915 <computeroutput>/etc/fstab</computeroutput> point to CD/DVD
916 devices.</para>
917 </listitem>
918 </orderedlist></para>
919
920 <para>In other words, you can try to set VBOX_CDROM to contain a list of
921 your CD/DVD devices, separated by colons, for example as follows:</para>
922
923 <para><screen>export VBOX_CDROM='/dev/cdrom0:/dev/cdrom1'</screen>On
924 modern Linux distributions, VirtualBox uses the hardware abstraction
925 layer (hal) to locate CD and DVD hardware.</para>
926 </sect2>
927
928 <sect2>
929 <title>Linux host floppy not found</title>
930
931 <para>The previous instructions (for CD and DVD drives) apply
932 accordingly to floppy disks, except that on older distributions
933 VirtualBox tests for <computeroutput>/dev/fd*</computeroutput> devices
934 by default, and this can be overridden with the
935 <computeroutput>VBOX_FLOPPY</computeroutput> environment
936 variable.</para>
937 </sect2>
938
939 <sect2>
940 <title>Strange guest IDE error messages when writing to CD/DVD</title>
941
942 <para>If the experimental CD/DVD writer support is enabled with an
943 incorrect VirtualBox, host or guest configuration, it is possible that
944 any attempt to access the CD/DVD writer fails and simply results in
945 guest kernel error messages (for Linux guests) or application error
946 messages (for Windows guests). VirtualBox performs the usual consistency
947 checks when a VM is powered up (in particular it aborts with an error
948 message if the device for the CD/DVD writer is not writable by the user
949 starting the VM), but it cannot detect all misconfigurations. The
950 necessary host and guest OS configuration is not specific for
951 VirtualBox, but a few frequent problems are listed here which occurred
952 in connection with VirtualBox.</para>
953
954 <para>Special care must be taken to use the correct device. The
955 configured host CD/DVD device file name (in most cases
956 <literal>/dev/cdrom</literal>) must point to the device that allows
957 writing to the CD/DVD unit. For CD/DVD writer units connected to a SCSI
958 controller or to a IDE controller that interfaces to the Linux SCSI
959 subsystem (common for some SATA controllers), this must refer to the
960 SCSI device node (e.g. <literal>/dev/scd0</literal>). Even for IDE
961 CD/DVD writer units this must refer to the appropriate SCSI CD-ROM
962 device node (e.g. <literal>/dev/scd0</literal>) if the
963 <literal>ide-scsi</literal> kernel module is loaded. This module is
964 required for CD/DVD writer support with all Linux 2.4 kernels and some
965 early 2.6 kernels. Many Linux distributions load this module whenever a
966 CD/DVD writer is detected in the system, even if the kernel would
967 support CD/DVD writers without the module. VirtualBox supports the use
968 of IDE device files (e.g. <literal>/dev/hdc</literal>), provided the
969 kernel supports this and the <literal>ide-scsi</literal> module is not
970 loaded.</para>
971
972 <para>Similar rules (except that within the guest the CD/DVD writer is
973 always an IDE device) apply to the guest configuration. Since this setup
974 is very common, it is likely that the default configuration of the guest
975 works as expected.</para>
976 </sect2>
977
978 <sect2>
979 <title>VBoxSVC IPC issues</title>
980
981 <para>On Linux, VirtualBox makes use of a custom version of Mozilla
982 XPCOM (cross platform component object model) for inter- and
983 intra-process communication (IPC). The process
984 <computeroutput>VBoxSVC</computeroutput> serves as a communication hub
985 between different VirtualBox processes and maintains the global
986 configuration, i.e. the XML database. When starting a VirtualBox
987 component, the processes <computeroutput>VBoxSVC</computeroutput> and
988 <computeroutput>VirtualBoxXPCOMIPCD</computeroutput> are started
989 automatically. They are only accessible from the user account they are
990 running under. <computeroutput>VBoxSVC</computeroutput> owns the
991 VirtualBox configuration database which normally resides in
992 <computeroutput>~/.VirtualBox</computeroutput>. While it is running, the
993 configuration files are locked. Communication between the various
994 VirtualBox components and <computeroutput>VBoxSVC</computeroutput> is
995 performed through a local domain socket residing in
996 <computeroutput>/tmp/.vbox-&lt;username&gt;-ipc</computeroutput>. In
997 case there are communication problems (i.e. a VirtualBox application
998 cannot communicate with <computeroutput>VBoxSVC</computeroutput>),
999 terminate the daemons and remove the local domain socket
1000 directory.</para>
1001 </sect2>
1002
1003 <sect2 id="usb_linux">
1004 <title>USB not working</title>
1005
1006 <para>If USB is not working on your Linux host, make sure that the
1007 current user is a member of the
1008 <computeroutput>vboxusers</computeroutput> group. On older hosts, you
1009 need to make sure that the user has permission to access the USB
1010 filesystem (<computeroutput>usbfs</computeroutput>), which VirtualBox
1011 relies on to retrieve valid information about your host's USB devices.
1012 The rest of this section only applies to those older systems.</para>
1013
1014 <note>
1015 <para>The current rdesktop-vrdp implementation does not support
1016 accessing USB devices through the
1017 <computeroutput>sysfs</computeroutput>!</para>
1018 </note>
1019
1020 <para>As <computeroutput>usbfs</computeroutput> is a virtual filesystem,
1021 a <computeroutput>chmod</computeroutput> on
1022 <computeroutput>/proc/bus/usb</computeroutput> has no effect. The
1023 permissions for <computeroutput>usbfs</computeroutput> can therefore
1024 <emphasis>only</emphasis> be changed by editing the
1025 <computeroutput>/etc/fstab</computeroutput> file.</para>
1026
1027 <para>For example, most Linux distributions have a user group called
1028 <computeroutput>usb</computeroutput> or similar, of which the current
1029 user must be a member. To give all users of that group access to usbfs,
1030 make sure the following line is present:<screen># 85 is the USB group
1031none /proc/bus/usb usbfs devgid=85,devmode=664 0 0</screen>Replace
1032 85 with the group ID that matches your system (search
1033 <computeroutput>/etc/group</computeroutput> for "usb" or similar).
1034 Alternatively, if you don't mind the security hole, give all users
1035 access to USB by changing "664" to "666".</para>
1036
1037 <para>The various distributions are very creative from which script the
1038 <computeroutput>usbfs</computeroutput> filesystem is mounted. Sometimes
1039 the command is hidden in unexpected places. For SuSE 10.0 the mount
1040 command is part of the udev configuration file
1041 <computeroutput>/etc/udev/rules.d/50-udev.rules</computeroutput>. As
1042 this distribution has no user group called
1043 <computeroutput>usb</computeroutput>, you may e.g. use the
1044 <computeroutput>vboxusers</computeroutput> group which was created by
1045 the VirtualBox installer. Since group numbers are allocated dynamically,
1046 the following example uses 85 as a placeholder. Modify the line
1047 containing (a linebreak has been inserted to improve
1048 readability)<screen>DEVPATH="/module/usbcore", ACTION=="add",
1049 RUN+="/bin/mount -t usbfs usbfs /proc/bus/usb"</screen> and add the
1050 necessary options (make sure that everything is in a single
1051 line):<screen>DEVPATH="/module/usbcore", ACTION=="add",
1052 RUN+="/bin/mount -t usbfs usbfs /proc/bus/usb -o devgid=85,devmode=664"</screen></para>
1053
1054 <para>Debian Etch has the mount command in
1055 <computeroutput>/etc/init.d/mountkernfs.sh</computeroutput>. Since that
1056 distribution has no group <computeroutput>usb</computeroutput>, it is
1057 also the easiest solution to allow all members of the group
1058 <computeroutput>vboxusers</computeroutput> to access the USB subsystem.
1059 Modify the line <screen>domount usbfs usbdevfs /proc/bus/usb -onoexec,nosuid,nodev</screen>
1060 so that it contains <screen>domount usbfs usbdevfs /proc/bus/usb -onoexec,nosuid,nodev,devgid=85,devmode=664</screen>
1061 As usual, replace the 85 with the actual group number which should get
1062 access to USB devices.</para>
1063
1064 <para>Other distributions do similar operations in scripts stored in the
1065 <computeroutput>/etc/init.d</computeroutput> directory.</para>
1066 </sect2>
1067
1068 <sect2>
1069 <title>PAX/grsec kernels</title>
1070
1071 <para>Linux kernels including the grsec patch (see <literal><ulink
1072 url="http://www.grsecurity.net/">http://www.grsecurity.net/</ulink></literal>)
1073 and derivates have to disable PAX_MPROTECT for the VBox binaries to be
1074 able to start a VM. The reason is that VBox has to create executable
1075 code on anonymous memory.</para>
1076 </sect2>
1077
1078 <sect2>
1079 <title>Linux kernel vmalloc pool exhausted</title>
1080
1081 <para>When running a large number of VMs with a lot of RAM on a Linux
1082 system (say 20 VMs with 1GB of RAM each), additional VMs might fail to
1083 start with a kernel error saying that the vmalloc pool is exhausted and
1084 should be extended. The error message also tells you to specify
1085 <computeroutput>vmalloc=256MB</computeroutput> in your kernel parameter
1086 list. If adding this parameter to your GRUB or LILO configuration makes
1087 the kernel fail to boot (with a weird error message such as "failed to
1088 mount the root partition"), then you have probably run into a memory
1089 conflict of your kernel and initial RAM disk. This can be solved by
1090 adding the following parameter to your GRUB configuration:</para>
1091
1092 <screen>uppermem 524288</screen>
1093 </sect2>
1094 </sect1>
1095
1096 <sect1>
1097 <title>Solaris hosts</title>
1098
1099 <sect2>
1100 <title>Cannot start VM, not enough contiguous memory</title>
1101
1102 <para>The ZFS file system is known to use all available RAM as cache if
1103 the default system settings are not changed. This may lead to a heavy
1104 fragmentation of the host memory preventing VirtualBox VMs from being
1105 started. We recommend to limit the ZFS cache by adding a line<screen>set zfs:zfs_arc_max = xxxx</screen>
1106 to /etc/system where <computeroutput>xxxx</computeroutput> bytes is the
1107 amount of memory usable for the ZFS cache.</para>
1108 </sect2>
1109
1110 <sect2>
1111 <title>VM aborts with out of memory errors on Solaris 10 hosts</title>
1112
1113 <para>Solaris 10 hosts (bug 1225025) requires swap space equal to, or
1114 greater than the host's physical memory size. For example, 8 GB physical
1115 memory would require at least 8 GB swap. This can be configured during a
1116 Solaris 10 install by choosing a 'custom install' and changing the
1117 default partitions.</para>
1118
1119 <para>For existing Solaris 10 installs, an additional swap image needs
1120 to be mounted and used as swap. Hence if you have 1 GB swap and 8 GB of
1121 physical memory, you require to add 7 GB more swap. This can be done as
1122 follows:</para>
1123
1124 <para>For ZFS (as root user):</para>
1125
1126 <para><screen>zfs create -V 8gb /_&lt;ZFS volume&gt;_/swap
1127swap -a /dev/zvol/dsk/_&lt;ZFS volume&gt;_/swap</screen></para>
1128
1129 <para>To mount if after reboot, add the following line to
1130 /etc/vfstab:</para>
1131
1132 <screen>/dev/zvol/dsk/_&lt;ZFS volume&gt;_/swap - - swap - no -</screen>
1133
1134 <para>Alternatively, you could grow the existing swap using:</para>
1135
1136 <screen>zfs set volsize=8G rpool/swap</screen>
1137
1138 <para>And reboot the system for the changes to take effect.</para>
1139
1140 <para>For UFS (as root user):</para>
1141
1142 <screen>mkfile 7g /path/to/swapfile.img
1143swap -a /path/to/swapfile.img</screen>
1144
1145 <para>To mount it after reboot, add the following line to
1146 /etc/vfstab:</para>
1147
1148 <screen>/path/to/swap.img - - swap - no -</screen>
1149 </sect2>
1150 </sect1>
1151</chapter>
Note: See TracBrowser for help on using the repository browser.

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