Investigating generic problems with the Linux Guest Additions

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 communication between various services which can run on the guest and matching services on the host, as well as providing a few ad-hoc services itself.
• 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.

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 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.