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

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

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