View source for Understanding and Installing VirtualBox Guest Additions

VirtualBox Guest Additions are a package of programs and drivers which are installed onto guest operating systems running in virtual machines to improve the guest's performance and usability.

In this chapter of [[VirtualBox 2 Essentials]] we will look at the VirtualBox Guest Additions features, installation, platform support and management.

== VirtualBox Guest Additions Features ==

When installed on a guest operating system, VirtualBox Guest Additions provide the following enhancements:

* '''Host/Guest Time Synchronization''' - Ensures that the system times of the guest and host are synchronized at regular intervals thereby preventing the ''virtualization time drift'' often encountered with guest operating systems running in virtual machines. 

* '''Seamless Window Support''' - One of the most compelling features of VirtualBox, seamless windows allow the window of an application running on the desktop of a guest operating system to be placed on the desktop of the host operating system such that it appears to be running directly on the host rather than within a virtual machine.

* '''Shared Folders''' - Provides the ability to make folders/directories on the host file system available to guest operating systems running inside VirtualBox virtual machines. This topic is covered in more detail in the [[VirtualBox Shared Folders]] chapter.

* '''Shared Clipboard''' - Allows the guest and host operating systems to access each others cut and paste clipboards enabling easy transfer of text and objects between the two environments. Control over clipboard access is controlled via the VirtualBox preferences settings, details of which can be found in the [[Configuring the VirtualBox Environment]] chapter.

* '''Automated Windows Logon''' - Guest additions allow Windows login credentials to be stored in a master repository and used to automatically log into one or more Windows guests. 

* '''Mouse Pointer Enhancements''' - Without the guest additions installed, clicking in a virtual machine window captures the mouse focus and locks it into the window until the ''host key'' (the right hand ''Ctrl'' key by default) is pressed. With guest additions installed, it is no longer necessary to click in the virtual machine window to establish focus and press the host key to release focus. Instead, the focus will switch automatically between the guest and host as the pointer travels in and out of the virtual machine window.

* '''Improved Video Support''' - The guest additions provide improved video performance and a greater range of video modes and resolutions. In the case of Linux guests, the additions also cause the desktop environment of the guest to resize and change resolution when the virtual machine window is resized.

== Support Guest Operating Systems ==

The VirtualBox Guest Additions are currently supported on the following guest operating systems:

* Windows Vista

* Windows XP

* Windows Server 2003

* Windows 2000

* Windows NT 4.0

* Fedora Core 4, 5, 6, 7, 8

* Red Hat Enterprise Linux 3, 4, 5

* SUSE Linux 9, 10.1, 10.2, 10.3

* openSUSE 9, 10.1, 10.2, 10.3

* Ubuntu 5.10, 6.06, 7.04, 7.10, 8.04, 8.10

Note that the list of supported guests is constantly evolving such that an operating system not listed above may still be able to run the VirtualBox Guest Additions. As a general rule, it won't do any harm to try the guest additions even if the guest is not listed as being supported.

== The VirtualBox Guest Additions ISO File ==

The VirtualBox Guest Additions are contained in an ISO image file which is installed on the host system along with the rest of the VirtualBox environment. The location of image file, which is named ''VBoxGuestAdditions.iso'', depends on the host operating system type.

* On Windows based hosts, the file is located in ''C\Program Files\Sun\xVM VirtualBox''.

* On Linux hosts the file will, by default, be located in ''/opt/VirtualBox-<version>/additions'' where ''<version>'' represents the installed version of VirtualBox. If an alternate location for VirtualBox was specified during the installation location, then the path will need to be adjusted accordingly.

* On Solaris hosts, assuming the default installation location was selected, the guest additions ISO image will be found in ''/opt/VirtualBox/additions''.

* On Mac OS X hosts, the ISO image file is located in the VirtualBox application bundle. To locate the the file, start the ''Finder'', right click on the VirtualBox icon and select ''Show Package Contents''). 

The ISO image contains executable files intended to autorun when the image is mounted as a virtual CD/DVD device on a virtual machine. The correct executable depends on the guest operating system and virtual machine architecture (i.e 32-bit or 64-bit) as outlined below:

* '''VBoxLinuxAdditions-x86.run''' - A shell script for installing VirtualBox Guest additions on 32-bit Linux guests.

* '''VBoxLinuxAdditions-amd64.run''' - A shell script for installing VirtualBox Guest additions on 64-bit Linux guests.

* '''VBoxWindowsAdditions.exe''' - The main Windows VirtualBox Guest Additions installation executable. When run this program decides whether to install the 32-bit or 64-bit guest additions using one of the following executables.

* '''VBoxWindowsAdditions-x86.exe''' - The 32-bit VirtualBox Guest Additions executable for Windows guest systems. The is executed automatically by the main VBoxWindowsAdditions.exe installed on 32-bit guest.

* '''VBoxWindowsAdditions-amd64.exe''' - The 64-bit VirtualBox Guest Additions executable for Windows guest systems. The is executed automatically by the main VBoxWindowsAdditions.exe installed on 64-bit guests.

Whilst the ISO image file may be manually added to the VirtualBox virtual media library and mounted on a virtual machine as a virtual CD/DVD device, a quicker mechanism is provided via the ''Devices...'' menu of the virtual machine window.

== Installing VirtualBox Guest Additions on Windows ==

As previously discussed, the VirtualBox Guest Additions reside in an ISO image file which is bundled with the VirtalBox software. This image file must be mounted as a virtual CD-ROM on the virtual machine on which the additions are to be installed. VirtualBox provides a shortcut to performing this task in form of the ''Devices->Install Guest Additions....'' menu option. When selected, this option mounts the ''VBoxGuestAdditions.iso'' as a virtual CD-ROM and, assuming that AutoPlay is enabled on the guest Windows operating system, the VirtualBox Guest Additions installer will automatically start. If AutoPlay is not enabled, navigate to the CD-ROM using Windows Explorer and double click on ''VBoxWindowsAdditions.exe'' to initiate the installation process. Once invoked, the ''Sun xVM VirtualBox Guest Additions Setup Welcome'' screen will appear. Click ''Next >'' to proceed to the license scree, review the license and click ''I Agree'' to display the installation screen as illustrated below:


[[Image:virtualbox_guest_additions_install.jpg|Installing VirtualBox Guest Additions on a Windows guest]]


Either accept the default installation folder or browse to the desired location before clicking the ''Install'' button to initiate the installation process. The progress of the installation is communicate via a progress bar and a scrolling report of tasks as they are performed:


[[Image:virtualbox_guest_additions_installation_progress.jpg|The progress of a VirtualBox Guest Additions windows installation]]


Once the installation is complete,  the guest operating system must be rebooted for the guest additions to take effect. The reboot may be initiated from the Setup screen, or performed manually at a later, more convenient time.

== Manually Extracting the VirtualBox Windows Drivers ==

The VirtualBox Guest Additions installer automatically extracts and installs the VirtualBox device drivers. In some situations, it is possible that just the drivers, and none of the other guest addition features may be required. In this situation, perform the following steps to extract the device drivers:

1. Mount the VirtualBox Guest Additions CD-ROM following steps outlined previously

2. Open a command prompt window and change directory to the location of the guest additions virtual CD-ROM

3. Execute one of the following commands depending on the guest operating system architecture:

::* VBoxWindowsAdditions-x86.exe /extract /D=C:\VBoxDrivers

::* VBoxWindowsAdditions-amd64.exe /extract /D=C:\VBoxDrivers

Note that the above commands extract the driver files into C:\VBoxDrivers\x86 and C:\VBoxDrivers\amd64 respectively. Alternate locations may be specified by modifying the ''/D='' directive accordingly.

== Installing VirtualBox Guest Addition on Linux ==

The VirtualBox Guest Additions for Linux guests require that the packages necessary to facilitate the building of Kernel modules be installed prior to installing the guest additions. This include the GNU C Compiler and kernel development sources. These are typically installed by default on Ubuntu distributions. On Red Hat, CentOS and Fedora systems however, this can be achieved by executing the following command as super user:

<pre>
su
yum install gcc kernel-devel
</pre>

It is also recommended that the Dynamic Kernel Module Support (DKMS) be installed on guest operating systems where it is supported. This can be achieved on Fedora as follows:

<pre>
yum install dkms
</pre>

and on Ubuntu by running the following command:

<pre>
sudo apt-get install dkms
</pre>
 
As with installation on Windows guests, the VirtualBox Guest Additions CD-ROM may be mounted by selecting the ''Devices->Install Guest Additions....'' menu option from the virtual machine window toolbar. The majority of modern Linux desktop environments will provide the option to automatically run the installer contained on the CD-ROM:


[[Image:virtualbox_guest_additions_linux_autorun.jpg|Auto running The VirtualBox Guest Additions Linux Installer]]


Alternatively, the installation script for the appropriate guest virtual machine architecture may be run manually by changing directory to the CD-ROM mount point and executing one of the following commands, either as super user or prefixing the command with the ''sudo'':

* For 32-bit Linux guests

<pre>
sh VBoxLinuxAdditions-x86.run
</pre>

* For 64-bit Linux guests

<pre>
sh VBoxLinuxAdditions-amd64.run
</pre>


After the installation is complete, the system will need to be rebooted before the guest additions will become operational.

== Selected Installation of Linux Guest Additions ==

The default behavior of the Linux VirtualBox guest additions is to install all the components. Select components may be installed by running the installation script (either VBoxLinuxAdditions-amd64.run or sh VBoxLinuxAdditions-x86.run) with one or more of a number of command line options, for example:

sh VBoxLinuxAdditions-x86.run ''<option>''

where ''<options>'' represents one or more of the following:

* '''all''' - Installs all guest addition components (the default)

* '''x11''' - Install the guest drivers for for the X11 windowing system

* '''kernel-module''' - Installs the kernel module core components

* '''vfs-module''' - Installs the components to facilitate shared folders

* '''timesync''' - Installs the component responsible for synchronizing host and guest system times.

* '''Control''' - Installs the ''VBoxControl'' commandline management tool.

* '''help''' - Displays summary information of the above and other command line options.

== Recompiling the Linux Guest Addition Kernel Modules ==

To rebuild the VirtualBox Guest Additions Linux kernel modules, mount the guest additions CD-ROM ISO image if it is not already mounted, change directory to the mount point and run one of the following commands:

* For 32-bit Linux guests:

<pre>
sh VBoxLinuxAdditions-x86.run setup
</pre>

* For 64-bit Linux guests:

<pre>
sh VBoxLinuxAdditions-amd64.run setup
</pre>

== Updating the Linux VirtualBox Guest Additions ==

The VirtualBox Guest Additions installed on a guest operating system may be updated by mounting the latest VBoxGuestAdditions.iso image file and repeating the above installation process.

== Installing Solaris Guest Additions ==

The VirtualBox Guest Additions may be installed on a Solaris guest by mounting the ISO image as outlined previously, changing directory to the mount point and running the following command as super user:

<pre>
pkgadd -d ./VBoxSolarisAdditions.pkg
</pre>

When prompted for the package to install, enter ''1''.

To subsequently remove the guest additions from a Solaris host, run the following command as super user:

<pre>
pkgrm SUNWvboxguest
</pre>

To update guest additions on a Solaris guest, remove the current installation using the above command and then repeat the installation process using the latest ISO image file.