VM Reactor

VM Reactor turns a Debian computer into a host for guests. It manages virtual machines (KVM with libvirt), system containers (LXC) and applications (Docker compose projects) in one web interface with its own port – HTTPS, 8443 by default. Every guest has a number: the host is ID 0, the guests are 1, 2, 3 …, whatever their type. Each guest has exactly one configuration file (/etc/vm-reactor/guests/<id>.conf) and one directory in a storage – nothing is hidden in a database, and everything the web interface does can also be done on the command line with vm-reactor.

VM Reactor uses the tools Debian already has: libvirt and QEMU, LXC, Docker from Docker's own repository (installed together with VM Reactor and managed by it), nftables and dnsmasq. It works together with the Stratum modules – firewall, sign-in protection, WireGuard mesh, support – when they are installed.

If Stratum is not installed yet, follow the quick setup first. VM Reactor is in the component contrib – check that the APT source has it:

grep Components /etc/apt/sources.list.d/stratum.sources
# Components: main contrib non-free

Sources written by older versions of stratum-archive-keyring have only main; installing the current stratum-archive-keyring (or stratum-core) adds contrib and non-free by itself.

apt-get update
apt-get install vm-reactor

APT brings everything VM Reactor needs from Debian – libvirt and QEMU, LXC, nftables, dnsmasq, noVNC – together with the Stratum modules it works with: stratum-memory for the memory setup, stratum-firewall, stratum-security, stratum-watchdog, stratum-software, stratum-support and stratum-wireguard. The installation asks one question – Install Docker from Docker's repository? (yes by default): VM Reactor then sets up Docker's key and repository and installs Docker as soon as APT has finished, as a task you can follow under Tasks. At the end, the installation prints the address of the web interface and where the first password is:

vm-reactor: first sign-in as user admin, password in /etc/vm-reactor/initial-admin-password
         (change it in the web interface: Security - My account; then delete the file)
vm-reactor: web interface https://10.0.0.22:8443/

1. Open the address in the browser (vm-reactor url prints it again). The certificate is created on the host and is not signed by an authority – the browser asks once whether to trust it.
2. Sign in as admin with the password from /etc/vm-reactor/initial-admin-password.
3. In Users → My account set your own password and switch on two-factor sign-in (an authenticator app); then delete the file: rm /etc/vm-reactor/initial-admin-password.
4. Look at the Overview: the warnings at the top tell you what is still missing (for example hardware virtualization or noVNC), the status lights of the Host card show the state of KVM, LXC and Docker, of the memory techniques and of the protection, and the bell in the top bar lists what needs attention.

Create guest opens a wizard: choose the type, the name and the storage; a machine gets an ISO image, cores, memory and a disk, a container a system image, an application a compose file or a template. The guest appears in the list with the next free ID. By default it is in the NAT network and gets an address from the host's DHCP; publish ports to reach it from outside, or put it directly into your LAN.

Every role includes the rights of the ones before it. Users other than admins see only the guests in their scope (all, or a list of IDs).

vm-reactor user add anna operator 3,4,7     # asks for the password
vm-reactor user list
vm-reactor user guests anna all
vm-reactor user 2fa-off anna                 # lost phone: switch two-factor sign-in off
vm-reactor user disable anna                 # sessions end at once

• Allowed networks (Users, ALLOW_FROM): only these networks reach the web interface; VM Reactor refuses a change that would lock you out.
• Sign-in limits: after LOGIN_ATTEMPTS failed sign-ins an address is blocked for 10 minutes; session timeout in minutes (SESSION_TIMEOUT).
• stratum-security (Settings → Security): the protected service vm-reactor – fail2ban bans addresses with too many failed sign-ins.
• stratum-firewall: VM Reactor writes its own rules (port 8443, DHCP and DNS of the NAT network, forwarding of the guests) to /etc/stratum/firewall.d/vm-reactor.rules.
• Own certificate: replace /etc/vm-reactor/tls/vm-reactor.crt and vm-reactor.key and run systemctl restart vm-reactor. Behind a reverse proxy on the same host, LOCAL_HTTP_PORT offers plain HTTP on 127.0.0.1 only.
• Audit log: every sign-in and change is in /var/log/vm-reactor/audit.log.

Every guest also has its own firewall (nftables on the bridge): policies, rules and protection against address spoofing. With stratum-wireguard the NAT network can be announced in the mesh – the other members then reach the guests directly; when several hosts share a mesh, give each one its own NAT network (the guests keep the host part of their address).

Protection against lock-out. A change of the NAT network, of a bridge on a network card or of the access to the web interface (port, address, allowed networks under Settings – General) must be kept within 60 seconds: a banner with the countdown and Keep the change appears on every page. Confirm it from the browser over the new configuration; when the host can no longer be reached, the previous configuration comes back by itself (a systemd timer, vm-reactor settings-rollback).

The storages are listed in /etc/vm-reactor/storage.conf – one line each: name, type, path, content (guests, ISO images, templates, backups):

local dir /var/lib/vm-reactor guests,iso,templates,backup
data btrfs /var/lib/vm-reactor/storage/data guests,iso,templates,backup source=<uuid> options=compress=zstd:1
thin lvmthin /var/lib/vm-reactor/storage/thin guests source=vmr-thin/data

Add storage offers four types; the dialog checks your entries at once and shows what is wrong:

• Directory – any mounted directory: a second disk, an existing btrfs file system or an NFS share the host mounts itself. VM Reactor recognises the file system: on btrfs the guests get subvolumes and snapshots, on an NFS share the storage is offline while the share is not there.
• Btrfs pool – a new btrfs file system on one or more empty disks or partitions: single, RAID 0, RAID 1 (2+ disks), RAID 1C3 (3 copies, 3+ disks) or RAID 10 (4+ disks). RAID 5/6 are not offered – their write hole can lose data. The metadata always have two copies at least. Compression zstd, checksums with self-repair from the copies, instant snapshots of every guest (its own subvolume), clones as reflinks; disks of machines are raw files (optionally without copy-on-write). Disks on the card adds, removes and replaces disks – also a failed or missing one – converts the profile, starts a scrub or a balance and mounts a pool with a missing disk degraded, all while the guests keep running. VM Reactor watches the pools (missing disks, device errors, scrub results) and runs a scrub every 30 days.
• LVM thin pool – a new thin pool on one or more empty disks (or an existing one such as pve/data): thin volumes for disks of machines and file systems of containers, instant snapshots; disks can be added and taken out later. A thin pool cannot shrink – to take a disk out, the other disks need room for its data.
• NFS share – an export (server:/path), mounted by VM Reactor through /etc/fstab; the server must answer on port 2049.

vm-reactor storage list                                     # all storages: type, state, size, free space
vm-reactor storage add data btrfs /dev/sdb /dev/sdc --profile raid1 --yes   # a btrfs pool, RAID 1
vm-reactor storage disk add data /dev/sdd --yes              # one more disk, the data are spread
vm-reactor storage profile data raid1c3                      # three copies
vm-reactor storage disk replace data /dev/sdb /dev/sde --yes # replace a disk (devid:N: a missing one)
vm-reactor storage scrub data                                # check every block, repair from the copies
vm-reactor storage disk list data                            # disks, errors, the last scrub
vm-reactor storage add thin lvmthin --new /dev/sdf --yes     # an LVM thin pool
vm-reactor storage add share nfs 10.0.0.5:/srv/vm            # an NFS export

vm-reactor backup 2                        # guest 2, paused during the backup (default)
vm-reactor backup 2 --mode stop            # shut down, back up, start again
vm-reactor restore /var/lib/vm-reactor/backup/<file> --id 12   # restore as guest 12
vm-reactor backup prune --dry-run          # what the retention rules would remove
vm-reactor backup prune --guest 2 --keep-last 3 --keep-weekly 4   # own rules for guest 2
vm-reactor backup protect local:<file>     # never removed (--off: protection off)
vm-reactor backup 2 --storage peer:host2:local   # to the storage local of the paired host host2

A backup is one file in the backup storage; it can be exported, copied to another host and imported there. Backups → Schedules runs backups by itself – on the days and at the time you choose, for all guests or a list. Retention rules decide which backups stay: the last N, one per day, week, month or year for N periods, and a maximum age. A backup stays when any rule keeps it; the newest backup of a guest is never removed, and protected backups (lock) are never removed at all. The rules can be previewed before they are saved, manual and imported backups have rules of their own (off by default), and every removal is written to the audit log. A storage of a paired host (peer:<host>:<storage>) can be chosen in Back up now and in schedules: the backup is made here, copied there and the retention rules of the schedule run there; the Backups page shows the backups of this host on each paired host (Fetch here copies one back to restore it) and the backups other hosts keep here. Clean up now applies the configured rules – or rules of its own for this one clean-up – to all, the scheduled or the manual and imported backups, with a live preview that names for every backup the rule that keeps it; the top of the page shows the state, the last backup, the next scheduled run and the total size.

Migrations (main menu, Operations) moves guests between VM Reactor hosts.

1. Pair the hosts once. On the first host: Pairing code – a code valid for 15 minutes, with the address and the certificate of the host. On the second host: Pair a host, enter the address and the code. The hosts then trust each other: the web interface of the other host with its certificate pinned and a shared secret (/etc/vm-reactor/peers.json), and SSH as root with a key of VM Reactor, accepted only from the address of the other host – libvirt needs it for live migrations. Unpair removes all of it on both hosts.
2. Migrate. Choose the guest, the host and the storage there, then Check: storage and free space, the ID, the network, versions, processor and SSH. A guest keeps its ID when it is free there; its MAC address, published ports and firewall go along, a guest in the NAT network gets an address of the NAT network there. The guest is removed here only when it runs there; its backups stay here.

vm-reactor peers                              # the paired hosts, online or not
vm-reactor migrate 7 host2 --check            # only the checks
vm-reactor migrate 7 host2 --storage local    # offline
vm-reactor migrate 7 host2 --live             # a running machine, live
vm-reactor peers unpair host2                 # end the pairing (on both hosts)

VM Reactor takes care of Docker completely – there is nothing else to install:

• Installation and upgrades: Docker CE with compose and buildx from Docker's own repository (its key is checked against the published fingerprint) – at the installation of VM Reactor or later with Install Docker; the engine is upgraded with the system. On a Debian release Docker does not support yet, the packages of the release before are used – Switch appears as soon as Docker has its own.
• Settings (Docker → Settings): log rotation, address pool of new networks, live restore, IPv6, no-new-privileges, data location – checked by dockerd before Docker restarts.
• Automatic updates of the applications every night or every Monday at 04:30, with a mode per application: auto (update and restart), notify (download, you apply) or off. The images before an update are kept – Roll back returns to them.
• Limits: CPU and memory for all containers of an application (Resources of the application).
• The whole host: all containers (also those not made by VM Reactor), images, volumes, networks, disk usage and cleanup, events (crashed, out of memory, unhealthy) and the Docker users.

vm-reactor docker status                  # Docker, its settings and the applications
vm-reactor docker set logsize 10mx3       # 3 log files of 10 MB per container
vm-reactor docker update 5 --check        # download new images of application 5
vm-reactor docker rollback 5              # back to the images before the last update
vm-reactor docker import /opt/myapp       # an existing compose project becomes an application

• Start with the host: guests with autostart start in their start order with delays (vm-reactor-guests.service); at host shutdown they are shut down in reverse order, each with a timeout (SHUTDOWN_TIMEOUT).
• Watchdog: every WATCHDOG_INTERVAL seconds it checks the components (libvirt, LXC, Docker, the NAT network, the firewall rules, the storages) and the guests. A guest that should run but stopped or crashed is started again when its option restart is on – at most three times an hour; a machine whose guest agent stops answering is reset. With stratum-watchdog, VM Reactor itself is watched too.
• Memory (main menu): deduplication (ksm with ksmtuned; ksm belongs to the physical host – inside a virtual machine ksmtuned does not start), compression (zram with zstd or lz4 and the recommended kernel values for a hypervisor) and ballooning (virtio-balloon: free page reporting, and an automatic balloon that never takes a machine below its minimum memory – half its memory by default, Hardware). All of it is done by stratum-memory with the type of computer VM Reactor host – VM Reactor shows it and changes its settings; it is switched on at the installation, vm-reactor memory-defaults –force applies it again.

VM Reactor is updated with APT like every other package (apt-get upgrade). Restarting the web interface does not touch the guests – they keep running.

Optional packages (Settings – Packages, one click each): vm-reactor-virtio-win – the VirtIO drivers for Windows machines (the virtio-win ISO image 0.1.302 of the Fedora project, BSD licence): it appears in the storage local among the ISO images as virtio-win-0.1.302.iso – attach it to a Windows machine as a second CD drive and load the drivers during the Windows setup (viostor or vioscsi) or install them all afterwards with virtio-win-guest-tools.exe; vm-reactor-handbook – the VM Reactor Handbook as PDF.

VM Reactor is written in Go – the server, the API and the command line are one Go program; the web interface uses Vue.js.