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 and managed by VM Reactor itself), nftables and dnsmasq. It works together with the Stratum modules – firewall, security, WireGuard mesh, Ansible, support, telemetry – 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-init) 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 stratum-zram and ksmtuned for the memory setup, and recommends stratum-firewall. 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), and the status lights of the Host card show the state of KVM, LXC and Docker, of the memory techniques and of the protection.

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: 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).

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
thin lvmthin /var/lib/vm-reactor/storage/thin guests source=vmr-thin/data

Types: dir (Directory), nfs (NFS share) and lvmthin (LVM thin pool: thin volumes and snapshots). Add them in Storage; the web interface checks the tools and can format a new disk.

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)

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.

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); 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): compression (stratum-zram with a type for VM hosts, zstd or lz4, and the recommended kernel values for a hypervisor), deduplication (KSM with ksmtuned; KSM belongs to the physical host – inside a virtual machine ksmtuned does not start) and the 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 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.