Document running tests in qemu

Author: teqwve

.gitignore

@@ -15,6 +15,8 @@ pin.log
 
 *.tar.gz
 
+*.qcow2
+
 // Various pycharm test related outputs
 *.log
 *.pyc
@@ -34,4 +36,4 @@ obj-x86*
 out/
 
 .vscode/
-.devcontainer/
+.devcontainer/

README.md

@@ -118,6 +118,66 @@ following cmake options:
     -DTEST_COMPILER_IN_DOCKER_DEBIAN_TAG="bookworm"
     -DTEST_COMPILER_IN_DOCKER_GCC_VERSION="12"
 
+Developing in QEMU
+---------------
+
+Sometimes it may be useful to run sio2jail in a virtual machine, e.g. to test running
+sio2jail under a different kernel version. In QEMU:
+
+    # get debian 11 QEMU image
+    wget https://cdimage.debian.org/images/cloud/bullseye/latest/debian-11-nocloud-amd64.qcow2
+
+    # reserve more space for QEMU image
+    qemu-img resize debian-11-nocloud-amd64.qcow2 +10G
+
+    # start QEMU with KVM and sio2jail sources mounted with virtfs
+    qemu-system-x86_64 \
+        -enable-kvm \
+        -m 4G \
+        -nographic \
+        -hda debian-11-nocloud-amd64.qcow2 \
+        -virtfs local,path=$SIO2JAIL_SOURCES,security_model=mapped-xattr,mount_tag=sio2jail \
+        -cpu max
+
+    # login as root (no password)
+
+    # resize root partition
+    apt update
+    apt install -y cloud-utils fdisk
+    growpart /dev/sda 1
+    resize2fs /dev/sda1
+
+    # install dependencies and utilities
+    apt install -y \
+        build-essential \
+        cmake \
+        gcc-multilib \
+        g++-multilib \
+        gperf \
+        wget
+
+    # mount sio2jail sources
+    mkdir /sio2jail
+    mount -t 9p -o trans=virtio sio2jail /sio2jail -oversion=9p2000.L,posixacl,msize=104857600
+
+    # enable required sysctls
+    sysctl -w kernel.perf_event_paranoid=-1
+    sysctl -w kernel.unprivileged_userns_clone=1
+
+    # create a separate user with same uid and gid as your local user (check id -u)
+    groupadd -g $GID dev
+    useradd -u $UID -g dev -m dev -s /bin/bash
+
+    # compile and run tests as you would usually
+    su dev
+    cd /sio2jail
+    mkdir build
+    cd build
+    make sio2jail
+    make check
+
+    # to exit virtual machine use Ctrl+A X, see QEMU manpage for more escape sequences
+
 Notes for developers
 --------------------