diff options
Diffstat (limited to 'doc/manual/en_US/user_Troubleshooting.xml')
| -rw-r--r-- | doc/manual/en_US/user_Troubleshooting.xml | 1916 |
1 files changed, 1916 insertions, 0 deletions
diff --git a/doc/manual/en_US/user_Troubleshooting.xml b/doc/manual/en_US/user_Troubleshooting.xml new file mode 100644 index 00000000..f7e4695d --- /dev/null +++ b/doc/manual/en_US/user_Troubleshooting.xml @@ -0,0 +1,1916 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2022 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="Troubleshooting"> + + <title>Troubleshooting</title> + + <para> + This chapter provides answers to commonly asked questions. In order + to improve your user experience with &product-name;, it is + recommended to read this section to learn more about common pitfalls + and get recommendations on how to use the product. + </para> + + <sect1 id="ts_procs-tools"> + + <title>Procedures and Tools</title> + + <sect2 id="ts_categorize-isolate"> + + <title>Categorizing and Isolating Problems</title> + + <para> + More often than not, a virtualized guest behaves like a physical + system. Any problems that a physical machine would encounter, a + virtual machine will encounter as well. If, for example, + Internet connectivity is lost due to external issues, virtual + machines will be affected just as much as physical ones. + </para> + + <para> + If a true &product-name; problem is encountered, it helps to + categorize and isolate the problem first. Here are some of the + questions that should be answered before reporting a problem: + </para> + + <itemizedlist> + + <listitem> + <para> + Is the problem specific to a certain guest OS? Or a specific + release of a guest OS? Especially with Linux guest related + problems, the issue may be specific to a certain + distribution and version of Linux. + </para> + </listitem> + + <listitem> + <para> + Is the problem specific to a certain host OS? Problems are + usually not host OS specific, because most of the + &product-name; code base is shared across all supported + platforms, but especially in the areas of networking and USB + support, there are significant differences between host + platforms. Some GUI related issues are also host specific. + </para> + </listitem> + + <listitem> + <para> + Is the problem specific to certain host hardware? This + category of issues is typically related to the host CPU. + Because of significant differences between VT-x and AMD-V, + problems may be specific to one or the other technology. The + exact CPU model may also make a difference because different + CPUs support different features, which may affect certain + aspects of guest CPU operation. + </para> + </listitem> + + <listitem> + <para> + Is the problem specific to guest SMP? That is, is it related + to the number of virtual CPUs (VCPUs) in the guest? Using + more than one CPU usually significantly affects the internal + operation of a guest OS. + </para> + </listitem> + + <listitem> + <para> + Is the problem specific to the Guest Additions? In some + cases, this is obvious, such as a shared folders problem. In + other cases such as display problems, it may be less + obvious. If the problem is Guest Additions specific, is it + also specific to a certain version of the Guest Additions? + </para> + </listitem> + + <listitem> + <para> + Is the problem specific to a certain environment? Some + problems are related to a particular environment external to + the VM. This usually involves network setup. Certain + configurations of external servers such as DHCP or PXE may + expose problems which do not occur with other, similar + servers. + </para> + </listitem> + + <listitem> + <para> + Is the problem a regression? Knowing that an issue is a + regression usually makes it significantly easier to find the + solution. In this case, it is crucial to know which version + is affected and which is not. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="collect-debug-info"> + + <title>Collecting Debugging Information</title> + + <para> + For problem determination, it is often important to collect + debugging information which can be analyzed by &product-name; + support. This section contains information about what kind of + information can be obtained. + </para> + + <para> + Every time &product-name; starts up a VM, a so-called + <emphasis>release log file</emphasis> is created, containing + lots of information about the VM configuration and runtime + events. The log file is called <filename>VBox.log</filename> and + resides in the VM log file folder, which is + <filename>$HOME/VirtualBox + VMs/<replaceable>VM-name</replaceable>/Logs</filename> by + default. + </para> + + <para> + When starting a VM, the configuration file of the last run will + be renamed to <filename>.1</filename>, up to + <filename>.3</filename>. Sometimes when there is a problem, it + is useful to have a look at the logs. Also when requesting + support for &product-name;, supplying the corresponding log file + is mandatory. + </para> + + <para> + For convenience, for each virtual machine, &vbox-mgr; can show + these logs in a window. Select a virtual machine from the + machine list on the left and click + <emphasis role="bold">Logs</emphasis> in the machine tools menu. + </para> + + <para> + The release log file, <filename>VBox.log</filename>, contains a + wealth of diagnostic information, such as Host OS type and + version, &product-name; version and build. It also includes a + complete dump of the guest's configuration (CFGM), detailed + information about the host CPU type and supported features, + whether hardware virtualization is enabled, information about + VT-x/AMD-V setup, state transitions (such as creating, running, + paused, stopping), guest BIOS messages, Guest Additions + messages, device-specific log entries and, at the end of + execution, final guest state and condensed statistics. + </para> + + <para> + In case of crashes, it is very important to collect + <emphasis>crash dumps</emphasis>. This is true for both host and + guest crashes. For information about enabling core dumps on + Linux, Oracle Solaris, and macOS systems, refer to the following + core dump article on the &product-name; website: + </para> + + <para> + <ulink url="http://www.virtualbox.org/wiki/Core_dump" />. + </para> + + <para> + You can also use <command>VBoxManage debugvm</command> to create + a dump of a complete virtual machine. See + <xref linkend="vboxmanage-debugvm" />. + </para> + + <para> + For network related problems, it is often helpful to capture a + trace of network traffic. If the traffic is routed through an + adapter on the host, it is possible to use Wireshark or a + similar tool to capture the traffic there. However, this often + also includes a lot of traffic unrelated to the VM. + </para> + + <para> + &product-name; provides an ability to capture network traffic + only on a specific VM's network adapter. Refer to the following + network tracing article on the &product-name; website for + information on enabling this capture: + </para> + + <para> + <ulink url="http://www.virtualbox.org/wiki/Network_tips" />. + </para> + + <para> + The trace files created by &product-name; are in + <filename>.pcap</filename> format and can be easily analyzed + with Wireshark. + </para> + + </sect2> + + <sect2 id="ts_vboxbugreport"> + + <title>Using the VBoxBugReport Command to Collect Debug Information + Automatically</title> + + <para> + The <command>VBoxBugReport</command> command is used to collect + debug information automatically for an &product-name; + installation. This command can be useful when you need to gather + information to send to Oracle Support. + </para> + + <para> + The following examples show how to use + <command>VBoxBugReport</command>. + </para> + + <para> + By default, the command collects <command>VBoxSVC</command> + process logs, device settings, and global configuration data for + an &product-name; host. + </para> + +<screen>$ VBoxBugReport + ... + 0% - collecting VBoxSVC.log.10... + 7% - collecting VBoxSVC.log.9... + ... + 64% - collecting VBoxSVC.log.1... + 71% - collecting VBoxSVC.log... + 78% - collecting VirtualBox.xml... + 85% - collecting HostUsbDevices... + 92% - collecting HostUsbFilters... +100% - compressing... + +Report was written to '2019-03-26-13-32-02-bugreport.tgz'</screen> + + <para> + The results are saved as a compressed tar file archive in the + same directory where the command is run. + </para> + + <para> + To specify a different output file location: + </para> + +<screen>$ VBoxBugReport --output ~/debug/bug004.tgz</screen> + + <para> + To output all debug information to a single text file, rather + than a <filename>tgz</filename> file: + </para> + +<screen>$ VBoxBugReport --text</screen> + + <para> + To collect information for a specific VM, called + <literal>Windows_10</literal>: + </para> + +<screen>$ VBoxBugReport Windows_10</screen> + + <para> + This command collects machine settings, guest properties, and + log files for the specified VM. Global configuration information + for the host is also included. + </para> + + <para> + To collect information for several VMs, called + <literal>Windows_7</literal>, <literal>Windows_8</literal>, and + <literal>Windows_10</literal>: + </para> + +<screen>$ VBoxBugReport Windows_7 Windows_8 Windows_10</screen> + + <para> + To collect information for all VMs: + </para> + +<screen>$ VBoxBugReport --all</screen> + + <para> + To show a full list of the available command options, run + <command>VBoxBugReport --help</command>. + </para> + + </sect2> + + <sect2 id="ts_debugger"> + + <title>The Built-In VM Debugger</title> + + <para> + &product-name; includes a built-in VM debugger, which advanced + users may find useful. This debugger enables you to examine and, + to some extent, control the VM state. + </para> + + <warning> + <para> + Use the VM debugger at your own risk. There is no support for + it, and the following documentation is only made available for + advanced users with a very high level of familiarity with the + x86/AMD64 machine instruction set, as well as detailed + knowledge of the PC architecture. A degree of familiarity with + the internals of the guest OS in question may also be very + helpful. + </para> + </warning> + + <para> + The VM debugger is available in all regular production versions + of &product-name;, but it is disabled by default because the + average user will have little use for it. There are two ways to + access the debugger: + </para> + + <itemizedlist> + + <listitem> + <para> + Using a debugger console window displayed alongside the VM + </para> + </listitem> + + <listitem> + <para> + Using the <command>telnet</command> protocol on port 5000 + </para> + </listitem> + + </itemizedlist> + + <para> + The debugger can be enabled in the following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + Start the VM directly using <command>VirtualBoxVM + --startvm</command>, with an additional + <option>--dbg</option>, <option>--debug</option>, or + <option>--debug-command-line</option> argument. See the + <command>VirtualBoxVM --help</command> command usage help + for details. + </para> + </listitem> + + <listitem> + <para> + Set the <literal>VBOX_GUI_DBG_ENABLED</literal> or + <literal>VBOX_GUI_DBG_AUTO_SHOW</literal> environment + variable to <literal>true</literal> before launching the + &product-name; process. Setting these variables, only their + presence is checked, is effective even when the first + &product-name; process is the VM selector window. VMs + subsequently launched from the selector will have the + debugger enabled. + </para> + </listitem> + + <listitem> + <para> + Set the <literal>GUI/Dbg/Enabled</literal> extra data item + to <literal>true</literal> before launching the VM. This can + be set globally or on a per VM basis. + </para> + </listitem> + + </itemizedlist> + + <para> + A new <emphasis role="bold">Debug</emphasis> menu entry is added + to the &product-name; application. This menu enables the user to + open the debugger console. + </para> + + <para> + The VM debugger command syntax is loosely modeled on Microsoft + and IBM debuggers used on DOS, OS/2, and Windows. Users familiar + with symdeb, CodeView, or the OS/2 kernel debugger will find the + &product-name; VM debugger familiar. + </para> + + <para> + The most important command is <command>help</command>. This will + print brief usage help for all debugger commands. The set of + commands supported by the VM debugger changes frequently and the + <command>help</command> command is always up-to-date. + </para> + + <para> + A brief summary of frequently used commands is as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>stop</command>: Stops the VM execution and enables + single stepping + </para> + </listitem> + + <listitem> + <para> + <command>g</command>: Continue VM execution + </para> + </listitem> + + <listitem> + <para> + <command>t</command>: Single step an instruction + </para> + </listitem> + + <listitem> + <para> + <command>rg</command>, <command>rh</command>, and + <command>r</command>: Print the guest, hypervisor, and + current registers + </para> + </listitem> + + <listitem> + <para> + <command>kg</command>, <command>kh</command>, and + <command>k</command>: Print the guest, hypervisor, and + current call stack + </para> + </listitem> + + <listitem> + <para> + <command>da</command>, <command>db</command>, + <command>dw</command>, <command>dd</command>, + <command>dq</command>: Print memory contents as ASCII, + bytes, words, dwords, and qwords + </para> + </listitem> + + <listitem> + <para> + <command>u</command>: Unassemble memory + </para> + </listitem> + + <listitem> + <para> + <command>dg</command>: Print the guest's GDT + </para> + </listitem> + + <listitem> + <para> + <command>di</command>: Print the guest's IDT + </para> + </listitem> + + <listitem> + <para> + <command>dl</command>: Print the guest's LDT + </para> + </listitem> + + <listitem> + <para> + <command>dt</command>: Print the guest's TSS + </para> + </listitem> + + <listitem> + <para> + <command>dp*</command>: Print the guest's page table + structures + </para> + </listitem> + + <listitem> + <para> + <command>bp</command> and <command>br</command>: Set a + normal and recompiler breakpoint + </para> + </listitem> + + <listitem> + <para> + <command>bl</command>: List breakpoints + </para> + </listitem> + + <listitem> + <para> + <command>bc</command>: Clear a breakpoint + </para> + </listitem> + + <listitem> + <para> + <command>writecore</command>: Write a VM core file to disk. + See <xref linkend="ts_guest-core-format" /> + </para> + </listitem> + + </itemizedlist> + + <para> + See the built-in <command>help</command> for other available + commands. + </para> + + <para> + The VM debugger supports symbolic debugging, although symbols + for guest code are often not available. For Oracle Solaris + guests, the <command>detect</command> command automatically + determines the guest OS version and locates kernel symbols in + guest's memory. Symbolic debugging is then available. For Linux + guests, the <command>detect</command> commands also determines + the guest OS version, but there are no symbols in the guest's + memory. Kernel symbols are available in the file + <filename>/proc/kallsyms</filename> on Linux guests. This file + must be copied to the host, for example using + <command>scp</command>. The <command>loadmap</command> debugger + command can be used to make the symbol information available to + the VM debugger. Note that the <filename>kallsyms</filename> + file contains the symbols for the currently loaded modules. If + the guest's configuration changes, the symbols will change as + well and must be updated. + </para> + + <para> + For all guests, a simple way to verify that the correct symbols + are loaded is the <command>k</command> command. The guest is + normally idling and it should be clear from the symbolic + information that the guest operating system's idle loop is being + executed. + </para> + + <para> + Another group of debugger commands is the set of + <command>info</command> commands. Running <command>info + help</command> provides complete usage information. The + information commands provide ad-hoc data pertinent to various + emulated devices and aspects of the VMM. There is no general + guideline for using the <command>info</command> commands, the + right command to use depends entirely on the problem being + investigated. Some of the <command>info</command> commands are + as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>cfgm</command>: Print a branch of the configuration + tree + </para> + </listitem> + + <listitem> + <para> + <command>cpuid</command>: Display the guest CPUID leaves + </para> + </listitem> + + <listitem> + <para> + <command>ioport</command>: Print registered I/O port ranges + </para> + </listitem> + + <listitem> + <para> + <command>mmio</command>: Print registered MMIO ranges + </para> + </listitem> + + <listitem> + <para> + <command>mode</command>: Print the current paging mode + </para> + </listitem> + + <listitem> + <para> + <command>pit</command>: Print the i8254 PIT state + </para> + </listitem> + + <listitem> + <para> + <command>pic</command>: Print the i8259A PIC state + </para> + </listitem> + + <listitem> + <para> + <command>ohci</command>, <command>ehci</command>, + <command>xhci</command>: Print a subset of the OHCI, EHCI, + and xHCI USB controller state + </para> + </listitem> + + <listitem> + <para> + <command>pcnet0</command>: Print the PCnet state + </para> + </listitem> + + <listitem> + <para> + <command>vgatext</command>: Print the contents of the VGA + framebuffer formatted as standard text mode + </para> + </listitem> + + <listitem> + <para> + <command>timers</command>: Print all VM timers + </para> + </listitem> + + </itemizedlist> + + <para> + The output of the <command>info</command> commands generally + requires in-depth knowledge of the emulated device or + &product-name; VMM internals. However, when used properly, the + information provided can be invaluable. + </para> + + </sect2> + + <sect2 id="ts_guest-core-format"> + + <title>VM Core Format</title> + + <para> + &product-name; uses the 64-bit ELF format for its VM core files + created by <command>VBoxManage debugvm</command>, see + <xref linkend="vboxmanage-debugvm" />. The VM core file contain + the memory and CPU dumps of the VM and can be useful for + debugging your guest OS. The 64-bit ELF object format + specification can be obtained at: + </para> + + <para> + <ulink url="http://downloads.openwatcom.org/ftp/devel/docs/elf-64-gen.pdf" />. + </para> + + <para> + The overall layout of the VM core format is as follows: + </para> + +<screen>[ ELF 64 Header] +[ Program Header, type PT_NOTE ] + → offset to COREDESCRIPTOR +[ Program Header, type PT_LOAD ] - one for each contiguous physical memory range + → Memory offset of range + → File offset +[ Note Header, type NT_VBOXCORE ] +[ COREDESCRIPTOR ] + → Magic + → VM core file version + → VBox version + → Number of vCPUs etc. +[ Note Header, type NT_VBOXCPU ] - one for each vCPU +[ vCPU 1 Note Header ] + [ DBGFCORECPU - vCPU 1 dump ] +[ Additional Notes + Data ] - currently unused +[ Memory dump ]</screen> + + <para> + The memory descriptors contain physical addresses relative to + the guest and not virtual addresses. Regions of memory such as + MMIO regions are not included in the core file. + </para> + + <para> + The relevant data structures and definitions can be found in the + &product-name; sources under the following header files: + <filename>include/VBox/dbgfcorefmt.h</filename>, + <filename>include/iprt/x86.h</filename> and + <filename>src/VBox/Runtime/include/internal/ldrELFCommon.h</filename>. + </para> + + <para> + The VM core file can be inspected using + <command>elfdump</command> and GNU <command>readelf</command> or + other similar utilities. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_general"> + + <title>General Troubleshooting</title> + + <sect2 id="ts_config-periodic-flush"> + + <title>Guest Shows IDE/SATA Errors for File-Based Images on Slow Host File + System</title> + + <para> + Occasionally, some host file systems provide very poor writing + performance and as a consequence cause the guest to time out + IDE/SATA commands. This is normal behavior and should normally + cause no real problems, as the guest should repeat commands that + have timed out. However, guests such as some Linux versions have + severe problems if a write to an image file takes longer than + about 15 seconds. Some file systems however require more than a + minute to complete a single write, if the host cache contains a + large amount of data that needs to be written. + </para> + + <para> + The symptom for this problem is that the guest can no longer + access its files during large write or copying operations, + usually leading to an immediate hang of the guest. + </para> + + <para> + In order to work around this problem, the true fix is to use a + faster file system that does not exhibit such unacceptable write + performance, it is possible to flush the image file after a + certain amount of data has been written. This interval is + normally infinite, but can be configured individually for each + disk of a VM. + </para> + + <para> + For IDE disks use the following command: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> +"VBoxInternal/Devices/piix3ide/0/LUN#[<replaceable>x</replaceable>]/Config/FlushInterval" [<replaceable>b</replaceable>]</screen> + + <para> + For SATA disks use the following command: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> +"VBoxInternal/Devices/ahci/0/LUN#[<replaceable>x</replaceable>]/Config/FlushInterval" [<replaceable>b</replaceable>]</screen> + + <para> + <literal>[<replaceable>x</replaceable>]</literal> specifies the + disk. For IDE, <literal>0</literal> represents device 0 on the + primary channel, <literal>1</literal> represents device 1 on the + primary channel, <literal>2</literal> represents device 0 on the + secondary channel, and <literal>3</literal> represents device 1 + on the secondary channel. For SATA, use values between + <literal>0</literal> and <literal>29</literal>. This + configuration option applies to disks only. Do not use this + option for CD or DVD drives. + </para> + + <para> + The unit of the interval + (<literal>[<replaceable>b</replaceable>]</literal>) is the + number of bytes written since the last flush. The value for it + must be selected so that the occasional long write delays do not + occur. Since the proper flush interval depends on the + performance of the host and the host filesystem, finding the + optimal value that makes the problem disappear requires some + experimentation. Values between 1000000 and 10000000 (1 to 10 + megabytes) are a good starting point. Decreasing the interval + both decreases the probability of the problem and the write + performance of the guest. Setting the value unnecessarily low + will cost performance without providing any benefits. An + interval of 1 will cause a flush for each write operation and + should solve the problem in any case, but has a severe write + performance penalty. + </para> + + <para> + Providing a value of <literal>0</literal> for + <literal>[<replaceable>b</replaceable>]</literal> is treated as + an infinite flush interval, effectively disabling this + workaround. Removing the extra data key by specifying no value + for <literal>[<replaceable>b</replaceable>]</literal> has the + same effect. + </para> + + </sect2> + + <sect2 id="ts_ide-sata-flush"> + + <title>Responding to Guest IDE/SATA Flush Requests</title> + + <para> + If desired, the virtual disk images can be flushed when the + guest issues the IDE FLUSH CACHE command. Normally these + requests are ignored for improved performance. The parameters + below are only accepted for disk drives. They must not be set + for DVD drives. + </para> + + <para> + To enable flushing for IDE disks, issue the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/Devices/piix3ide/0/LUN#[<replaceable>x</replaceable>]/Config/IgnoreFlush" 0</screen> + + <para> + <literal>[<replaceable>x</replaceable>]</literal> specifies the + disk. Enter <literal>0</literal> for device 0 on the primary + channel, <literal>1</literal> for device 1 on the primary + channel, <literal>2</literal> for device 0 on the secondary + channel, or <literal>3</literal> for device 1 on the secondary + channel. + </para> + + <para> + To enable flushing for SATA disks, issue the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/IgnoreFlush" 0</screen> + + <para> + The value [x] that selects the disk can be a value between 0 and + 29. + </para> + + <para> + Note that this does not affect the flushes performed according + to the configuration described in + <xref linkend="ts_config-periodic-flush"/>. Restoring the + default of ignoring flush commands is possible by setting the + value to 1 or by removing the key. + </para> + + </sect2> + + <sect2 id="ts_host-freq-boost"> + + <title>Performance Variation with Frequency Boosting</title> + + <para> + Many multicore processors support some form of frequency + boosting, which means that if only one core is utilized, it can + run possibly 50% faster or even more than the rated CPU + frequency. This causes measured performance to vary somewhat as + a function of the momentary overall system load. The exact + behavior depends strongly on the specific processor model. + </para> + + <para> + As a consequence, benchmarking on systems which utilize + frequency boosting may produce unstable and non-repeatable + results. This is especially true if benchmark runs are short, of + the order of seconds. To obtain stable results, benchmarks must + be run over longer periods of time and with a constant system + load apart from the VM being tested. + </para> + + </sect2> + + <sect2 id="ts_host-freq-scaling"> + + <title>Frequency Scaling Effect on CPU Usage</title> + + <para> + On some hardware platforms and operating systems, CPU frequency + scaling may cause CPU usage reporting to be highly misleading. + This happens in situations when the host CPU load is significant + but not heavy, such as between 15% to 30% of the maximum. + </para> + + <para> + Most operating systems determine CPU usage in terms of time + spent, measuring for example how many nanoseconds the systems or + a process was active within one second. However, in order to + save energy, systems can significantly scale down CPU speed when + the system is not fully loaded. When the CPU is running at for + example one half of its maximum speed, the same number of + instructions will take roughly twice as long to execute compared + to running at full speed. + </para> + + <para> + Depending on the specific hardware and host OS, this effect can + very significantly skew the CPU usage reported by the OS. The + reported CPU usage can be several times higher than what it + would have been had the CPU been running at full speed. The + effect can be observed both on the host OS and in a guest OS. + </para> + + </sect2> + + <sect2 id="ts_win-cpu-usage-rept"> + + <title>Inaccurate Windows CPU Usage Reporting</title> + + <para> + CPU usage reporting tools which come with Windows, such as Task + Manager or Resource Monitor, do not take the time spent + processing hardware interrupts into account. If the interrupt + load is heavy, with thousands of interrupts per second, CPU + usage may be significantly underreported. + </para> + + <para> + This problem affects Windows as both host and guest OS. + Sysinternals tools, such as Process Explorer, do not suffer from + this problem. + </para> + + </sect2> + + <sect2 id="ts_host-powermgmt"> + + <title>Poor Performance Caused by Host Power Management</title> + + <para> + On some hardware platforms and operating systems, virtualization + performance is negatively affected by host CPU power management. + The symptoms may be choppy audio in the guest or erratic guest + clock behavior. + </para> + + <para> + Some of the problems may be caused by firmware and/or host + operating system bugs. Therefore, updating the firmware and + applying operating systems fixes is recommended. + </para> + + <para> + For optimal virtualization performance, the C1E power state + support in the system's BIOS should be disabled, if such a + setting is available. Not all systems support the C1E power + state. On Intel systems, the <literal>Intel C State</literal> + setting should be disabled. Disabling other power management + settings may also improve performance. However, a balance + between performance and power consumption must always be + considered. + </para> + + </sect2> + + <sect2 id="ts_gui-2d-grayed-out"> + + <title>GUI: 2D Video Acceleration Option is Grayed Out</title> + + <para> + To use 2D Video Acceleration within &product-name;, your host's + video card should support certain OpenGL extensions. On startup, + &product-name; checks for those extensions, and, if the test + fails, this option is silently grayed out. + </para> + + <para> + To find out why it has failed, you can manually execute the + following command: + </para> + +<screen>$ VBoxTestOGL --log "log_file_name" --test 2D</screen> + + <para> + It will list the required OpenGL extensions one by one and will + show you which one failed the test. This usually means that you + are running an outdated or misconfigured OpenGL driver on your + host. It can also mean that your video chip is lacking required + functionality. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_win-guests"> + + <title>Windows Guests</title> + + <sect2 id="ts_win7-guest-usb3-support"> + + <title>No USB 3.0 Support in Windows 7 Guests</title> + + <para> + If a Windows 7 or Windows Server 2008 R2 guest is configured for + USB 3.0 (xHCI) support, the guest OS will not have any USB + support at all. This happens because Windows 7 predates USB 3.0 + and therefore does not ship with any xHCI drivers. Microsoft + also does not offer any vendor-provided xHCI drivers through + Windows Update. + </para> + + <para> + To solve this problem, it is necessary to download and install + the Intel xHCI driver in the guest. Intel offers the driver as + the USB 3.0 eXtensible Host Controller (xHCI) driver for Intel 7 + Series/C216 chipsets. + </para> + + <para> + Note that the driver only supports Windows 7 and Windows Server + 2008 R2. The driver package includes support for both 32-bit and + 64-bit OS variants. + </para> + + </sect2> + + <sect2 id="ts_win-guest-bluescreen"> + + <title>Windows Bluescreens After Changing VM Configuration</title> + + <para> + Changing certain virtual machine settings can cause Windows + guests to fail during start up with a bluescreen. This may + happen if you change VM settings after installing Windows, or if + you copy a disk image with an already installed Windows to a + newly created VM which has settings that differ from the + original machine. + </para> + + <para> + This applies in particular to the following settings: + </para> + + <itemizedlist> + + <listitem> + <para> + The ACPI and I/O APIC settings should never be changed after + installing Windows. Depending on the presence of these + hardware features, the Windows installation program chooses + special kernel and device driver versions and will fail to + startup should these hardware features be removed. Enabling + them for a Windows VM which was installed without them does + not cause any harm. However, Windows will not use these + features in this case. + </para> + </listitem> + + <listitem> + <para> + Changing the storage controller hardware will cause bootup + failures as well. This might also apply to you if you copy a + disk image from an older version of &product-name; to a new + virtual machine. The default subtype of IDE controller + hardware used by &product-name; is PIIX4. Make sure that the + storage controller settings are identical. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="ts_win-guest-bluescreen-smp"> + + <title>Windows 0x101 Bluescreens with SMP Enabled (IPI Timeout)</title> + + <para> + If a VM is configured to have more than one processor + (symmetrical multiprocessing, SMP), some configurations of + Windows guests crash with an 0x101 error message, indicating a + timeout for interprocessor interrupts (IPIs). These interrupts + synchronize memory management between processors. + </para> + + <para> + According to Microsoft, this is due to a race condition in + Windows. A hotfix is available from Microsoft. + </para> + + <para> + If this does not help, please reduce the number of virtual + processors to 1. + </para> + + </sect2> + + <sect2 id="ts_win2k-guest-install"> + + <title>Windows 2000 Installation Failures</title> + + <para> + When installing Windows 2000 guests, you might run into one of + the following issues: + </para> + + <itemizedlist> + + <listitem> + <para> + Installation reboots, usually during component registration. + </para> + </listitem> + + <listitem> + <para> + Installation fills the whole hard disk with empty log files. + </para> + </listitem> + + <listitem> + <para> + Installation complains about a failure installing + <filename>msgina.dll</filename>. + </para> + </listitem> + + </itemizedlist> + + <para> + These problems are all caused by a bug in the hard disk driver + of Windows 2000. After issuing a hard disk request, there is a + race condition in the Windows driver code which leads to + corruption if the operation completes too fast. For example, the + hardware interrupt from the IDE controller arrives too soon. + With physical hardware, there is a guaranteed delay in most + systems so the problem is usually hidden there. However, it + should be possible to also reproduce it on physical hardware. In + a virtual environment, it is possible for the operation to be + done immediately, especially on very fast systems with multiple + CPUs, and the interrupt is signaled sooner than on a physical + system. The solution is to introduce an artificial delay before + delivering such interrupts. This delay can be configured for a + VM using the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/Devices/piix3ide/0/Config/IRQDelay" 1</screen> + + <para> + This sets the delay to one millisecond. In case this does not + help, increase it to a value between 1 and 5 milliseconds. + Please note that this slows down disk performance. After + installation, you should be able to remove the key, or set it to + 0. + </para> + + </sect2> + + <sect2 id="ts_win-guest-bluescreen-record-info"> + + <title>How to Record Bluescreen Information from Windows Guests</title> + + <para> + When Windows guests run into a kernel crash, they display a + bluescreen error. Depending on how Windows is configured, the + information will remain on the screen until the machine is + restarted or it will reboot automatically. During installation, + Windows is usually configured to reboot automatically. With + automatic reboots, there is no chance to record the bluescreen + information which might be important for problem determination. + </para> + + <para> + &product-name; provides a method of halting a guest when it + wants to perform a reset. In order to enable this feature, use + the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/PDM/HaltOnReset" 1</screen> + + </sect2> + + <sect2 id="ts_win-vista-guest-networking"> + + <title>No Networking in Windows Vista Guests</title> + + <para> + With Windows Vista, Microsoft dropped support for the AMD PCNet + card that legacy versions of &product-name; used to provide as + the default virtual network card. For Windows Vista guests, + &product-name; now uses an Intel E1000 card by default. + </para> + + <para> + If, for some reason, you still want to use the AMD card, you + need to download the PCNet driver from the AMD website. This + driver is available for 32-bit Windows only. You can transfer it + into the virtual machine using a shared folder. See + <xref linkend="sharedfolders" />. + </para> + + </sect2> + + <sect2 id="ts_win-guest-high-cpu"> + + <title>Windows Guests may Cause a High CPU Load</title> + + <para> + Several background applications of Windows guests, especially + virus scanners, are known to increase the CPU load notably even + if the guest appears to be idle. We recommend to deactivate + virus scanners within virtualized guests if possible. + </para> + + </sect2> + + <sect2 id="ts_win-guest-shared-folders-access-delay"> + + <title>Long Delays When Accessing Shared Folders</title> + + <para> + The performance for accesses to shared folders from a Windows + guest might be decreased due to delays during the resolution of + the &product-name; shared folders name service. To fix these + delays, add the following entries to the file + <filename>\windows\system32\drivers\etc\lmhosts</filename> of + the Windows guest: + </para> + +<screen>255.255.255.255 VBOXSVR #PRE +255.255.255.255 VBOXSRV #PRE</screen> + + <para> + After doing this change, a reboot of the guest is required. + </para> + + </sect2> + + <sect2 id="ts_win98-guest-usb-tablet-coordinates"> + + <title>USB Tablet Coordinates Wrong in Windows 98 Guests</title> + + <para> + If a Windows 98 VM is configured to use the emulated USB tablet + (absolute pointing device), the coordinate translation may be + incorrect and the pointer is restricted to the upper left + quarter of the guest's screen. + </para> + + <para> + The USB HID (Human Interface Device) drivers in Windows 98 are + very old and do not handle tablets in the same way as modern + operating systems do. To work around the problem, use the + following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/USB/HidMouse/0/Config/CoordShift" 0</screen> + + <para> + To restore the default behavior, remove the key or set its value + to 1. + </para> + + </sect2> + + <sect2 id="ts_win-guest-active-dir-domain"> + + <title>Windows Guests are Removed From an Active Directory Domain After + Restoring a Snapshot</title> + + <para> + If a Windows guest is a member of an Active Directory domain and + the snapshot feature of &product-name; is used, it could be + removed from the Active Direcory domain after you restore an + older snapshot. + </para> + + <para> + This is caused by automatic machine password changes performed + by Windows at regular intervals for security purposes. You can + disable this feature as shown in the following article from + Microsoft: + <ulink url="http://support.microsoft.com/kb/154501" />. + </para> + + </sect2> + + <sect2 id="ts_win31-ram-limitations"> + + <title>Windows 3.x Limited to 64 MB RAM</title> + + <para> + Windows 3.x guests are typically limited to 64 MB RAM, even if a + VM is assigned much more memory. While Windows 3.1 is + theoretically capable of using up to 512 MB RAM, it only uses + memory available through the XMS interface. Versions of + HIMEM.SYS, the Microsoft XMS manager, shipped with MS-DOS and + Microsoft Windows 3.x can only use up to 64 MB on standard PCs. + </para> + + <para> + This is a known HIMEM.SYS limitation. Windows 3.1 memory limits + are described in detail in Microsoft Knowledge base article KB + 84388. + </para> + + <para> + It is possible for Windows 3.x guests to utilize more than 64 MB + RAM if a different XMS provider is used. That could be a newer + HIMEM.SYS version, such as that shipped with Windows 98, or a + more capable third-party memory manager, such as QEMM. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_lin-x11-guests"> + + <title>Linux and X11 Guests</title> + + <sect2 id="ts_linux-guest-high-cpu"> + + <title>Linux Guests May Cause a High CPU load</title> + + <para> + Some Linux guests may cause a high CPU load even if the guest + system appears to be idle. This can be caused by a high timer + frequency of the guest kernel. Some Linux distributions, for + example Fedora, ship a Linux kernel configured for a timer + frequency of 1000Hz. We recommend to recompile the guest kernel + and to select a timer frequency of 100Hz. + </para> + + <para> + Linux kernels shipped with Red Hat Enterprise Linux, as well as + kernels of related Linux distributions, such as CentOS and + Oracle Linux, support a kernel parameter + <emphasis>divider=N</emphasis>. Hence, such kernels support a + lower timer frequency without recompilation. We suggest you add + the kernel parameter <emphasis>divider=10</emphasis> to select a + guest kernel timer frequency of 100Hz. + </para> + + </sect2> + + <sect2 id="ts_linux-buggy"> + + <title>Buggy Linux 2.6 Kernel Versions</title> + + <para> + The following bugs in Linux kernels prevent them from executing + correctly in &product-name;, causing VM boot crashes: + </para> + + <itemizedlist> + + <listitem> + <para> + The Linux kernel version 2.6.18, and some 2.6.17 versions, + introduced a race condition that can cause boot crashes in + &product-name;. Please use a kernel version 2.6.19 or later. + </para> + </listitem> + + <listitem> + <para> + With hardware virtualization and the I/O APIC enabled, + kernels before 2.6.24-rc6 may panic on boot with the + following message: + </para> + +<screen>Kernel panic - not syncing: IO-APIC + timer doesn't work! Boot with +apic=debug and send a report. Then try booting with the 'noapic' option</screen> + + <para> + If you see this message, either disable hardware + virtualization or the I/O APIC as described in + <xref linkend="settings-system" />, or upgrade the guest to + a newer kernel. + </para> + + <para> + See + <ulink url="http://www.mail-archive.com/git-commits-head@vger.kernel.org/msg30813.html" /> + for details about the kernel fix. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="ts_linux-guest-x11-services"> + + <title>Shared Clipboard, Auto-Resizing, and Seamless Desktop in X11 Guests</title> + + <para> + Guest desktop services in guests running the X11 window system + such as Oracle Solaris and Linux, are provided by a guest + service called <command>VBoxClient</command>, which runs under + the ID of the user who started the desktop session and is + automatically started using the following command lines when + your X11 user session is started if you are using a common + desktop environment such as Gnome or KDE. + </para> + +<screen>$ VBoxClient --clipboard +$ VBoxClient --display +$ VBoxClient --seamless</screen> + + <para> + If a particular desktop service is not working correctly, it is + worth checking whether the process which should provide it is + running. + </para> + + <para> + The <command>VBoxClient</command> processes create files in the + user's home directory with names of the form + <filename>.vboxclient-*.pid</filename> when they are running in + order to prevent a given service from being started twice. It + can happen due to misconfiguration that these files are created + owned by root and not deleted when the services are stopped, + which will prevent them from being started in future sessions. + If the services cannot be started, you may wish to check whether + these files still exist. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_sol-guests"> + + <title>Oracle Solaris Guests</title> + + <sect2 id="ts_solaris-10-guest-slow-boot-smp"> + + <title>Certain Oracle Solaris 10 Releases May Take a Long Time to Boot with SMP</title> + + <para> + When using more than one CPU, Oracle Solaris 10 10/08, and + Oracle Solaris 10 5/09 may take a long time to boot and may + print warnings on the system console regarding failures to read + from disk. This is a bug in Oracle Solaris 10 which affects + specific physical and virtual configurations. It is caused by + trying to read microcode updates from the boot disk when the + disk interrupt is reassigned to a not yet fully initialized + secondary CPU. Disk reads will time out and fail, triggering + delays of about 45 seconds and warnings. + </para> + + <para> + The recommended solution is upgrading to at least Oracle Solaris + 10 10/09 which includes a fix for this problem. Alternative + solutions include restricting the number of virtual CPUs to one + or possibly using a different storage controller. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_win-hosts"> + + <title>Windows Hosts</title> + + <sect2 id="ts_win-dnd-uipi"> + + <title>Drag'n Drop not Working</title> + + <para> + Microsoft Windows uses technologies like UAC (User Account Control) and + UIPI (User Interface Privilege Isolation) to prevent and/or mitigate + security issues. By default, UAC and UIPI are enabled. + </para> + <para> + When a &product-name; VM process is running with a higher so-called + privilege level than another process that wants to interact with the + VM process via drag'n drop (or system clipboard), Windows prevents this + by default due to security reasons. This results in &product-name; not + being able to receive any Windows messages for drag'n drop. + + To make this work, the &product-name; VM process must be running with + the same (or lower) privilege level as the process its interacting with + using drag'n drop. + + Disabling UAC and/or UIPI is not recommended. + </para> + + </sect2> + + <sect2 id="ts_win-host-com-server"> + + <title>VBoxSVC Out-of-Process COM Server Issues</title> + + <para> + &product-name; makes use of the Microsoft Component Object Model + (COM) for interprocess and intraprocess communication. This + enables &product-name; to share a common configuration among + different virtual machine processes and provide several user + interface options based on a common architecture. All global + status information and configuration is maintained by the + process <filename>VBoxSVC.exe</filename>, which is an + out-of-process COM server. Whenever an &product-name; process is + started, it requests access to the COM server and Windows + automatically starts the process. Note that it should never be + started by the end user. + </para> + + <para> + When the last process disconnects from the COM server, it will + terminate itself after some seconds. The &product-name; + configuration XML files are maintained and owned by the COM + server and the files are locked whenever the server runs. + </para> + + <para> + In some cases, such as when a virtual machine is terminated + unexpectedly, the COM server will not notice that the client is + disconnected and stay active for a longer period of 10 minutes + or so, keeping the configuration files locked. In other rare + cases the COM server might experience an internal error and + subsequently other processes fail to initialize it. In these + situations, it is recommended to use the Windows task manager to + kill the process <filename>VBoxSVC.exe</filename>. + </para> + + </sect2> + + <sect2 id="ts_win-host-cd-dvd-changes"> + + <title>CD and DVD Changes Not Recognized</title> + + <para> + In case you have assigned a physical CD or DVD drive to a guest + and the guest does not notice when the medium changes, make sure + that the Windows media change notification (MCN) feature is not + turned off. This is represented by the following key in the + Windows registry: + </para> + +<screen>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Cdrom\Autorun</screen> + + <para> + Certain applications may disable this key against Microsoft's + advice. If it is set to 0, change it to 1 and reboot your + system. &product-name; relies on Windows notifying it of media + changes. + </para> + + </sect2> + + <sect2 id="ts_win-host-rdp-client"> + + <title>Sluggish Response When Using Microsoft RDP Client</title> + + <para> + If connecting to a Virtual Machine using the Microsoft RDP + client, called a Remote Desktop Connection, there can be large + delays between input such as moving the mouse over a menu and + output. This is because this RDP client collects input for a + certain time before sending it to the RDP server. + </para> + + <para> + The interval can be decreased by setting a Windows registry key + to smaller values than the default of 100. The key does not + exist initially and must be of type DWORD. The unit for its + values is milliseconds. Values around 20 are suitable for + low-bandwidth connections between the RDP client and server. + Values around 4 can be used for a gigabit Ethernet connection. + Generally values below 10 achieve a performance that is very + close to that of the local input devices and screen of the host + on which the Virtual Machine is running. + </para> + + <para> + Depending whether the setting should be changed for an + individual user or for the system, set either of the following. + </para> + +<screen>HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client\Min Send Interval</screen> + +<screen>HKEY_LOCAL_MACHINE\Software\Microsoft\Terminal Server Client\Min Send Interval</screen> + + </sect2> + + <sect2 id="ts_win-host-iscsi"> + + <title>Running an iSCSI Initiator and Target on a Single System</title> + + <para> + Deadlocks can occur on a Windows host when attempting to access + an iSCSI target running in a guest virtual machine with an iSCSI + initiator, such as a Microsoft iSCSI Initiator, that is running + on the host. This is caused by a flaw in the Windows cache + manager component, and causes sluggish host system response for + several minutes, followed by a "Delayed Write Failed" error + message in the system tray or in a separate message window. The + guest is blocked during that period and may show error messages + or become unstable. + </para> + + <para> + Setting the <literal>VBOX_DISABLE_HOST_DISK_CACHE</literal> + environment variable to <literal>1</literal> enables a + workaround for this problem until Microsoft addresses the issue. + For example, open a command prompt window and start + &product-name; like this: + </para> + +<screen>set VBOX_DISABLE_HOST_DISK_CACHE=1 +VirtualBox</screen> + + <para> + While this will decrease guest disk performance, especially + writes, it does not affect the performance of other applications + running on the host. + </para> + + </sect2> + + <sect2 id="ts_win-host-bridged-network-adapters"> + + <title>Bridged Networking Adapters Missing</title> + + <para> + If no bridged adapters show up in the + <emphasis role="bold">Networking</emphasis> section of the VM + settings, this typically means that the bridged networking + driver was not installed properly on your host. This could be + due to the following reasons: + </para> + + <itemizedlist> + + <listitem> + <para> + The maximum allowed filter count was reached on the host. In + this case, the MSI log would mention the + <literal>0x8004a029</literal> error code returned on NetFlt + network component install, as follows: + </para> + +<screen>VBoxNetCfgWinInstallComponent: Install failed, hr (0x8004a029)</screen> + + <para> + You can try to increase the maximum filter count in the + Windows registry using the following key: + </para> + +<screen>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Network\MaxNumFilters</screen> + + <para> + The maximum number allowed is 14. After a reboot, try to + reinstall &product-name;. + </para> + </listitem> + + <listitem> + <para> + The INF cache is corrupt. In this case, the install log at + <filename>%windir%\inf\setupapi.dev.log</filename> would + typically mention the failure to find a suitable driver + package for either the <command>sun_VBoxNetFlt</command> or + <command>sun_VBoxNetFltmp</command> components. The solution + then is to uninstall &product-name;, remove the INF cache + (<filename>%windir%\inf\INFCACHE.1</filename>), reboot and + try to reinstall &product-name;. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="ts_win-host-host-only-network-adapters"> + + <title>Host-Only Networking Adapters Cannot be Created</title> + + <para> + If a host-only adapter cannot be created, either with the + &vbox-mgr; or the <command>VBoxManage</command> command, then + the INF cache is probably corrupt. In this case, the install log + at <filename>%windir%\inf\setupapi.dev.log</filename> would + typically mention the failure to find a suitable driver package + for the <filename>sun_VBoxNetAdp</filename> component. Again, as + with the bridged networking problem described above, the + solution is to uninstall &product-name;, remove the INF cache + (<filename>%windir%\inf\INFCACHE.1</filename>), reboot and try + to reinstall &product-name;. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_lin-hosts"> + + <title>Linux Hosts</title> + + <sect2 id="ts_linux-kernelmodule-fails-to-load"> + + <title>Linux Kernel Module Refuses to Load</title> + + <para> + If the &product-name; kernel module, <command>vboxdrv</command>, + refuses to load you may see an <literal>Error inserting vboxdrv: + Invalid argument</literal> message. As root, check the output of + the <command>dmesg</command> command to find out why the load + failed. Most probably the kernel disagrees with the version of + <command>gcc</command> used to compile the module. Make sure + that you use the same compiler that was used to build the + kernel. + </para> + + </sect2> + + <sect2 id="ts_linux-host-cd-dvd-not-found"> + + <title>Linux Host CD/DVD or Floppy Disk Drive Not Found</title> + + <para> + If you have configured a virtual machine to use the host's CD or + DVD drive or floppy disk drive, but this does not appear to + work, make sure that the current user has permission to access + the corresponding Linux device file. For example, for a CD or + DVD drive this may be <filename>/dev/hdc</filename>, + <filename>/dev/scd0</filename>, <filename>/dev/cdrom</filename> + or similar. On most distributions, the user must be added to a + corresponding group, usually called <command>cdrom</command> or + <command>cdrw</command> or <command>floppy</command>. + </para> + + <para> + On supported Linux distributions, &product-name; uses + <command>udev</command> to locate hardware such as CD/DVD drives + and floppy disk drives. + </para> + + </sect2> + + <sect2 id="ts_linux-host-ide-messages"> + + <title>Strange Guest IDE Error Messages When Writing to CD or DVD</title> + + <para> + If the experimental CD or DVD writer support is enabled with an + incorrect host or guest configuration, it is possible that any + attempt to access the CD or DVD writer fails and simply results + in guest kernel error messages for Linux guests or application + error messages for Windows guests. &product-name; performs the + usual consistency checks when a VM is powered up. In particular, + it aborts with an error message if the device for the CD or DVD + writer is not writable by the user starting the VM. But + &product-name; cannot detect all misconfigurations. The + necessary host and guest OS configuration is not specific for + &product-name;, but a few frequent problems are listed here + which occurred in connection with &product-name;. + </para> + + <para> + Special care must be taken to use the correct device. The + configured host CD or DVD device file name, in most cases + <filename>/dev/cdrom</filename>, must point to the device that + allows writing to the CD or DVD unit. For CD or DVD writer units + connected to a SCSI controller or to a IDE controller that + interfaces to the Linux SCSI subsystem, common for some SATA + controllers, this must refer to the SCSI device node, such as + <filename>/dev/scd0</filename>. Even for IDE CD or DVD writer + units this must refer to the appropriate SCSI CD-ROM device + node, such as <filename>/dev/scd0</filename>, if the + <command>ide-scsi</command> kernel module is loaded. This module + is required for CD or DVD writer support with some early 2.6 + kernels. Many Linux distributions load this module whenever a CD + or DVD writer is detected in the system, even if the kernel + would support CD or DVD writers without the module. + &product-name; supports the use of IDE device files, such as + <filename>/dev/hdc</filename>, provided the kernel supports this + and the <command>ide-scsi</command> module is not loaded. + </para> + + <para> + Similar rules, except that within the guest the CD or DVD writer + is always an IDE device, apply to the guest configuration. Since + this setup is very common, it is likely that the default + configuration of the guest works as expected. + </para> + + </sect2> + + <sect2 id="ts_linux-host-vboxsvc"> + + <title>VBoxSVC IPC Issues</title> + + <para> + On Linux, &product-name; makes use of a custom version of + Mozilla XPCOM (cross platform component object model) for + interprocess and intraprocess communication (IPC). The process + <command>VBoxSVC</command> serves as a communication hub between + different &product-name; processes and maintains the global + configuration, such as the XML database. When starting an + &product-name; component, the processes + <command>VBoxSVC</command> and <command>VBoxXPCOMIPCD</command> + are started automatically. They are only accessible from the + user account they are running under. <command>VBoxSVC</command> + owns the &product-name; configuration database which normally + resides in <filename>~/.config/VirtualBox</filename>, or the + appropriate configuration directory for your operating system. + While it is running, the configuration files are locked. + Communication between the various &product-name; components and + <command>VBoxSVC</command> is performed through a local domain + socket residing in + <filename>/tmp/.vbox-<replaceable>username</replaceable>-ipc</filename>. + In case there are communication problems, such as an + &product-name; application cannot communicate with + <command>VBoxSVC</command>, terminate the daemons and remove the + local domain socket directory. + </para> + + </sect2> + + <sect2 id="ts_usb-linux"> + + <title>USB Not Working</title> + + <para> + If USB is not working on your Linux host, make sure that the + current user is a member of the <literal>vboxusers</literal> + group. Please keep in mind that group membership does not take + effect immediately but rather at the next login. If available, + the <command>newgrp</command> command may avoid the need for a + logout and login. + </para> + + </sect2> + + <sect2 id="ts_linux-host-grsec"> + + <title>PAX/grsec Kernels</title> + + <para> + Linux kernels including the grsec patch, see + <ulink url="http://www.grsecurity.net/" />, and derivates have + to disable PAX_MPROTECT for the <command>VBox</command> binaries + to be able to start a VM. The reason is that &product-name; has + to create executable code on anonymous memory. + </para> + + </sect2> + + <sect2 id="ts_linux-host-malloc"> + + <title>Linux Kernel vmalloc Pool Exhausted</title> + + <para> + When running a large number of VMs with a lot of RAM on a Linux + system, say 20 VMs with 1 GB of RAM each, additional VMs might + fail to start with a kernel error saying that the vmalloc pool + is exhausted and should be extended. The error message also + tells you to specify <literal>vmalloc=256MB</literal> in your + kernel parameter list. If adding this parameter to your GRUB or + LILO configuration makes the kernel fail to boot, with an error + message such as <literal>failed to mount the root + partition</literal>, then you have probably run into a memory + conflict of your kernel and initial RAM disk. This can be solved + by adding the following parameter to your GRUB configuration: + </para> + +<screen>uppermem 524288</screen> + + </sect2> + + </sect1> + + <sect1 id="ts_sol-hosts"> + + <title>Oracle Solaris Hosts</title> + + <sect2 id="ts_sol-host-zfs"> + + <title>Cannot Start VM, Not Enough Contiguous Memory</title> + + <para> + The ZFS file system is known to use nearly all available RAM as + cache if the default system settings are not changed. This may + lead to a heavy fragmentation of the host memory preventing + &product-name; VMs from being started. We recommend to limit the + ZFS cache by adding the following line to + <filename>/etc/system</filename>, where + <replaceable>xxxx</replaceable> bytes is the amount of memory + usable for the ZFS cache. + </para> + +<screen>set zfs:zfs_arc_max = xxxx</screen> + + </sect2> + + </sect1> + +</chapter> |