Host Setup

This document provides detailed host setup instructions for Debian- and Ubuntu-based systems. For other Linux distributions, please consult the respective official documentation to address distribution-specific differences.

QEMU

Install QEMU and its associated tools with the commands below:

sudo apt install qemu-system qemu-utils

Qlean uses qemu-bridge-helper to manage networking for multiple virtual machines, so it requires proper configuration.

For the default network helper, enabling the setuid bit is typically required. However, for improved security, it is recommended to use Linux capabilities for finer-grained privilege control instead. Specifically, the CAP_NET_ADMIN capability should be granted to the helper binary.

sudo chmod u-s /usr/lib/qemu/qemu-bridge-helper
sudo setcap cap_net_admin+ep /usr/lib/qemu/qemu-bridge-helper

The ACL mechanism enforced by qemu-bridge-helper defaults to blacklisting all users, so the qlbr0 bridge created by qlean must be explicitly allowed:

sudo mkdir -p /etc/qemu
sudo sh -c 'echo "allow qlbr0" > /etc/qemu/bridge.conf'
sudo chmod 644 /etc/qemu/bridge.conf

libvirt

First, install libvirt by running the following instructions:

sudo apt install libvirt-daemon libvirt-clients libvirt-daemon-system

Next, add the current user to the libvirt and kvm groups to enable non-privileged execution of related commands:

sudo usermod -aG libvirt,kvm $USER
newgrp libvirt
newgrp kvm

Qlean automatically falls back to QEMU's TCG (Tiny Code Generator) engine when KVM is unavailable. Nevertheless, adding the user to the kvm group is still required to obtain permissions for using vsock. Under normal circumstances, running ls -l /dev/vhost-vsock should display:

crw-rw---- 1 root kvm 10, 241 Jan 28 06:00 /dev/vhost-vsock

Finally, start the libvirt service to verify that the installation was successful:

sudo systemctl enable libvirtd
sudo systemctl start libvirtd
virsh list --all

(Optional) Configure network

Qlean uses a dedicated libvirt virtual network to provide isolated, reproducible networking for test VMs. The default network definition is stored at ~/.local/share/qlean/network.xml as follows:

<network>
  <name>qlean</name>
  <bridge name='qlbr0'/>
  <forward mode="nat"/>
  <ip address='192.168.221.1' netmask='255.255.255.0'>
    <dhcp>
      <range start='192.168.221.2' end='192.168.221.254'/>
    </dhcp>
  </ip>
</network>

This defines a NAT network named qlean in libvirt, backed by the Linux bridge qlbr0 at 192.168.221.1. DHCP hands out addresses in 192.168.221.2–192.168.221.254 on the 192.168.221.0/24 subnet so VMs can reach each other, the host, and the outside world through NAT.