From f215e02bf85f68d3a6106c2a1f4f7f063f819064 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 11 Apr 2024 10:17:27 +0200 Subject: Adding upstream version 7.0.14-dfsg. Signed-off-by: Daniel Baumann --- doc/manual/en_US/user_Troubleshooting.xml | 1938 +++++++++++++++++++++++++++++ 1 file changed, 1938 insertions(+) create mode 100644 doc/manual/en_US/user_Troubleshooting.xml (limited to 'doc/manual/en_US/user_Troubleshooting.xml') diff --git a/doc/manual/en_US/user_Troubleshooting.xml b/doc/manual/en_US/user_Troubleshooting.xml new file mode 100644 index 00000000..4906fd48 --- /dev/null +++ b/doc/manual/en_US/user_Troubleshooting.xml @@ -0,0 +1,1938 @@ + + + +%all.entities; +]> + + + Troubleshooting + + + 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. + + + + + Procedures and Tools + + + + Categorizing and Isolating Problems + + + 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. + + + + 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: + + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + 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? + + + + + + 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. + + + + + + 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. + + + + + + + + + + Collecting Debugging Information + + + 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. + + + + Every time &product-name; starts up a VM, a so-called + release log file is created, containing + lots of information about the VM configuration and runtime + events. The log file is called VBox.log and + resides in the VM log file folder, which is + $HOME/VirtualBox + VMs/VM-name/Logs by + default. + + + + When starting a VM, the configuration file of the last run will + be renamed to .1, up to + .3. 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. + + + + 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 + Logs in the machine tools menu. + + + + The release log file, VBox.log, 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. + + + + In case of crashes, it is very important to collect + crash dumps. 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: + + + + . + + + + You can also use VBoxManage debugvm to create + a dump of a complete virtual machine. See + . + + + + 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. + + + + &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: + + + + . + + + + The trace files created by &product-name; are in + .pcap format and can be easily analyzed + with Wireshark. + + + + + + + Using the VBoxBugReport Command to Collect Debug Information + Automatically + + + The VBoxBugReport 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. + + + + The following examples show how to use + VBoxBugReport. + + + + By default, the command collects VBoxSVC + process logs, device settings, and global configuration data for + an &product-name; host. + + +$ 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' + + + The results are saved as a compressed tar file archive in the + same directory where the command is run. + + + + To specify a different output file location: + + +$ VBoxBugReport --output ~/debug/bug004.tgz + + + To output all debug information to a single text file, rather + than a tgz file: + + +$ VBoxBugReport --text + + + To collect information for a specific VM, called + Windows_10: + + +$ VBoxBugReport Windows_10 + + + This command collects machine settings, guest properties, and + log files for the specified VM. Global configuration information + for the host is also included. + + + + To collect information for several VMs, called + Windows_7, Windows_8, and + Windows_10: + + +$ VBoxBugReport Windows_7 Windows_8 Windows_10 + + + To collect information for all VMs: + + +$ VBoxBugReport --all + + + To show a full list of the available command options, run + VBoxBugReport --help. + + + + + + + The Built-In VM Debugger + + + &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. + + + + + 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. + + + + + 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: + + + + + + + Using a debugger console window displayed alongside the VM + + + + + + Using the telnet protocol on port 5000 + + + + + + + The debugger can be enabled in the following ways: + + + + + + + Start the VM directly using VirtualBoxVM + --startvm, with an additional + , , or + argument. See the + VirtualBoxVM --help command usage help + for details. + + + + + + Set the VBOX_GUI_DBG_ENABLED or + VBOX_GUI_DBG_AUTO_SHOW environment + variable to true 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. + + + + + + Set the GUI/Dbg/Enabled extra data item + to true before launching the VM. This can + be set globally or on a per VM basis. + + + + + + + A new Debug menu entry is added + to the &product-name; application. This menu enables the user to + open the debugger console. + + + + 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. + + + + The most important command is help. This will + print brief usage help for all debugger commands. The set of + commands supported by the VM debugger changes frequently and the + help command is always up-to-date. + + + + A brief summary of frequently used commands is as follows: + + + + + + + stop: Stops the VM execution and enables + single stepping + + + + + + g: Continue VM execution + + + + + + t: Single step an instruction + + + + + + rg, rh, and + r: Print the guest, hypervisor, and + current registers + + + + + + kg, kh, and + k: Print the guest, hypervisor, and + current call stack + + + + + + da, db, + dw, dd, + dq: Print memory contents as ASCII, + bytes, words, dwords, and qwords + + + + + + u: Unassemble memory + + + + + + dg: Print the guest's GDT + + + + + + di: Print the guest's IDT + + + + + + dl: Print the guest's LDT + + + + + + dt: Print the guest's TSS + + + + + + dp*: Print the guest's page table + structures + + + + + + bp and br: Set a + normal and recompiler breakpoint + + + + + + bl: List breakpoints + + + + + + bc: Clear a breakpoint + + + + + + writecore: Write a VM core file to disk. + See + + + + + + + See the built-in help for other available + commands. + + + + The VM debugger supports symbolic debugging, although symbols + for guest code are often not available. For Oracle Solaris + guests, the detect command automatically + determines the guest OS version and locates kernel symbols in + guest's memory. Symbolic debugging is then available. For Linux + guests, the detect commands also determines + the guest OS version, but there are no symbols in the guest's + memory. Kernel symbols are available in the file + /proc/kallsyms on Linux guests. This file + must be copied to the host, for example using + scp. The loadmap debugger + command can be used to make the symbol information available to + the VM debugger. Note that the kallsyms + 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. + + + + For all guests, a simple way to verify that the correct symbols + are loaded is the k 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. + + + + Another group of debugger commands is the set of + info commands. Running info + help 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 info commands, the + right command to use depends entirely on the problem being + investigated. Some of the info commands are + as follows: + + + + + + + cfgm: Print a branch of the configuration + tree + + + + + + cpuid: Display the guest CPUID leaves + + + + + + ioport: Print registered I/O port ranges + + + + + + mmio: Print registered MMIO ranges + + + + + + mode: Print the current paging mode + + + + + + pit: Print the i8254 PIT state + + + + + + pic: Print the i8259A PIC state + + + + + + ohci, ehci, + xhci: Print a subset of the OHCI, EHCI, + and xHCI USB controller state + + + + + + pcnet0: Print the PCnet state + + + + + + vgatext: Print the contents of the VGA + framebuffer formatted as standard text mode + + + + + + timers: Print all VM timers + + + + + + + The output of the info 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. + + + + + + + VM Core Format + + + &product-name; uses the 64-bit ELF format for its VM core files + created by VBoxManage debugvm, see + . 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: + + + + . + + + + The overall layout of the VM core format is as follows: + + +[ 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 ] + + + 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. + + + + The relevant data structures and definitions can be found in the + &product-name; sources under the following header files: + include/VBox/dbgfcorefmt.h, + include/iprt/x86.h and + src/VBox/Runtime/include/internal/ldrELFCommon.h. + + + + The VM core file can be inspected using + elfdump and GNU readelf or + other similar utilities. + + + + + + + + + General Troubleshooting + + + + Guest Shows IDE/SATA Errors for File-Based Images on Slow Host File + System + + + 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. + + + + 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. + + + + 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. + + + + For IDE disks use the following command: + + +VBoxManage setextradata VM-name +"VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/FlushInterval" [b] + + + For SATA disks use the following command: + + +VBoxManage setextradata VM-name +"VBoxInternal/Devices/ahci/0/LUN#[x]/Config/FlushInterval" [b] + + + [x] specifies the + disk. For IDE, 0 represents device 0 on the + primary channel, 1 represents device 1 on the + primary channel, 2 represents device 0 on the + secondary channel, and 3 represents device 1 + on the secondary channel. For SATA, use values between + 0 and 29. This + configuration option applies to disks only. Do not use this + option for CD or DVD drives. + + + + The unit of the interval + ([b]) 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. + + + + Providing a value of 0 for + [b] is treated as + an infinite flush interval, effectively disabling this + workaround. Removing the extra data key by specifying no value + for [b] has the + same effect. + + + + + + + Responding to Guest IDE/SATA Flush Requests + + + 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. + + + + To enable flushing for IDE disks, issue the following command: + + +$ VBoxManage setextradata VM-name "VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/IgnoreFlush" 0 + + + [x] specifies the + disk. Enter 0 for device 0 on the primary + channel, 1 for device 1 on the primary + channel, 2 for device 0 on the secondary + channel, or 3 for device 1 on the secondary + channel. + + + + To enable flushing for SATA disks, issue the following command: + + +$ VBoxManage setextradata VM-name "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/IgnoreFlush" 0 + + + The value [x] that selects the disk can be a value between 0 and + 29. + + + + Note that this does not affect the flushes performed according + to the configuration described in + . Restoring the + default of ignoring flush commands is possible by setting the + value to 1 or by removing the key. + + + + + + + Performance Variation with Frequency Boosting + + + 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. + + + + 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. + + + + + + + Frequency Scaling Effect on CPU Usage + + + 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. + + + + 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. + + + + 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. + + + + + + + Inaccurate Windows CPU Usage Reporting + + + 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. + + + + This problem affects Windows as both host and guest OS. + Sysinternals tools, such as Process Explorer, do not suffer from + this problem. + + + + + + + Poor Performance Caused by Host Power Management + + + 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. + + + + 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. + + + + 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 Intel C State + 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. + + + + + + + GUI: 2D Video Acceleration Option is Grayed Out + + + 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. + + + + To find out why it has failed, you can manually execute the + following command: + + +$ VBoxTestOGL --log "log_file_name" --test 2D + + + 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. + + + + + + + + + Windows Guests + + + + No USB 3.0 Support in Windows 7 Guests + + + 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. + + + + 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. + + + + 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. + + + + + + + Windows Bluescreens After Changing VM Configuration + + + 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. + + + + This applies in particular to the following settings: + + + + + + + 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. + + + + + + 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. + + + + + + + + + + Windows 0x101 Bluescreens with SMP Enabled (IPI Timeout) + + + 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. + + + + According to Microsoft, this is due to a race condition in + Windows. A hotfix is available from Microsoft. + + + + If this does not help, please reduce the number of virtual + processors to 1. + + + + + + + Windows 2000 Installation Failures + + + When installing Windows 2000 guests, you might run into one of + the following issues: + + + + + + + Installation reboots, usually during component registration. + + + + + + Installation fills the whole hard disk with empty log files. + + + + + + Installation complains about a failure installing + msgina.dll. + + + + + + + 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: + + +$ VBoxManage setextradata VM-name "VBoxInternal/Devices/piix3ide/0/Config/IRQDelay" 1 + + + 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. + + + + + + + How to Record Bluescreen Information from Windows Guests + + + 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. + + + + &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: + + +$ VBoxManage setextradata VM-name "VBoxInternal/PDM/HaltOnReset" 1 + + + + + + No Networking in Windows Vista Guests + + + 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. + + + + 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 + . + + + + + + + Windows Guests may Cause a High CPU Load + + + 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. + + + + + + + Long Delays When Accessing Shared Folders + + + 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 + \windows\system32\drivers\etc\lmhosts of + the Windows guest: + + +255.255.255.255 VBOXSVR #PRE +255.255.255.255 VBOXSRV #PRE + + + After doing this change, a reboot of the guest is required. + + + + + + + USB Tablet Coordinates Wrong in Windows 98 Guests + + + 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. + + + + 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: + + +$ VBoxManage setextradata VM-name "VBoxInternal/USB/HidMouse/0/Config/CoordShift" 0 + + + To restore the default behavior, remove the key or set its value + to 1. + + + + + + + Windows Guests are Removed From an Active Directory Domain After + Restoring a Snapshot + + + 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. + + + + 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: + . + + + + + + + Windows 3.x Limited to 64 MB RAM + + + 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. + + + + This is a known HIMEM.SYS limitation. Windows 3.1 memory limits + are described in detail in Microsoft Knowledge base article KB + 84388. + + + + 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. + + + + + + + + + Linux and X11 Guests + + + + Linux Guests May Cause a High CPU load + + + 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. + + + + 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 + divider=N. Hence, such kernels support a + lower timer frequency without recompilation. We suggest you add + the kernel parameter divider=10 to select a + guest kernel timer frequency of 100Hz. + + + + + + + Buggy Linux 2.6 Kernel Versions + + + The following bugs in Linux kernels prevent them from executing + correctly in &product-name;, causing VM boot crashes: + + + + + + + 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. + + + + + + With hardware virtualization and the I/O APIC enabled, + kernels before 2.6.24-rc6 may panic on boot with the + following message: + + +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 + + + If you see this message, either disable hardware + virtualization or the I/O APIC as described in + , or upgrade the guest to + a newer kernel. + + + + See + + for details about the kernel fix. + + + + + + + + + + Shared Clipboard, Auto-Resizing, and Seamless Desktop in X11 Guests + + + Guest desktop services in guests running the X11 window system + such as Oracle Solaris and Linux, are provided by a guest + service called VBoxClient, 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. + + +$ VBoxClient --clipboard +$ VBoxClient --display +$ VBoxClient --seamless + + + If a particular desktop service is not working correctly, it is + worth checking whether the process which should provide it is + running. + + + + The VBoxClient processes create files in the + user's home directory with names of the form + .vboxclient-*.pid 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. + + + + + + + + + Oracle Solaris Guests + + + + Certain Oracle Solaris 10 Releases May Take a Long Time to Boot with SMP + + + 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. + + + + 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. + + + + + + + Older Solaris Releases Do Not Work with E1000 Ethernet + + + Solaris releases before Solaris 10 1/06, including Solaris 9, Solaris + 10 1/05 (GA), and Solaris 10 3/05 (HW2), are unable to communicate + through the Intel E1000 card. The Solaris e1000g driver does not enable + PCI bus mastering for the network adapter and is therefore unable to send + and receive data. This problem appears to be specific to the e1000g + driver and does not reflect general Solaris driver behavior. + + + + The AMD PCnet emulation (using the Solaris pcn driver) can be used + instead of Intel E1000. Solaris 10 1/06 (U1) and later releases do not + have this problem and work with the emulated E1000 ethernet + controller. + + + + + + + + + Windows Hosts + + + + Drag'n Drop not Working + + + 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. + + + 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. + + + + + + + VBoxSVC Out-of-Process COM Server Issues + + + &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 VBoxSVC.exe, 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. + + + + 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. + + + + 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 VBoxSVC.exe. + + + + + + + CD and DVD Changes Not Recognized + + + 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: + + +HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Cdrom\Autorun + + + 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. + + + + + + + Sluggish Response When Using Microsoft RDP Client + + + 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. + + + + 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. + + + + Depending whether the setting should be changed for an + individual user or for the system, set either of the following. + + +HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client\Min Send Interval + +HKEY_LOCAL_MACHINE\Software\Microsoft\Terminal Server Client\Min Send Interval + + + + + + Running an iSCSI Initiator and Target on a Single System + + + 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. + + + + Setting the VBOX_DISABLE_HOST_DISK_CACHE + environment variable to 1 enables a + workaround for this problem until Microsoft addresses the issue. + For example, open a command prompt window and start + &product-name; like this: + + +set VBOX_DISABLE_HOST_DISK_CACHE=1 +VirtualBox + + + While this will decrease guest disk performance, especially + writes, it does not affect the performance of other applications + running on the host. + + + + + + + Bridged Networking Adapters Missing + + + If no bridged adapters show up in the + Networking 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: + + + + + + + The maximum allowed filter count was reached on the host. In + this case, the MSI log would mention the + 0x8004a029 error code returned on NetFlt + network component install, as follows: + + +VBoxNetCfgWinInstallComponent: Install failed, hr (0x8004a029) + + + You can try to increase the maximum filter count in the + Windows registry using the following key: + + +HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Network\MaxNumFilters + + + The maximum number allowed is 14. After a reboot, try to + reinstall &product-name;. + + + + + + The INF cache is corrupt. In this case, the install log at + %windir%\inf\setupapi.dev.log would + typically mention the failure to find a suitable driver + package for either the sun_VBoxNetFlt or + sun_VBoxNetFltmp components. The solution + then is to uninstall &product-name;, remove the INF cache + (%windir%\inf\INFCACHE.1), reboot and + try to reinstall &product-name;. + + + + + + + + + + Host-Only Networking Adapters Cannot be Created + + + If a host-only adapter cannot be created, either with the + &vbox-mgr; or the VBoxManage command, then + the INF cache is probably corrupt. In this case, the install log + at %windir%\inf\setupapi.dev.log would + typically mention the failure to find a suitable driver package + for the sun_VBoxNetAdp component. Again, as + with the bridged networking problem described above, the + solution is to uninstall &product-name;, remove the INF cache + (%windir%\inf\INFCACHE.1), reboot and try + to reinstall &product-name;. + + + + + + + + + Linux Hosts + + + + Linux Kernel Module Refuses to Load + + + If the &product-name; kernel module, vboxdrv, + refuses to load you may see an Error inserting vboxdrv: + Invalid argument message. As root, check the output of + the dmesg command to find out why the load + failed. Most probably the kernel disagrees with the version of + gcc used to compile the module. Make sure + that you use the same compiler that was used to build the + kernel. + + + + + + + Linux Host CD/DVD or Floppy Disk Drive Not Found + + + 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 /dev/hdc, + /dev/scd0, /dev/cdrom + or similar. On most distributions, the user must be added to a + corresponding group, usually called cdrom or + cdrw or floppy. + + + + On supported Linux distributions, &product-name; uses + udev to locate hardware such as CD/DVD drives + and floppy disk drives. + + + + + + + Strange Guest IDE Error Messages When Writing to CD or DVD + + + 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;. + + + + Special care must be taken to use the correct device. The + configured host CD or DVD device file name, in most cases + /dev/cdrom, 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 + /dev/scd0. Even for IDE CD or DVD writer + units this must refer to the appropriate SCSI CD-ROM device + node, such as /dev/scd0, if the + ide-scsi 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 + /dev/hdc, provided the kernel supports this + and the ide-scsi module is not loaded. + + + + 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. + + + + + + + VBoxSVC IPC Issues + + + 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 + VBoxSVC 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 + VBoxSVC and VBoxXPCOMIPCD + are started automatically. They are only accessible from the + user account they are running under. VBoxSVC + owns the &product-name; configuration database which normally + resides in ~/.config/VirtualBox, 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 + VBoxSVC is performed through a local domain + socket residing in + /tmp/.vbox-username-ipc. + In case there are communication problems, such as an + &product-name; application cannot communicate with + VBoxSVC, terminate the daemons and remove the + local domain socket directory. + + + + + + + USB Not Working + + + If USB is not working on your Linux host, make sure that the + current user is a member of the vboxusers + group. Please keep in mind that group membership does not take + effect immediately but rather at the next login. If available, + the newgrp command may avoid the need for a + logout and login. + + + + + + + PAX/grsec Kernels + + + Linux kernels including the grsec patch, see + , and derivates have + to disable PAX_MPROTECT for the VBox binaries + to be able to start a VM. The reason is that &product-name; has + to create executable code on anonymous memory. + + + + + + + Linux Kernel vmalloc Pool Exhausted + + + 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 vmalloc=256MB 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 failed to mount the root + partition, 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: + + +uppermem 524288 + + + + + + + + Oracle Solaris Hosts + + + + Cannot Start VM, Not Enough Contiguous Memory + + + 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 + /etc/system, where + xxxx bytes is the amount of memory + usable for the ZFS cache. + + +set zfs:zfs_arc_max = xxxx + + + + + + -- cgit v1.2.3