// writeup

VM-TUNE

bash libvirt qemu/kvm vfio github.com/ArchIsOverrated/VM-TUNE ↗

Cyberpunk 2077 running with full gpu acceleration in virtual machine. — Sample of Cyberpunk 2077 running in virtual machine optimized by vmtune toolkit.

What It Is

A small collection of helper scripts I use to build and configure a custom Fedora VM environment — GPU passthrough, VM creation. Meant to make the creation of high performance virtual machines easy through the use of vmtune tool in the CLI.

Why I Built It

Setting up GPU passthrough on a fresh machine means hand-editing kernel command lines, loading VFIO module loads, writing libvirt hooks for hugepages and CPU isolation, takes hours of setup and research to do. This tool handles that for you and makes it easy.

How It's Structured

Two entry points and one runtime CLI:

setup.sh — Installs the virtualization stack for you along with setting up and installing vmtune CLI to /usr/local/bin.
bin/vmtune — the wrapper users actually run. A wrapper for vmtune.sh. Invokes polkit policies so that sudo is not needed to run vmtune
bin/vmtune.sh — the code that the vmtune wrapper executes. vmtune -h lists every subcommand.

The supporting scripts are installed to /usr/local/lib/VMTUNE and called by vmtune behind the scenes:

configurevm.sh — sets up the libvirt hooks for hugepages and CPU isolation. Includes a limited guided flow for adding the hugepages tag and CPU pinning to a VM's XML.
createvm.sh — bootstraps a new VM with sensible defaults.
gpu_passthrough.sh — configures VFIO and rewrites kernel boot args.
install_looking-glass.sh — fetches Looking Glass source and compiles the client (broken at the moment, I will fix it later).

The Libvirt Hooks

The performance wins live here. A dispatcher script under /etc/libvirt/hooks/qemu fans out to three hook scripts on VM start, and reverses them on shutoff:

hugepages.sh — switches the VM's backing memory from 4 KiB to 2 MiB pages. Requires the hugepages tag in the VM's XML and a RAM allocation that's a multiple of 2.
isolatecpus.sh — moves systemd services off the pinned VM cores so the guest takes less kernel-level noise. Requires CPU pinning to be set in the XML.
performancegoverner.sh — flips the CPU governor to performance on VM start and back to powersave on shutoff.

Assets That Ship With It

assets/50-vmtune.rules — polkit rule, installed to /usr/share/polkit-1/rules.d/. Lets anyone in the libvirt group connect to VMs under the vmtune policy.
assets/vmtune.policy — the policy file the rule applies.
assets/fakebattery.dsl + fakebattery.aml — ACPI source and compiled machine code for a fake battery, handed to the guest so it thinks the host has one. Useful for Windows guests on a desktop host. This is because Nvidia mobile gpu drivers refuse to load if a battery is not detected.

Warning: Don't run the VM image off a BTRFS filesystem — performance tanks. If you must, disable copy-on-write on the directory where the image lives.

What's Next

Probably overhaul the whole project. Especially the gui for a making my own Linux distribution I have planned. Some of the code is not optimal so re-writes are needed.