4.2. Installing and Maintaining Guest Additions

Oracle VM VirtualBox

4.2. Installing and Maintaining Guest Additions

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.

4.2.1. Guest Additions for Windows

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 10 RTM build 10240

  • Microsoft Windows Server 2012

4.2.1.1. Installation

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.

Note

For the basic Direct3D acceleration to work in a Windows guest, you have to install the WDDM video driver available for Windows Vista or higher.[18] For Windows 8 and higher only the WDDM Direct3D video driver is available. For basic Direct3D acceleration to work in Windows XP guests, you have to install the Guest Additions in "Safe Mode", see Chapter 14, Known limitations for details.

If you prefer to mount the additions manually, you can perform the following steps:

  1. Start the virtual machine in which you have installed Windows.

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

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

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

4.2.1.2. Updating the Windows Guest 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:

  1. the VirtualBox Graphics Adapter and

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

4.2.1.3. Unattended Installation

As a prerequisite for avoid popups while performing an unattended installation of the VirtualBox Guest Additions, the code signing certificates used to sign the drivers needs to be installed in the right certificates stores in the guest system. Failing to do this will cause a typical windows installation to pop up a dialog asking whether its allowable to install each driver.

Note

On some Windows versions like Windows 2000 and Windows XP the user intervention popups mentioned above always will be displayed, even after importing the Oracle certificates.

Since VirtualBox 4.2 installing those code signing 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.exe add-trusted-publisher vbox*.cer --root 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 code signing 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:

VeriSign Code Signing CA

Open 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"

Oracle Corporation

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

Note

By default on an unattended installation on a Vista or Windows 7 guest, there will be the XPDM graphics driver installed. This graphics driver does not support Windows Aero / Direct3D on the guest – instead the 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 (only required for Vista and Windows 7).

Note

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 /?

4.2.1.4. Manual file extraction

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.

4.2.2. Guest Additions for Linux

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.

4.2.2.1. Installing the Linux 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:

  1. 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 driver modules”, except that this step must now be performed in your Linux guest instead of on a Linux host system, as described there.

    If you suspect that something has gone wrong, check that your guest is set up correctly and try executing the command

    rcvboxadd setup

    as root.

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

  3. Change to the directory where your CD-ROM drive is mounted and execute as root:

    sh ./VBoxLinuxAdditions.run

4.2.2.2. Graphics and mouse integration

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

4.2.2.3. Updating the Linux Guest Additions

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.

4.2.2.4. Uninstalling the Linux 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-5.2.4/uninstall.sh

Please replace /opt/VBoxGuestAdditions-5.2.4 with the correct Guest Additions installation directory.

4.2.3. Guest Additions for Solaris

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.

4.2.3.1. Installing the Solaris Guest Additions

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:

  1. 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
  2. Change to the directory where your CD-ROM drive is mounted and execute as root:

    pkgadd -G -d ./VBoxSolarisAdditions.pkg
  3. 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.

4.2.3.2. Uninstalling the Solaris 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

4.2.3.3. Updating the Solaris Guest Additions

The Guest Additions should be updated by first uninstalling the existing Guest Additions and then installing the new ones. Attempting to install new Guest Additions without removing the existing ones is not possible.

4.2.4. Guest Additions for OS/2

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.


[18] An experimental WDDM driver was added with VirtualBox 4.1.