skraba.net

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
<WRAP centeralign>
{{vm-reactor:logo.png?96&nolink|VM Reactor}}

====== VM Reactor ======

**Virtual machines, containers and applications – one web interface for your Debian host.**

KVM virtual machines, LXC system containers and Docker applications side by side: one list, one number for every guest, one place to start, watch, back up and protect them. Part of the [[stratum:start|Stratum]] project – your host remains Debian.
</WRAP>

{{vm-reactor:overview-dark.png?1200&nolink|VM Reactor – overview of the host}}

<WRAP centeralign>
**VM Reactor 0.24 – Technical Preview** · Debian 13 (trixie) and Debian 14 (forky) · amd64 and arm64 · free software (GPL-3+) · package ''vm-reactor'' in the Stratum repository (component //contrib//)
</WRAP>

<WRAP center round important 80%>
**Technical preview.** VM Reactor is new and still changing: features, settings and the web interface may change from one version to the next. Try it, test it and tell us what you think – but keep backups of your guests and do not rely on it alone for production systems yet.
</WRAP>

<WRAP center round info 80%>
**A contrib package of the Stratum repository.** VM Reactor is published in the component //contrib// of the Stratum repository, next to the Stratum modules in //main//. It builds on Stratum – it needs ''stratum-core'' and works together with the Stratum modules – but it enjoys a certain independence from them: its own versions and release cycle, its own web interface, its own handbook and this page of its own.
</WRAP>

===== Overview =====

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.

<grid cols="1fr 1fr 1fr">
<col>
<card header="Machines" subtitle="KVM · libvirt" shadow="small">
Create a virtual machine with a wizard, install it from an ISO image, use the graphical console (VNC) or the serial console in the browser. Disks, snapshots, clones, guest agent, hardware watchdog, start order with the host.
</card>
</col>
<col>
<card header="Containers" subtitle="LXC · unprivileged" shadow="small">
Complete Linux systems – Debian, Ubuntu, Alpine and more – from the LXC image server, started in seconds. A shell in the browser, resource limits, snapshots, backups, the same network and firewall as the machines.
</card>
</col>
<col>
<card header="Applications" subtitle="Docker · compose" shadow="small">
Docker from Docker's own repository, installed together with VM Reactor and managed by it; applications as compose projects – a compose file, a pasted ''docker run'' command, an image wizard or a template (nginx, Nginx Proxy Manager, Uptime Kuma, Vaultwarden, Portainer, MariaDB, Nextcloud …). Automatic updates with rollback, CPU and memory limits, registries, images, volumes, networks and events in one place.
</card>
</col>
</grid>

<grid cols="1fr 1fr 1fr">
<col>
<card header="Storage" subtitle="Directory · Btrfs pool · LVM thin pool · NFS share" shadow="small">
Guests, ISO images, LXC templates and backups in the storage you choose: a directory, a btrfs pool on one or more disks – RAID 0, 1, 1C3 or 10, snapshots, compression and checksums – an LVM thin pool or an NFS share. Disks of the pools are added, removed and replaced while the guests keep running.
</card>
</col>
<col>
<card header="Network" subtitle="NAT · LAN · bridges" shadow="small">
A NAT network with DHCP, DNS, fixed addresses and **published ports** – for machines, containers and applications alike; guests directly in your local network (macvtap / macvlan); internal bridges and bridges on network cards – with confirmation and automatic rollback.
</card>
</col>
<col>
<card header="Protection" subtitle="firewall · backups · watchdog" shadow="small">
A firewall for every guest (nftables, anti-spoofing), backups as one file each – manual or scheduled, here or on another host, with retention rules and protected backups, restore under a new ID – and a watchdog that restarts what has failed.
</card>
</col>
</grid>

<grid cols="1fr 1fr 1fr">
<col>
<card header="Users and roles" subtitle="5 roles · guest scopes" shadow="small">
viewer, user, operator, manager and admin – each user sees only the guests you give them. Two-factor sign-in (TOTP), allowed networks, sign-in limits, session timeout and an audit log of every change.
</card>
</col>
<col>
<card header="Memory" subtitle="on by default · deduplication · compression · ballooning" shadow="small">
A page of its own and switched on by default: deduplication (ksm), compression (zram, zstd) and ballooning (virtio-balloon with free page reporting and an automatic balloon) – tuned for a hypervisor, managed by ''stratum-memory''. The Overview shows in real time how much RAM each of them saves.
</card>
</col>
<col>
<card header="Clear at a glance" subtitle="search · notifications · Stratum" shadow="small">
**Ctrl+K** finds any guest by name, ID or address, any page and setting; the **bell** gathers what needs attention – watchdog checks, failed backups, guests whose storage is offline. Sign-in protection and remote support have their own tabs in the settings, the WireGuard mesh is on the Network page.
</card>
</col>
</grid>

<grid cols="1fr 1fr">
<col>
<card header="Migrations" subtitle="paired hosts · offline · live" shadow="small">
Hosts are paired once with a one-time code – over the LAN, the WireGuard mesh or any route. A guest moves to another host **offline** (every type: shut down, copied, started there) or **live** (a running machine keeps running while its memory and disks are copied). Checks first, removed here only when it runs there.
</card>
</col>
<col>
<card header="Backups on another host" subtitle="schedules · retention · fetch back" shadow="small">
A storage of a paired host is a backup target like any other – in **Back up now** and in schedules, with the retention rules applied there. The Backups page lists the backups of this host on every paired host; one click fetches a backup back to restore it here.
</card>
</col>
</grid>

===== A look inside =====

<grid cols="1fr 1fr">
<col>
{{vm-reactor:guests.png?700&nolink|Guests}}
<WRAP centeralign>//Guests – machines, containers and applications in one list, one ID each.//</WRAP>
</col>
<col>
{{vm-reactor:guest-2.png?700&nolink|A virtual machine}}
<WRAP centeralign>//A virtual machine – state, configuration and load charts.//</WRAP>
</col>
</grid>

<grid cols="1fr 1fr">
<col>
{{vm-reactor:guest-1-console.png?700&nolink|Shell of a container}}
<WRAP centeralign>//The console in the browser – the shell of a container.//</WRAP>
</col>
<col>
{{vm-reactor:network.png?700&nolink|Network}}
<WRAP centeralign>//Network – traffic of the host, the NAT network, the WireGuard mesh and the bridges.//</WRAP>
</col>
</grid>

<WRAP centeralign>
**More guests in the same memory – an advanced feature of VM Reactor.** **Memory** – a page of the main menu – brings three techniques together, always in this order: **deduplication** keeps identical memory pages of the virtual machines only once (ksm), **compression** keeps idle guest memory compressed in RAM (zram, typically 3:1 and more), and **ballooning** returns memory the machines do not use to the host (virtio-balloon). VM Reactor switches them on at the installation with values recommended for a virtualization host (''stratum-memory'', type //VM Reactor host//), and the panel **Memory management** on the **Overview** shows in real time – one curve each – how much RAM they save.
</WRAP>

<grid cols="1fr 1fr">
<col>
{{vm-reactor:memory.png?700&nolink|Memory}}
<WRAP centeralign>//Memory – memory management at the top, then deduplication (ksm) and compression (zram with zstd or lz4), each with its light, its numbers and its chart.//</WRAP>
</col>
<col>
{{vm-reactor:memory-balloon.png?700&nolink|Ballooning}}
<WRAP centeralign>//Ballooning – free page reporting and an automatic balloon that never shrinks a machine below its minimum memory.//</WRAP>
</col>
</grid>

<grid cols="1fr 1fr">
<col>
{{vm-reactor:backups.png?700&nolink|Backups}}
<WRAP centeralign>//Backups – the state at a glance, schedules with retention rules, protected backups.//</WRAP>
</col>
<col>
{{vm-reactor:settings-security.png?700&nolink|Settings – Security}}
<WRAP centeralign>//Settings – Security: the sign-in protected by stratum-security.//</WRAP>
</col>
</grid>

<WRAP centeralign>
{{vm-reactor:migrations.png?960&nolink|Migrations}}

//Migrations – paired hosts, the checks before a migration, offline or live.//
</WRAP>

===== Installation =====

==== What you need ====

^ Item ^ Requirement ^
| System | **Debian 13 (trixie)** or **Debian 14 (forky)**, ''amd64'' or ''arm64'' – a physical computer or a virtual machine with nested virtualization |
| Virtualization | **VT-x / AMD-V** switched on in the firmware for KVM machines; without it, machines run emulated and slowly (containers and applications do not need it) |
| Stratum | ''stratum-core'' 0.49 or newer (the Stratum core, written in Go) and the Stratum repository with the components ''main'' **and** ''contrib'' – see [[stratum:start#quick_setup|Stratum – quick setup]] |
| Memory and disk | Enough for the host and all guests; memory compression, deduplication and the balloon help when it gets tight |
| Browser | Any current browser; the web interface uses HTTPS on port ''8443'' |

==== 1. The Stratum repository ====

If Stratum is not installed yet, follow the [[stratum:start#quick_setup|quick setup]] first. VM Reactor is in the component **contrib** – check that the APT source has it:

<card header="Terminal — root@host" shadow="large">
<code bash>
grep Components /etc/apt/sources.list.d/stratum.sources
# Components: main contrib non-free
</code>
</card>

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.

==== 2. Install the package ====

<card header="Terminal — root@host" shadow="large">
<code bash>
apt-get update
apt-get install vm-reactor
</code>
</card>

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:

<card header="Output" shadow="small">
<code>
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/
</code>
</card>

==== 3. First sign-in ====

  - 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.
  - Sign in as **admin** with the password from ''/etc/vm-reactor/initial-admin-password''.
  - 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''.
  - 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.

<WRAP round tip>
**Docker** is installed together with VM Reactor. If you answered no, or the setup stopped – for example because Debian's ''docker.io'' is installed, which VM Reactor never removes by itself; the bell says why – open **Docker** in the web interface and choose **Install Docker**, or run ''vm-reactor docker setup''. Compose projects that already run on the host become applications with **Docker → Import a compose project** (''vm-reactor docker import <folder>'').
</WRAP>

==== 4. Your first guests ====

**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**.

===== Administration =====

==== Users and roles ====

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

^ Role ^ May ^
| **viewer** | see the guests of the scope: state, configuration, tasks |
| **user** | + start, shut down, stop, reboot and use the console |
| **operator** | + snapshots, backups and logs |
| **manager** | + create, change, clone and delete guests, Docker compose, disks, ISO images; restore and delete backups; schedules |
| **admin** | + the host: shell, storage, network, users, security, settings (always all guests) |

<card header="Terminal — root@host" shadow="large">
<code bash>
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
</code>
</card>

==== Securing the web interface ====

  * **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''.

==== Network ====

^ Network ^ What the guest gets ^
| **NAT** (bridge ''vmnat0'', ''10.10.10.0/24'' by default) | a private address from the host's DHCP, names ''<name>.vm-reactor.lan''; reachable from outside through **published ports**. Fixed addresses below the DHCP range. |
| **Local network** | its own address in your LAN (machines: macvtap, containers: macvlan) – the host itself cannot reach these guests |
| **Bridge** | a bridge on a network card (''vmbrN'') – guests are like computers next to the host; the change of ''/etc/network/interfaces'' must be confirmed within 60 seconds, otherwise it is rolled back |
| **Internal bridge** | a bridge without a network card – guests talk only to each other |
| **Applications** | the front service of a Docker application joins the NAT network (Docker network ''vmnat'' on ''vmnat0'', addresses ''.64''–''.95'' by default, ''NAT_DOCKER''): a fixed address, ''<name>.vm-reactor.lan'', published ports and the firewall of the guest; its other services (e.g. a database) stay in the application's own network. New applications join by themselves, existing ones under **Network** of the application. |

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

==== Storage ====

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

<card header="File — /etc/vm-reactor/storage.conf" shadow="small">
<code>
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
</code>
</card>

**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.

<card header="Terminal — root@host" shadow="large">
<code bash>
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
</code>
</card>

==== Backups and restore ====

<card header="Terminal — root@host" shadow="large">
<code bash>
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
</code>
</card>

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 ====

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

  - **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.
  - **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.

^ Mode ^ Guests ^ How ^
| **Offline** | machines, containers, applications | shut down, backed up, copied (checksum), restored and started there |
| **Live** | running machines (KVM) | ''virsh migrate --live --copy-storage-all'': memory and disks are copied while the machine runs, the pause at the end is short; the target storage is a directory or NFS storage. Needs the same or a newer QEMU there (between major versions some device states may not load – the machine then keeps running here), the same processor model when KVM uses the host processor, and the ports ''49152''–''49215'' (opened for the other host only while the migration runs). |

<code bash>
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)
</code>

==== Docker ====

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.

<code bash>
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
</code>

==== Start, shutdown, watchdog ====

  * **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.

==== Stratum modules ====

^ Module ^ With VM Reactor ^ Where ^
| stratum-firewall | rules of the web interface, the NAT network and published ports | automatic |
| stratum-security | fail2ban protects the sign-in (jail ''vm-reactor'') | Settings → Security |
| stratum-wireguard | the NAT network is announced in the mesh; the members reach the guests | Network |
| stratum-support | support sessions; ''vm-reactor report'' is part of the diagnostic report | Settings → Support |
| stratum-memory | compression (zram), deduplication (ksm) and the automatic ballooning of the machines | Memory |
| stratum-ansible | dynamic inventory of the machines and containers | ''vm-reactor inventory'' |

==== Command line ====

<card header="Terminal — root@host" shadow="large">
<code bash>
vm-reactor list                 # all guests: ID, type, name, state, storage
vm-reactor start 3              # also: shutdown, stop, reboot
vm-reactor url                  # address of the web interface
vm-reactor docker help          # Docker and the applications
vm-reactor migrate 7 host2      # move guest 7 to the paired host host2 (--live, --check)
vm-reactor backup prune --dry-run   # backups the retention rules would remove
vm-reactor help                 # every command and switch
systemctl status vm-reactor     # the web interface and the API
</code>
</card>

==== Files ====

^ Path ^ Contents ^
| ''/etc/vm-reactor/vm-reactor.conf'' | settings (port, allowed networks, sign-in limits, watchdog …) |
| ''/etc/vm-reactor/guests/<id>.conf'' | one file per guest |
| ''/etc/vm-reactor/storage.conf'', ''network.conf'', ''users.conf'' | storages, networks, users |
| ''/etc/vm-reactor/tls/'' | certificate of the web interface |
| ''/etc/vm-reactor/peers.json'' | paired hosts (address, certificate, secret) |
| ''/var/lib/vm-reactor/'' | guests, ISO images, templates, backups (storage ''local'') |
| ''/var/log/vm-reactor/'' | ''audit.log'' and the logs of the tasks |

==== Updates ====

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.

===== VM Reactor Handbook =====

<WRAP center round important 80%>
**The VM Reactor Handbook is being written.** This first draft contains the cover, the complete contents and the first chapters; the chapters shown in grey in the contents are in preparation and follow in the next drafts, together with VM Reactor itself.
</WRAP>

<grid cols="1fr 2fr">
<col>
<WRAP centeralign>
[[https://www.skraba.net/stratum-apt/handbook/vm-reactor-handbook.pdf|{{vm-reactor:vm-reactor-handbook-cover.png?300&nolink|VM Reactor Handbook – cover}}]]
</WRAP>
</col>
<col>
**The guide to running machines, containers and applications side by side on Debian** – for the people who use them and for the administrators who run the host. Every chapter is marked with the readers it is meant for.

  * **Getting started** – what VM Reactor is, installation and a tour of the web interface //(in this draft)//
  * **Guests** – machines, containers and applications; consoles, snapshots and clones; starting, stopping and the watchdog //(in preparation)//
  * **Resources of the host** – storage, memory, networks, backups and restore //(in preparation)//
  * **Administration** – users and roles, securing the web interface, the Stratum integrations and updates //(in preparation)//
  * **Reference** – every command and switch, files, troubleshooting and a glossary //(in preparation)//

<card header="Download" shadow="small">
**[[https://www.skraba.net/stratum-apt/handbook/vm-reactor-handbook.pdf|VM Reactor Handbook (PDF, A4, 28 pages, 0.7 MB)]]** \\
Draft · November 2026 · VM Reactor 0.24 · Stratum Project \\
On a VM Reactor host: ''apt install vm-reactor-handbook'' (or **Settings – Packages**) – the book is then at ''/usr/share/vm-reactor/handbook/vm-reactor-handbook.pdf'', with a link in ''/root/vm-reactor-handbook.pdf''.
</card>
</col>
</grid>

<WRAP centeralign>
{{vm-reactor:vm-reactor-handbook-preview.png?960&nolink|VM Reactor Handbook – cover, contents and a chapter}}
</WRAP>