VirtualBox

VirtualBox is cross-platform virtualization software that allows users to run guest operating systems inside a host operating system without having to reboot. Since 2010 VirtualBox software has been written and maintained by the Oracle Corporation.

Installation
There is a source based package and a binary package  available in the Portage tree. The binary version is available so 64bit no-multilib users can use VirtualBox, too. The binary package contains some extensions which are not available in the source package. To get identical functionality with the source package, additionally emerge the package.

The  or   USE controls installation of the graphical user interface (GUI) which is enabled by default.

VirtualBox 4.x
For VirtualBox versions < 5.0.0, enable the  USE flag when installing VirtualBox on the host system to get the Guest Additions ISO image that contains all necessary Windows guest drivers.

Virtualbox 5.x
Starting with versions >= 5.0.0, emerge the package on the host system to get the Guest Additions ISO image that contains all necessary Windows guest drivers:

Kernel configuration
When running Gentoo as a guest system, enable the following kernel options on the guest system (either built-in or as modules) to get proper support for the hardware emulated by VirtualBox:

Guest Additions
To install the Guest Additions, invoke the following command on the Gentoo guest system:

To enable the shared clipboard, display resizing, seamless mode, and drag and drop make sure the user running the X session belongs to the group:

Changes will not take effect until the user signs out and then signs in again (re-logins).

To install other Linux distributions as guest operating systems please refer to the distribution's documentation on how to install the drivers needed by VirtualBox or consult the official VirtualBox documentation.

VirtualBox shared folders in a Gentoo guest
VirtualBox shared folders can only be mounted after the virtualbox-guest-additions service has been started. Since this happens towards the end of the bootup sequence (OpenRC), a shared folder mount in will fail. Either:


 * Make the  mount option and add a mount/unmount pair of scripts in
 * View for information about adding extra dependencies for services.

Advanced networking-related
According to the ebuild's message after VirtualBox is installed and  can be installed for advanced network configuration. Install them only if advanced networking is required:

Kernel modules
Users will not be able to run and use VirtualBox if they are not a member of the group:

Changes will not take effect until the user re-login.

Load the required driver module into the kernel. This module is made available when has been emerged:

Optional modules:

OpenRC
When using OpenRC it is possible to automatically load the modules each time the system boots. Edit the file by adding the following VirtualBox modules:

Systemd
When using Systemd, a similar approach can be taken. Create a new file under the directory and list, separated by newlines, the kernel modules to load:

Modules can be loaded immediately by running:

Enable port forwarding to guest machines
When booting LiveCDs or other live media, it can be handy to enable port forwarding from the host machine to the guest machine. None of the additional network configuration modes are necessary to for a simple port forwarding setup, so do not dig too deep into upstream docs. Port forwarding can be handy when running a web server, an SSH daemon, or any other service that runs on a specific port.

First, be sure the guest VM is shutdown, then from the command line issue:

Be sure to replace  with the proper name of the guest virtual machine. The first number will be the port on the host machine. The second number will be the port on the guest machine. Adjust accordingly, then reboot the virtual machine. This can also be performed via the GUI by clicking ->  ->  (drop down) ->.

More details can be found in the upstream documentation.

Usage
There are many options which can influence behavior and performance of the virtual machines. If you don't know what these options are doing, leave them to their defaults. Virtual machines may become unbootable if the wrong options are set.

Here is a list of options that are safe to use:
 * Host I/O cache can safely be enabled for all virtual storage controllers.
 * If the host system's CPU supports hardware virtualization, enable the 'VT-x/AMD-V' option. It can drastically increase the performance of the virtual machines.

virtualbox fails to build
When the package fails to build because the  command cannot be found (even with a Java JDK (Java Development Kit) and a Java JRE (Java Runtime Environment) installed), it is likely the JRE has been set as the default system-vm. JRE packages do not contain. Make sure the correct system-vm (JDK) has been selected using the command and then try rebuilding virtualbox. More information can be found in the Installing a virtual machine section of the Java User Guide.

virtualbox-modules fails to build
Some users have issues with the package failing to build. This can be caused by an improper kernel/profile configuration. Verify the chosen kernel and the selected profile match each other. For example, if a hardened profile is set, a hardened kernel should be used. If a default AMD64 profile is set, then the default gentoo-sources should be used. Run the command to view the list of profile options:

Then use the command again to display which kernel is selected:

Looking at the output of these two commands, a user can determine if the system is setup properly (the profile matches the kernel) and should have no issues installing. Remember: Make sure the system profile and the selected kernel match!

virtualbox-modules permission denied errors
The following "Permission denied" errors can be caused by a strict file mode creation mask (e.g. ):

cc1: error: ./arch/x86/include/generated/uapi: Permission denied cc1: error: ./arch/x86/include/generated/uapi: Permission denied cc1: error: ./include/generated/uapi: Permission denied cc1: error: ./include/generated/uapi: Permission denied cc1: error: ./arch/x86/include/generated/uapi: Permission denied cc1: error: ./include/generated/uapi: Permission denied cc1: error: ./arch/x86/include/generated/uapi: Permission denied cc1: error: ./include/generated/uapi: Permission denied

The easiest solution would be to backup, run   and use the default.

Host key failing to operate in the virtual machine
If the host key (typically the right key) is failing to operate within the virtual (guest) machine, be sure any desktop environment or window manager hooks to host key have been disabled from the host machine's desktop environment or window manager.

For example, the GNOME 3 desktop environment includes a "Show location of the [mouse] pointer" option in the section of the Tweak Tool. This option will enable a ripple effect to be displayed around the mouse when either the right or left key is pressed. This mouse locator handle conflicts with the virtual machine's handle on the right key. Disabling this setting (via switching the rocker switch to Off in the Tweak Tool interface) should fix the problem by re-assigning the right key as the handle for the host key within the virtual machine.

Microsoft Windows guests

 * According to the documentation, the I/O APIC feature (VM -> Settings -> System -> Motherboard -> Enable I/O APIC), which is enabled by default, 'slightly increases the overhead of virtualization and therefore slows down the guest OS a little'. However, there have been reports that the performance impact may actually be quite severe on some host/guest system combinations (e.g. forum post). Be aware that disabling this feature might require additional steps on the guest system as described by this forum post.
 * Using a SATA controller, it is necessary to choose the right driver version from Intel's SATA drivers. Using a wrong version will cause performance problems along with blue screen errors! Refer to this post for a list of working SATA drivers.
 * Slow performance using SATA driver? Only use the SATA controller interface for the hard disk. Remove any CDROMs from the SATA controller and place them onto a IDE Controller.
 * When installing the VirtualBox Guest Additions into your Windows operating system, do not select to enable Direct3D (experimental) option as this will cause resizing problems and other anomalies. Also, you need to install the Guest Additions from Safe Mode.
 * Do not use the ICH9 chipset with Windows. It is still considered experimental. Using it can cause temporary freezes of the whole VM when used with Windows 7. See this post for more informations.
 * Slow read/write speed to the virtual disk? If the host system has sufficient RAM, try checking (enabling) the check box in the virtual machine's  frame. This will cache much of the guest machine's page file into the host's memory effectively limiting the amount of I/O guest machine will use the virtual disk image file. This is particularly helpful when running Windows guests because of the amount of paging Windows based operating systems regularly perform.

Linux guests

 * When running Gentoo as a guest system make sure you start the virtualbox-guest-additions init script during bootup.

Kernel driver not installed


This may occur after building a new kernel and causes an error message:

Solution: Rebuild the VirtualBox kernel modules via:

The system may need rebooted for changes to take effect.

Nonexistent host networking interface, named 'vboxnet0'
Newly created interface will now be shown as available, but not activated (down):

An IP will need to be assigned to it:

Kernel Panic when suspending the HOST while Virtualbox is running
If you experience such behavior, try removing the vbox family of modules before suspending. If this solves the kernel panic, you can add the vbox modules to the list of permanently removed modules before suspend, these modules are loaded automatically after suspend:

External resources

 * vboxweb_rb - Web-based administration utility (Ruby)
 * VirtualBox Manual