KVM Backend for VirtualBox

This repository contains a KVM backend for the open source virtualization tool VirtualBox. With this backend, Linux KVM is used as the underlying hypervisor.

Note: VirtualBox is a trademark owned by Oracle. This project has no affiliation with Oracle.

What to expect

The basic look and feel will be largely unchanged. The user is able to boot the same guest VMs as in their existing configuration.

Nonetheless, there are the following benefits of using the KVM backend:

VirtualBox VMs can run in parallel to QEMU/KVM
VirtualBox kernel driver (vboxdrv) is not required
Modern virtualization features supported by KVM are automatically used (e.g. APICv)
KVM is part of the Linux kernel and therefore always directly available with every kernel update

Due to the replacement of the underlying hypervisor, there will be differences in the guest performance. Performance differences heavily depend on the guest workload.

How to use

There are no prebuilt packages of the resulting program and it needs to be built from source. The process of building VirtualBox from source can be found on virtualbox.org and only minor adjustments are required to integrate the KVM backend.

On a fresh install of Ubuntu 22.04, you can use the following command to install all prerequisites via apt:

apt install acpica-tools chrpath doxygen g++-multilib libasound2-dev libcap-dev \
        libcurl4-openssl-dev libdevmapper-dev libidl-dev libopus-dev libpam0g-dev \
        libpulse-dev libqt5opengl5-dev libqt5x11extras5-dev qttools5-dev libsdl1.2-dev libsdl-ttf2.0-dev \
        libssl-dev libvpx-dev libxcursor-dev libxinerama-dev libxml2-dev libxml2-utils \
        libxmu-dev libxrandr-dev make nasm python3-dev python2-dev qttools5-dev-tools \
        texlive texlive-fonts-extra texlive-latex-extra unzip xsltproc \
        \
        default-jdk libstdc++5 libxslt1-dev linux-kernel-headers makeself \
        mesa-common-dev subversion yasm zlib1g-dev glslang-tools \
        libc6-dev-i386 lib32stdc++6 libtpms-dev

Newer GCC versions (>= 12) might cause build issues. The command above installs a compatible version on Ubuntu 22.04.

After having all the prerequisites installed, the build process can be condensed to the following steps:

$ # Download the VirtualBox 7.0.20 source package from Oracle.
$ tar xf VirtualBox-7.0.20.tar.bz2
$ git clone https://github.com/cyberus-technology/virtualbox-kvm vbox-kvm
$ cd VirtualBox-7.0.20
$ git init
$ git add *
$ git commit -m "VirtualBox vanilla code"
$ git am ../vbox-kvm/patches/*.patch
$ ./configure --with-kvm --disable-kmods --disable-docs --disable-hardening --disable-java
$ source ./env.sh
$ kmk

The noticeable difference to the official build process is the addition of --with-kvm when calling ./configure.

Note: These instructions are intended for local building and testing purposes only. There are more considerations when packaging for a distribution. We do not advise or recommend instructions for packaging at this time.

Known issues and limitations

Currently, Intel x86_64 is the only supported host platform.
- AMD will most likely work too but is considered experimental at the moment.
- Processor support for the XSAVE instruction is required. This implies a 2nd Gen Core processor or newer.
Linux is required as a host operating system for building and running the KVM backend.
Starting with Intel Tiger Lake (11th Gen Core processors) or newer, split lock detection must be turned off in the host system. This can be achieved using the Linux kernel command line parameter split_lock_detect=off or using the split_lock_mitigate sysctl.

Networking

The new KVM backend utilizes the --driverless mode of VirtualBox. Some setups that require kernel module support will not work in this mode and prevent the VM from starting. Specifically, the Bridged adapter and "NAT Network" modes do not work. Only regular NAT is easily supported. More complex setups will need manual configuration, e.g., using tun/tap devices.

USB pass-through

USB device pass-through is supported. Some udev rules are required to trigger the creation of fitting device nodes, though. VirtualBox provides the out/linux.amd64/bin/VBoxCreateUSBNode.sh script to create the right nodes. Distribution-provided packages will usually take care of the required setup. The following is a short summary of the additional configuration steps, which might differ based on the distribution. Be sure to know what you are doing when following these steps. This can potentially interfere with existing installations.

Create a group vboxusers and add your user to the group. Remember group changes need a re-login or newgrp to take effect.
```
sudo groupadd -r vboxusers -U <username>
```

Place the VBoxCreateUSBNode.sh script in a system accessible folder

sudo mkdir /usr/lib/virtualbox
sudo cp out/release/linux.amd64/bin/VBoxCreateUSBNode.sh /usr/lib/virtualbox
sudo chown -R root:vboxusers /usr/lib/virtualbox

Create a udev rule file (e.g. 60-vboxusb.rules) in /etc/udev/rules.d/ with the following entries:

SUBSYSTEM=="usb_device", ACTION=="add", RUN+="/usr/lib/virtualbox/VBoxCreateUSBNode.sh $major $minor $attr{bDeviceClass}"
SUBSYSTEM=="usb", ACTION=="add", ENV{DEVTYPE}=="usb_device", RUN+="/usr/lib/virtualbox/VBoxCreateUSBNode.sh $major $minor $attr{bDeviceClass}"
SUBSYSTEM=="usb_device", ACTION=="remove", RUN+="/usr/lib/virtualbox/VBoxCreateUSBNode.sh --remove $major $minor"
SUBSYSTEM=="usb", ACTION=="remove", ENV{DEVTYPE}=="usb_device", RUN+="/usr/lib/virtualbox/VBoxCreateUSBNode.sh --remove $major $minor"

Reload the udev rules
```
sudo systemctl reload systemd-udevd
```

SR-IOV Graphics Virtualization

If you want to use the graphics virtualization features of modern Intel processors, please refer to our SR-IOV Graphics Virtualization HowTo.

Nested Virtualization

If you want to use nested virtualization, you need to run the following command:

VBoxManage modifyvm <vm_name> --nested-hw-virt on

Please note that nested virtualization is only supported for Intel CPUs. Nested virtualization on AMD is currently unsupported.

How to engage

If you would like to use our KVM backend or if you have a need for custom virtualization solutions, we are happy to provide guidance and engineering services. Please reach out to us via our support form or via e-mail at service@cyberus-technology.de.

If you encounter any issues please use the provided issue template and describe your problem as detailed as possible.

Licensing

This source code is released under the GPLv3, the same license terms as the original VirtualBox Open Source release it is derived from. See the LICENSE file and the upstream COPYING file for details. Make sure to follow licensing conditions when redistributing.

cyberus-technology / virtualbox-kvm

readme