Installation

This page sets up the first node. Every later node is added with a single command from the web UI; see Adding nodes.

The installer

staxmax ships as one signed installer, staxmax-<version>-linux-x64.run, with its signature staxmax-<version>-linux-x64.run.sig beside it. The same file installs a node and updates one. It carries everything it needs, including its own runtime for the installer.

Installers are not publicly available for download yet; contact Harness Automation for the current release.

1. Run the installer

Copy both files to the machine, then run the .run from its own directory, under its published name, with the .sig next to it:

cd /tmp
sudo sh ./staxmax-0.1.0-linux-x64.run -- --install -- --disk /dev/nvme1n1

Running it that way lets the node keep a copy of the installer, which it later hands to machines that join the cluster, so they install the same version.

Options go after the second --:

Option	Meaning
--disk /dev/XYZ	Dedicated disk or partition for the ZFS pool. All data on it is lost. Refused if it holds partitions or a filesystem, unless you also pass --force-disk.
--force-disk	Allow --disk to wipe a device that has partitions or filesystems.
--pool-size SIZE	How much of the system disk's free space the pool takes: a share such as 80%, or a size such as 200GiB or 1TiB (default: 100%, minimum 20 GiB). Use either --disk or --pool-size.
--pool NAME	Name of the storage pool (default stax). Every node must use the same name.
--iface IFACE	LAN interface the VMs attach to (default: the interface of the default route).
--keep-sleep	Leave suspend, hibernate and the lid switch as they are instead of offering to turn them off.
--yes	Don't ask for confirmation (sleep is turned off unless you also pass --keep-sleep).

The installer refuses a disk that is mounted, used as swap, holds the root filesystem, or already belongs to a ZFS pool. It shows the disk's current contents and asks before erasing it. Without --disk, the installer says where the pool will go and lists any empty disks it finds; to use one, stop and run it again with --disk.

What it does

1. Installs base packages, ZFS, and Incus from the Zabbly stable repository (its signing key is checked against a pinned fingerprint).
2. Initialises Incus with the layout staxmax expects: a ZFS storage pool (stax), a macvlan network lan on your LAN interface, and Incus listening on port 8443.
3. Opens ports 7443/tcp, 8443/tcp and 7443/udp (direct-cable beacons) if ufw is active.
4. Offers to turn off suspend, hibernate and sleep when the lid closes (the default answer is yes). A node that sleeps stops answering heartbeats, so the other nodes take over its VMs. It masks the systemd sleep targets and tells logind to ignore the lid and the suspend keys; staxmax-uninstall undoes this.
5. Installs and starts the staxmaxd service, and the staxmax admin command.

On Debian, ZFS is built with DKMS, which takes a few minutes; the installer enables the contrib component for it. If the ZFS module does not load after a kernel upgrade, reboot and run the installer again.

note

If Incus is already initialised on the machine, the installer leaves it alone and only checks it matches the layout above, printing the commands to fix anything that doesn't. --disk and --pool-size are ignored in that case. It is safe to re-run.

When it finishes it prints the address of the web UI.

2. Create the cluster

Open https://<node-ip>:7443 in a browser. The node uses a self-signed certificate, so the browser warns the first time.

On Set up this node, choose Start a new cluster and fill in:

• Node name — letters, numbers and dashes, starting with a letter, shown in the dashboard (e.g. mini-1).
• Admin password and Confirm password — at least 8 characters. Every node in the cluster uses this password.

Choose Create cluster. You land on the Overview, which shows Your VMs are not protected until a second node joins.

3. Add the second node

Go to Nodes → Add a second node and follow Adding nodes.

Hardware watchdog

If the machine has a hardware watchdog (/dev/watchdog; the installer mentions it when it finds one), let staxmaxd use it. A node that hangs, or that is cut off and cannot confirm its VMs stopped, is then reset by the hardware. Edit /etc/staxmax/staxmaxd.env:

STAXMAXD_OPTS="--listen :7443 --watchdog /dev/watchdog"

then sudo systemctl restart staxmaxd. Without a watchdog, a node that cannot stop its VMs forces a reboot itself. If staxmaxd cannot use the device (it is still missing 30 seconds after staxmaxd starts, or its timeout cannot be set to 10 seconds or less), it runs without it, falls back to that reboot, and raises the alarm A watchdog is missing until you fix the device or remove the option. Make sure the watchdog's driver loads at boot: Ubuntu blocks the kernel's software watchdog (softdog) from loading automatically.

What is installed where

staxmaxd.service	The node daemon (systemctl status staxmaxd, journalctl -u staxmaxd)
/opt/staxmax/current	Link to the running release in /opt/staxmax/releases/; the previous release is kept so an update can be rolled back
/usr/local/bin/staxmax	The admin command — see Command line
/usr/local/sbin/staxmax-uninstall	Removes staxmaxd again — see Uninstalling
/etc/staxmax/staxmaxd.env	Local options for staxmaxd (STAXMAXD_OPTS); updates keep it
/var/lib/staxmax	The node's state
/etc/systemd/logind.conf.d/staxmax-no-sleep.conf	Present if the installer turned sleep off

The full list is in Ports and files.

Uninstalling

sudo staxmax-uninstall stops and removes staxmaxd, its releases and commands. Incus, the VMs, the ZFS pool, /var/lib/staxmax and /etc/staxmax are left untouched, and VMs that were running keep running under Incus; the script prints the commands to remove those too if you no longer need them (if the pool is on the staxmax-pool logical volume, remove that with lvremove after destroying the pool). If the installer turned sleep off, uninstalling turns it back on.

Uninstalling does not take the node out of its cluster: the other nodes still count it as a member. To remove a node for good, retire it on the Nodes page first; see Nodes.