Guest Additions are available for virtual machines running Windows, Linux, Solaris or OS/2. The following sections describe the specifics of each variant in detail.
The VirtualBox Windows Guest Additions are designed to be installed in a virtual machine running a Windows operating system. The following versions of Windows guests are supported:
Microsoft Windows NT 4.0 (any service pack)
Microsoft Windows 2000 (any service pack)
Microsoft Windows XP (any service pack)
Microsoft Windows Server 2003 (any service pack)
Microsoft Windows Server 2008
Microsoft Windows Vista (all editions)
Microsoft Windows 7 (all editions)
Microsoft Windows 8 (all editions)
Microsoft Windows Server 2012
In the "Devices" menu in the virtual machine's menu bar, VirtualBox has a handy menu item named "Insert Guest Additions CD image", which mounts the Guest Additions ISO file inside your virtual machine. A Windows guest should then automatically start the Guest Additions installer, which installs the Guest Additions into your Windows guest. Other guest operating systems (or if automatic start of software on CD is disabled) need manual start of the installer.
For the basic Direct3D acceleration to work in a Windows Guest, you have to install the Guest Additions in "Safe Mode". This does not apply to the experimental WDDM Direct3D video driver available for Vista and Windows 7 guests, see Chapter 14, Known limitations for details.[19]
If you prefer to mount the additions manually, you can perform the following steps:
Start the virtual machine in which you have installed Windows.
Select "Mount CD/DVD-ROM" from the "Devices" menu in the virtual machine's menu bar and then "CD/DVD-ROM image". This brings up the Virtual Media Manager described in Section 5.3, “The Virtual Media Manager”.
In the Virtual Media Manager, press the "Add" button and
browse your host file system for the
VBoxGuestAdditions.iso
file:
On a Windows host, you can find this file in the
VirtualBox installation directory (usually under
C:\Program
files\Oracle\VirtualBox
).
On Mac OS X hosts, you can find this file in the
application bundle of VirtualBox. (Right click on the
VirtualBox icon in Finder and choose Show Package
Contents. There it is located in the
Contents/MacOS
folder.)
On a Linux host, you can find this file in the
additions
folder under
where you installed VirtualBox (normally
/opt/VirtualBox/
).
On Solaris hosts, you can find this file in the
additions
folder under
where you installed VirtualBox (normally
/opt/VirtualBox
).
Back in the Virtual Media Manager, select that ISO file and press the "Select" button. This will mount the ISO file and present it to your Windows guest as a CD-ROM.
Unless you have the Autostart feature disabled in your Windows
guest, Windows will now autostart the VirtualBox Guest Additions
installation program from the Additions ISO. If the Autostart feature
has been turned off, choose
VBoxWindowsAdditions.exe
from the
CD/DVD drive inside the guest to start the installer.
The installer will add several device drivers to the Windows driver database and then invoke the hardware detection wizard.
Depending on your configuration, it might display warnings that the drivers are not digitally signed. You must confirm these in order to continue the installation and properly install the Additions.
After installation, reboot your guest operating system to activate the Additions.
Windows Guest Additions can be updated by running the installation program again, as previously described. This will then replace the previous Additions drivers with updated versions.
Alternatively, you may also open the Windows Device Manager and select "Update driver..." for two devices:
the VirtualBox Graphics Adapter and
the VirtualBox System Device.
For each, choose to provide your own driver and use "Have Disk" to point the wizard to the CD-ROM drive with the Guest Additions.
As a prerequiste for performing an unattended installation of the VirtualBox Guest Additions on a Windows guest, there need to be Oracle CA (Certificate Authority) certificates installed in order to prevent user intervention popus which will undermine a silent installation.
Since VirtualBox 4.2 installing those CA certificates on a Windows
guest can be done in an automated fashion using the
VBoxCertUtil.exe
utility found on the Guest
Additions installation CD in the cert
folder:
Log in as Administrator on the guest.
Mount the VirtualBox Guest Additions .ISO.
Open a command line window on the guest and change to
the cert
folder on the VirtualBox
Guest Additions CD.
Do
VBoxCertUtil add-trusted-publisher oracle-vbox.cer --root oracle-vbox.cer
This will install the certificates to the certificate store. When installing the same certificate more than once, an appropriate error will be displayed.
Prior to VirtualBox 4.2 the Oracle CA certificates need to be imported in more manual style
using the certutil.exe
utility, which is shipped since Windows
Vista. For Windows versions before Vista you need to download and install certutil.exe
manually. Since the certificates are not accompanied on the VirtualBox Guest Additions CD-ROM
prior to 4.2, these need to get extracted from a signed VirtualBox executable first.
In the following example the needed certificates will be extracted from the VirtualBox Windows Guest Additions installer on the CD-ROM:
In the Windows Explorer, right click on VBoxWindowsAdditions-<Architecture>.exe, click on "Properties"
Go to tab "Digital Signatures", choose "Oracle Corporation" and click on "Details"
In tab "General" click on "View Certificate"
In tab "Certification Path" select "VeriSign Class 3 Public Primary CA"
Click on "View Certificate"
In tab "Details" click on "Copy to File ..."
In the upcoming wizard choose "DER encoded binary X.509 (.CER)" and save the certificate file to a local path, finish the wizard
Close certificate dialog for "Verisign Class 3 Code Signing 2010 CA"
In the Windows Explorer, right click on VBoxWindowsAdditions-<Architecture>.exe, click on "Properties"
Go to tab "Digital Signatures", choose "Oracle Corporation" and click on "Details"
In tab "General" click on "View Certificate"
In tab "Details" click on "Copy to File ..."
In the upcoming wizard choose "DER encoded binary X.509 (.CER)" and save the certificate file to a local path, finish the wizard
Close certificate dialog for "Oracle Corporation"
After exporting the two certificates above they can be imported into the
certificate store using the certutil.exe
utility:
certutil -addstore -f Root "<Path to exported
certificate file>"
In order to allow for completely unattended guest installations, you can specify a command line parameter to the install launcher:
VBoxWindowsAdditions.exe /S
This automatically installs the right files and drivers for the corresponding platform (32- or 64-bit).
By default on an unattended installation on a Windows 7 or 8
guest, there will be the XPDM graphics driver installed. This graphics
driver does not support Windows Aero / Direct3D on the guest - instead the
experimental WDDM graphics driver needs to be installed. To select this
driver by default, add the command line parameter
/with_wddm
when invoking the Windows
Guest Additions installer.
For Windows Aero to run correctly on a guest, the guest's VRAM size needs to be configured to at least 128 MB.
For more options regarding unattended guest installations, consult the command line help by using the command:
VBoxWindowsAdditions.exe /?
If you would like to install the files and drivers manually, you can extract the files from the Windows Guest Additions setup by typing:
VBoxWindowsAdditions.exe /extract
To explicitly extract the Windows Guest Additions for another
platform than the current running one (e.g. 64-bit files on a 32-bit
system), you have to execute the appropriate platform installer
(VBoxWindowsAdditions-x86.exe
or
VBoxWindowsAdditions-amd64.exe
) with
the /extract
parameter.
Like the Windows Guest Additions, the VirtualBox Guest Additions for Linux are a set of device drivers and system applications which may be installed in the guest operating system.
The following Linux distributions are officially supported:
Oracle Linux as of version 5 including UEK kernels;
Fedora as of Fedora Core 4;
Redhat Enterprise Linux as of version 3;
SUSE and openSUSE Linux as of version 9;
Ubuntu as of version 5.10.
Many other distributions are known to work with the Guest Additions.
The version of the Linux kernel supplied by default in SUSE and openSUSE 10.2, Ubuntu 6.10 (all versions) and Ubuntu 6.06 (server edition) contains a bug which can cause it to crash during startup when it is run in a virtual machine. The Guest Additions work in those distributions.
Note that some Linux distributions already come with all or part of the VirtualBox Guest Additions. You may choose to keep the distribution's version of the Guest Additions but these are often not up to date and limited in functionality, so we recommend replacing them with the Guest Additions that come with VirtualBox. The VirtualBox Linux Guest Additions installer tries to detect existing installation and replace them but depending on how the distribution integrates the Guest Additions, this may require some manual interaction. It is highly recommended to take a snapshot of the virtual machine before replacing pre-installed Guest Additions.
The VirtualBox Guest Additions for Linux are provided on the same virtual CD-ROM file as the Guest Additions for Windows described above. They also come with an installation program guiding you through the setup process, although, due to the significant differences between Linux distributions, installation may be slightly more complex.
Installation generally involves the following steps:
Before installing the Guest Additions, you will have to prepare your guest system for building external kernel modules. This works similarly as described in Section 2.3.2, “The VirtualBox kernel module”, except that this step must now be performed in your Linux guest instead of on a Linux host system, as described there.
Again, as with Linux hosts, we recommend using DKMS if it is available for the guest system. If it is not installed, use this command for Ubuntu/Debian systems:
sudo apt-get install dkms
or for Fedora systems:
yum install dkms
Be sure to install DKMS before installing the Linux Guest Additions. If DKMS is not available or not installed, the guest kernel modules will need to be recreated manually whenever the guest kernel is updated using the command
/etc/init.d/vboxadd setup
as root.
Insert the
VBoxGuestAdditions.iso
CD file
into your Linux guest's virtual CD-ROM drive, exactly the same way
as described for a Windows guest in Section 4.2.1.1, “Installation”.
Change to the directory where your CD-ROM drive is mounted and execute as root:
sh ./VBoxLinuxAdditions.run
For your convenience, we provide the following step-by-step instructions for freshly installed copies of recent versions of the most popular Linux distributions. After these preparational steps, you can execute the VirtualBox Guest Additions installer as described above.
In order to fully update your guest system, open a terminal and run
apt-get update
as root followed by
apt-get upgrade
Install DKMS using
apt-get install dkms
Reboot your guest system in order to activate the updates and then proceed as described above.
In order to fully update your guest system, open a terminal and run
yum updateas root.
Install DKMS and the GNU C compiler using
yum install dkms
followed by
yum install gcc
Reboot your guest system in order to activate the updates and then proceed as described above.
In order to fully update your guest system, open a terminal and run
zypper updateas root.
Install the make tool and the GNU C compiler using
zypper install make gcc
Reboot your guest system in order to activate the updates.
Find out which kernel you are running using
uname -a
An example would be
2.6.31.12-0.2-default
which
refers to the "default" kernel. Then install the correct
kernel development package. In the above example this would be
zypper install kernel-default-devel
Make sure that your running kernel
(uname -a
) and the kernel
packages you have installed (rpm -qa
kernel\*
) have the exact same version number.
Proceed with the installation as described above.
In order to fully update your guest system, open a terminal and run
zypper updateas root.
Install the GNU C compiler using
zypper install gcc
Reboot your guest system in order to activate the updates.
Find out which kernel you are running using
uname -a
An example would be
2.6.27.19-5.1-default
which
refers to the "default" kernel. Then install the correct
kernel development package. In the above example this would be
zypper install kernel-syms kernel-source
Make sure that your running kernel
(uname -a
) and the kernel
packages you have installed (rpm -qa
kernel\*
) have the exact same version number.
Proceed with the installation as described above.
Mandrake ships with the VirtualBox Guest Additions which will be replaced if you follow these steps.
In order to fully update your guest system, open a terminal and run
urpmi --auto-updateas root.
Reboot your system in order to activate the updates.
Install DKMS using
urpmi dkms
and make
sure to choose the correct kernel-devel package when asked by
the installer (use uname -a
to compare).
For versions prior to 6, add divider=10
to the kernel boot options in
/etc/grub.conf
to reduce the
idle CPU load.
In order to fully update your guest system, open a terminal and run
yum updateas root.
Install the GNU C compiler and the kernel development packages using
yum install gcc
followed by
yum install kernel-devel
For Oracle UEK kernels, use
yum install kernel-uek-devel
to install the UEK kernel headers.
Reboot your guest system in order to activate the updates and then proceed as described above.
In case Oracle Linux does not find the required packages, you either have to install them from a different source (e.g. DVD) or use Oracle's public Yum server located at http://public-yum.oracle.com.
In order to fully update your guest system, open a terminal and run
apt-get update
as root followed by
apt-get upgrade
Install the make tool and the GNU C compiler using
apt-get install make gcc
Reboot your guest system in order to activate the updates.
Determine the exact version of your kernel using
uname -a
and install the
correct version of the linux-headers package, e.g. using
apt-get install linux-headers-2.6.26-2-686
In Linux and Solaris guests, VirtualBox graphics and mouse integration goes through the X Window System. VirtualBox can use the X.Org variant of the system (or XFree86 version 4.3 which is identical to the first X.Org release). During the installation process, the X.Org display server will be set up to use the graphics and mouse drivers which come with the Guest Additions.
After installing the Guest Additions into a fresh installation of
a supported Linux distribution or Solaris system (many unsupported
systems will work correctly too), the guest's graphics
mode will change to fit the size of the VirtualBox window
on the host when it is resized. You can also ask the guest system to
switch to a particular resolution by sending a "video mode hint" using
the VBoxManage
tool.
Multiple guest monitors are supported in guests using the X.Org server version 1.3 (which is part of release 7.3 of the X Window System version 11) or a later version. The layout of the guest screens can be adjusted as needed using the tools which come with the guest operating system.
If you want to understand more about the details of how the X.Org drivers are set up (in particular if you wish to use them in a setting which our installer doesn't handle correctly), you should read Section 9.4.2, “Guest graphics and mouse driver setup in depth”.
The Guest Additions can simply be updated by going through the installation procedure again with an updated CD-ROM image. This will replace the drivers with updated versions. You should reboot after updating the Guest Additions.
If you have a version of the Guest Additions installed on your virtual machine and wish to remove it without installing new ones, you can do so by inserting the Guest Additions CD image into the virtual CD-ROM drive as described above and running the installer for the current Guest Additions with the "uninstall" parameter from the path that the CD image is mounted on in the guest:
sh ./VBoxLinuxAdditions.run uninstall
While this will normally work without issues, you may need to do some manual cleanup of the guest (particularly of the XFree86Config or xorg.conf file) in some cases, particularly if the Additions version installed or the guest operating system were very old, or if you made your own changes to the Guest Additions setup after you installed them.
Starting with version 3.1.0, you can uninstall the Additions by invoking
/opt/VBoxGuestAdditions-4.3.26_OSE/uninstall.sh
Please
replace
/opt/VBoxGuestAdditions-4.3.26_OSE
with the correct Guest Additions installation directory.
Like the Windows Guest Additions, the VirtualBox Guest Additions for Solaris take the form of a set of device drivers and system applications which may be installed in the guest operating system.
The following Solaris distributions are officially supported:
Solaris 11 including Solaris 11 Express;
Solaris 10 (u5 and higher);
Other distributions may work if they are based on comparable software releases.
The VirtualBox Guest Additions for Solaris are provided on the same ISO CD-ROM as the Additions for Windows and Linux described above. They also come with an installation program guiding you through the setup process.
Installation involves the following steps:
Mount the
VBoxGuestAdditions.iso
file as
your Solaris guest's virtual CD-ROM drive, exactly the same way as
described for a Windows guest in Section 4.2.1.1, “Installation”.
If in case the CD-ROM drive on the guest doesn't get mounted (observed on some versions of Solaris 10), execute as root:
svcadm restart volfs
Change to the directory where your CD-ROM drive is mounted and execute as root:
pkgadd -G -d ./VBoxSolarisAdditions.pkg
Choose "1" and confirm installation of the Guest Additions package. After the installation is complete, re-login to X server on your guest to activate the X11 Guest Additions.
The Solaris Guest Additions can be safely removed by removing the package from the guest. Open a root terminal session and execute:
pkgrm SUNWvboxguest
VirtualBox also ships with a set of drivers that improve running OS/2 in a virtual machine. Due to restrictions of OS/2 itself, this variant of the Guest Additions has a limited feature set; see Chapter 14, Known limitations for details.
The OS/2 Guest Additions are provided on the same ISO CD-ROM as
those for the other platforms. As a result, mount the ISO in OS/2 as
described previously. The OS/2 Guest Additions are located in the
directory \32bit\OS2
.
As we do not provide an automatic installer at this time, please
refer to the readme.txt
file in that
directory, which describes how to install the OS/2 Guest Additions
manually.