Investigating generic problems with the Linux Guest Additions

Feedback about this page and suggestions for improvements welcome on the vbox-dev mailing list!

Guest drivers

Overview

The core part, so to speak, of the Linux Guest Additions are the guest kernel drivers. When there are problems with the Guest Additions, the first thing to check is whether the drivers are correctly installed. There are three different drivers:

• The main driver, vboxguest, provides a generic communication channel ("HGCM", host-guest communication mechanism) between various services which can run on the guest (e.g. shared folders, shared clipboard, drag and drop) and matching services on the host, as well as providing a few ad-hoc services itself. It also includes an input driver which lets the host and the guest share a pointer. This works by pretending that the guest system has a touch screen which is "touched" in the right location whenever the host pointer moves over the guest window.
• The shared folder driver vboxsf provides shared folder functionality to the guest. It communicates with the host shared folder service through the vboxguest driver.
• The vboxvideo graphics driver drives the guest video hardware emulation. It does not depend on other drivers, programs the emulated hardware directly and is not expected to be running on systems with X.Org servers older than and including 1.16, as they are not compatible with it and use special drivers, or on systems with Linux kernels older than version 3.11.

The Guest Additions are notably not involved in keyboard input, USB and networking. All of these use normal Linux drivers in the guest kernel which drive the emulated guest hardware.

Some distributions actually come with Guest Additions installed, though generally not the most recent version. The VirtualBox team can usually not give much help with pre-installed Guest Additions (though the distribution should be able to), so our instructions for installation below include steps to remove distribution Guest Additions when these are known.

Driver installation

The kernel drivers are installed on the guest in source code form - readable text which is the ingredients of computer software. They are automatically transformed into usable software ("built") after installation, as every Linux kernel needs slightly different drivers. When the kernel is upgraded this needs to be done again as the old drivers will not match the new kernel. When possible (when we can detect the upgrade in time) this is done automatically when the new kernel is installed. If not, it will be attempted when the new kernel is first used, but in that case not all services may start correctly the first time. (Note to self: could the services just wait a bit and try again later if the kernel driver is not there when they start?) If this fails too, the user will have to find out why and trigger the build manually.

Before installing the Guest Additions, many Linux guest systems need the right software to be installed to build the drivers. Most Ubuntu systems have that software installed automatically. Here are some commands to do it on other systems. They should be run as root or using sudo, and you should restart the guest after they have finished. If you are using any guest other than a standard version of the following list then you will have to understand and solve this yourself. (Technical note: VirtualBox does not use dkms, but installing it also installs the software needed to build the drivers.)

• Debian, Ubuntu, Mint and similar: "apt-get update", "apt-get upgrade", "apt-get install dkms"
• Fedora, Redhat and similar: "yum update", "yum install gcc make perl kernel-devel" (replace "kernel-devel" appropriately if you installed a different kernel; replace "yum" with "dnf" for Fedora 22 and later)
• SUSE and OpenSUSE: "zypper refresh", "zypper update", "zypper install gcc make kernel-devel", "zypper remove virtualbox*" (replace "kernel-devel" appropriately if you installed a different kernel)
• Mageia, Rosa, OpenMandriva: "urpmi.update -a", "urpmi --auto-select", "urpmi dkms"

Basic checks

These checks assume that you have installed the Guest Additions on your guest, and that the installation was successful as far as you can tell.

• To check which version of the Guest Additions are installed, execute modinfo vboxguest. The user-space tools (VBoxClient, VBoxService, VBoxControl) all have --version options to check that those versions match, though at this time (5.1 series) VBoxService only answers if the drivers are loaded.
• To check whether the drivers are basically working on a given Linux guest at a given time, execute lsmod | grep vbox in a command terminal on the guest system. This will list the drivers which are working, but does not rule out more subtle problems in the drivers.
• If the drivers are not basically working, try to start them with the command /sbin/rcvboxadd start run as root or using sudo. This may provide information about why they are not working.
• The most likely reason for them not to work is that they could not be built. Try installing the build tools as described above (or investigate what is different with your particular guest) and run /sbin/rcvboxadd setup as root or using sudo
• Take a look at all log files starting with vbox or VBox in /var/log on the guest system.