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.
- 1 Terminology
- 2 Installation
- 3 Configuration
- 4 Usage
- 5 Troubleshooting
- 6 See also
- 7 External resources
|Host operating system||The host computer. Most likely the physical hardware present in the room. For Gentoo users the host operating system would be Gentoo Linux|
|Guest operating system||The operating system to be installed or currently installed inside the VirtualBox emulation environment. Possible alternative operating systems include Microsoft Windows, Solaris, BSD, Debian, Ubuntu, etc.|
|VirtualBox Guest Additions||Drivers for the guest operating system. These drivers provide smoother operation with the Host operating system compared to the standard drivers installed by the Guest operating system.|
There is a source based package (app-emulation/virtualbox) and a binary package (app-emulation/virtualbox-bin) 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, emerge it with the
extensions USE being enabled.
qt4 USE controls installation of the graphical user interface (GUI) which is enabled by default.
Since many of the same files are provided by one package or the other, only one virtualbox package can be installed at a time on the same system (either app-emulation/virtualbox or app-emulation/virtualbox-bin. Trying to install them both at the same will with result in a Portage complaining about blockers.
USE flags for app-emulation/virtualbox Family of powerful x86 virtualization products for enterprise and home use
||Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)||global|
||Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally||global|
||Build without any graphic frontend||local|
||Add support for Java||global|
||Use dev-libs/libressl as SSL provider (might need ssl USE flag), packages should not depend on this USE flag||global|
||Build VBoxVolInfo that needs devicemapper from sys-fs/lvm2.||local|
||Add support for OpenGL (3D graphics)||global|
||Add support for PAM (Pluggable Authentication Modules) - DANGEROUS to arbitrarily flip||global|
||Add support for PulseAudio sound server||global|
||Add optional support/bindings for the Python language||global|
||Add support for the Qt GUI/Application Toolkit version 4.x||global|
||Enable building of SDK||local|
||Controls installation of special USB udev rules.||local|
||Build and install the VirtualBox webservice||local|
||Enable VNC (remote desktop viewer) support||global|
USE flags for app-emulation/virtualbox-bin Family of powerful x86 virtualization products for enterprise as well as home use
||Install Guest System Tools ISO||local|
||Install kchmviewer binary to enable online help (in MS CHM format)||local|
||Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces||global|
||Install without any graphic frontend||local|
||Add optional support/bindings for the Python language||global|
||Install the rdesktop client integration||local|
||Enable building of SDK||local|
||Install the VirtualBox webservice||local|
echo "app-emulation/virtualbox-bin PUEL" >> /etc/portage/package.license
emerge --ask app-emulation/virtualbox
emerge --ask app-emulation/virtualbox-bin
When using VirtualBox versions < 5.0.0, it is possible to enable the
additions USE when installing VirtualBox on the host system to get the ISO image that contains all necessary Windows guest drivers.
Starting with versions >= 5.0.0, emerge the app-emulation/virtualbox-additions package for Windows guest additions extensions:
emerge --ask app-emulation/virtualbox-additions
In order to run Gentoo as a guest system, invoke the following command in the Gentoo guest operating system:
emerge --ask app-emulation/virtualbox-guest-additions
To enable the shared clipboard, display resizing, seamless mode and drag and drop make sure the user running the X.org session belongs to the vboxguest group.
gpasswd -a <user> vboxguest
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 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 /etc/fstab will fail. Either:
- make the mount noauto and add a mount/unmount pair of scripts in /etc/local.d
- or see /etc/rc.conf for information about adding extra dependencies for services
According to the ebuild's message after VirtualBox is installed sys-apps/usermode-utilities and net-misc/bridge-utils can be installed for advanced network configuration. Install them only if advanced networking is required:
emerge --ask sys-apps/usermode-utilities
emerge --ask net-misc/bridge-utils
Users will not be able to run and use VirtualBox if they are not a member of the vboxusers group:
gpasswd -a <user> vboxusers
Changes will not take effect until the user re-login.
Load the required driver module into the kernel. This module is made available when app-emulation/virtualbox-modules has been emerged:
When using OpenRC it is possible to automatically load the modules each time the system boots. Edit the /etc/conf.d/modules file by adding the following VirtualBox modules:
modules="vboxdrv vboxnetadp vboxnetflt"
When using Systemd, a similar approach can be taken. Create a new file under the /etc/modules-load.d directory and list, separated by newlines, the kernel modules to load:
vboxdrv vboxnetadp vboxnetflt
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 app-emulation/virtualbox package fails to build because the javac 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 javac. Make sure the correct system-vm (JDK) has been selected using the java-config command and then try rebuilding virtualbox. More information can be found in the Configuring the Java Virtual Machine section of the Java article.
virtualbox-modules fails to build
Some users have issues with the app-emulation/virtualbox-modules 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 eselect command to view the list of profile options:
eselect profile list
 default/linux/amd64/13.0 *  default/linux/amd64/13.0/selinux  default/linux/amd64/13.0/desktop  default/linux/amd64/13.0/desktop/gnome  default/linux/amd64/13.0/desktop/gnome/systemd  default/linux/amd64/13.0/desktop/kde  default/linux/amd64/13.0/desktop/kde/systemd  default/linux/amd64/13.0/developer  default/linux/amd64/13.0/no-emul-linux-x86  default/linux/amd64/13.0/no-emul-linux-x86/desktop  default/linux/amd64/13.0/no-emul-linux-x86/desktop/gnome  default/linux/amd64/13.0/no-emul-linux-x86/desktop/gnome/systemd  default/linux/amd64/13.0/no-emul-linux-x86/desktop/kde  default/linux/amd64/13.0/no-emul-linux-x86/desktop/kde/systemd  default/linux/amd64/13.0/no-emul-linux-x86/developer  default/linux/amd64/13.0/no-emul-linux-x86/selinux  default/linux/amd64/13.0/no-multilib  default/linux/amd64/13.0/x32  hardened/linux/amd64  hardened/linux/amd64/selinux  hardened/linux/amd64/no-multilib  hardened/linux/amd64/no-multilib/selinux  hardened/linux/amd64/x32  hardened/linux/musl/amd64  default/linux/uclibc/amd64  hardened/linux/uclibc/amd64
Then use the eselect command again to display which kernel is selected:
eselect kernel list
 linux-3.13.10-hardened  linux-3.16.3-hardened-r1  linux-3.17.2-hardened-r1  linux-3.18.4-hardened  linux-3.18.5-gentoo *
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 app-emulation/virtualbox-modules. Remember: Make sure the system profile and the selected kernel match!
Host key failing to operate in the virtual machine
If the host key (typically the right Ctrl key) is failing to operate within the virtual (guest) machine, be sure any specific hooks to this 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 Keyboard and Mouse section of the Tweak Tool (gnome-extra/gnome-tweak-tool). This option will enable a ripple effect to be displayed around the mouse when either the right or left Ctrl key is pressed. This mouse locator handle conflicts with the virtual machine's handle on the right Ctrl 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 Ctrl key as the handle for the host key within the virtual machine.
Microsoft Windows guests
- Do not enable APIC for Microsoft Windows guests! VirtualBox also has a bad habit of enabling this option on its own will. The fix is to select the System Processor Driver (i.e. ACPI Uniprocessor PC) and manually upgrade (change) to the Advanced Configuration and Power Interface (ACPI) PC. Shutdown (not reboot), restart VirtualBox and ensure APIC is off, then boot the guest. As usual, always make a backup before playing with Windows. Note
Not true for all Windows operating systems. Windows XP and Windows 7 play nice with APIC as long as they got installed with APIC being enabled.
- 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.Note
This can also be a problem of using the wrong SATA-driver version.
- 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 Use Host I/O Cache check box in the virtual machine's Storage 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.
- 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:
- Kernel driver not installed (rc=-1908)
- The VirtualBox Linux kernel driver (vboxdrv) is either not loaded or there is a permission problem with /dev/vboxdrv. Please reinstall the kernel module by executing
- '/etc/init.d/vboxdrv setup'
- as root. If it is available in your distribution, you should install the DKMS package first. This package keeps track of Linux kernel changes and recompiles the vboxdrv kernel module if necessary.
emerge -1 @module-rebuild
You may need to restart your computer to validate the change.
Nonexistent host networking interface, named 'vboxnet0'
VBoxManage hostonlyif create
Newly created interface will not be shown with ifconfig. You will have to assign some IP to it:
VBoxManage hostonlyif ipconfig vboxnet0 --ip 192.168.56.101
- phpVirtualBox - Web-based administration utility (PHP)
- QEMU - A popular open source virtual machine emulator.
- VMware - A popular closed source virtual machine emulator.