Ports and files
Ports
| Port | Direction | Used for |
|---|---|---|
| 7443/tcp | browsers → node, node ↔ node | The web UI, the API, heartbeats and everything else between nodes (HTTPS with a self-signed certificate that each node pins for the others) |
| 8443/tcp | node ↔ node | Incus API, used to copy VMs between nodes (replication, moves, ISOs and saved images) |
7443/udp (IPv6 link-local multicast to ff02::5354:4158) | node ↔ node, direct cable only | Beacons on spare wired ports that find a direct cable between nodes. They never leave the cable. This port stays 7443 even if you change --listen. |
| ICMP / ARP | node → LAN | Pinging the tiebreaker (router, two-node clusters only) and checking whether a failed node or its VMs still answer before a takeover |
If ufw is active when you install, the installer opens 7443/tcp, 8443/tcp and 7443/udp. With any other firewall, open them between the nodes yourself; the UI port also needs to be reachable from wherever you manage the cluster. Nodes installed with version 0.1.1 or earlier did not get the 7443/udp rule (updates do not change the firewall): if you use a direct cable, run sudo ufw allow 7443/udp on them, or the nodes never find the cable.
Outbound
| Destination | When |
|---|---|
Ubuntu/Debian mirrors, pkgs.zabbly.com | Installing (packages, Incus) |
images.linuxcontainers.org | Browsing and downloading VM images from the catalog |
| Any URL you give | Downloading an ISO from a URL into the ISO library, or the files of a VM to import |
updates.harnessautomation.com | Checking for and downloading updates (optional; releases can be uploaded instead), and activating and renewing a license (optional; a site without internet uses license files, see License) |
| Your SMTP server, the Telnyx API | Sending alarm emails and text messages, if configured |
| A Shelly smart plug on the LAN | Switching a failed node off before takeover, if configured |
Files on a node
| Path | What it is |
|---|---|
/etc/staxmax/staxmaxd.env | Local options for staxmaxd (STAXMAXD_OPTS). Updates keep it. |
/etc/staxmax/keyring.json | The signing keys this node trusts for releases. A release whose signature doesn't verify is never installed. |
/etc/systemd/system/staxmaxd.service | The unit. It belongs to the release and is replaced on every update, so put local options in staxmaxd.env, not here or in a drop-in. |
/opt/staxmax/current | Link to the release that is running, in /opt/staxmax/releases/<version>/. /opt/staxmax/previous links to the one a rollback goes back to. Each release includes license-keyring.json, the key license files must be signed with. |
/usr/local/bin/staxmax, /usr/local/bin/staxmaxd | The admin command and the daemon (links into the current release) |
/usr/local/sbin/staxmax-update | Installs, checks and rolls back releases on this node; see Command line |
/usr/local/sbin/staxmax-uninstall | Removes staxmaxd, leaving Incus, VMs and the pool |
/etc/systemd/logind.conf.d/staxmax-no-sleep.conf | Written if the installer turned sleep off (it also masks sleep.target, suspend.target, hibernate.target, hybrid-sleep.target and suspend-then-hibernate.target). staxmax-uninstall removes it and unmasks them. |
/var/lib/staxmax/ | The node's state (see below) |
/var/lib/staxmax-import/ | Where files of a VM being imported, and disks being built for Download as OVA, wait while they are converted. It is the ZFS dataset <pool>/staxmax-import on the storage pool, created the first time it is needed and emptied when staxmaxd restarts. staxmax-uninstall leaves it. |
/var/log/staxmax/ | Logs of each install, update and rollback. staxmaxd itself logs to the journal (journalctl -u staxmaxd). |
| The backup storage (Settings → Backups) | Nightly exports, one file per VM per night: <vm>/<vm>_<time>.tar.gz. A Folder is the same path on every node; a USB drive or a share is mounted by staxmax at /mnt/staxmax/backup (on every node for a share, on the drive's node for a USB drive). |
/etc/systemd/system/mnt-staxmax-backup.mount | The mount of the backup storage, written by staxmax (it replaces your changes). An SMB share's user and password are in /etc/staxmax/backup-smb.credentials, readable by root only. |
| The offsite bucket or SFTP folder (Settings → Offsite backups) | Encrypted exports: <folder>/<cluster ID>/<vm>/<vm>_<time>.tar.gz.enc. Decrypt one by hand with staxmax decrypt-backup; see Command line. |
State directory: /var/lib/staxmax
| File | What it is |
|---|---|
config.json | This node's identity, the cluster members, the cluster settings, the admin password hash and the cluster secret. Readable by root only; treat it as a secret. |
state.json | The replicated VM table |
tls.crt, tls.key | This node's certificate, pinned by the other nodes. Don't replace or delete them: a new certificate is no longer accepted by the other nodes. |
fenced.json | Present while this node has fenced itself; keeps it fenced across restarts and reboots |
alarms.json | Which alarm notifications have been sent |
password-reset.json | Left by staxmax reset-password until staxmaxd applies it |
update-rollout.json | The cluster update this node is coordinating, so it can finish the record after its own restart |
boot_id | The boot staxmaxd last started in, so it can tell a restart of staxmaxd from a reboot |
updates/ | This node's identity with the release server |
updates/license.json, updates/license-state.json | This node's current license, as last issued by the license server or imported from a file, and what it must remember across restarts. |
updates/releases/ | Kept installers (.run + .sig), handed to other nodes in an update and to machines that join |
incus-client/ | Credentials staxmaxd uses to talk to the other nodes' Incus |
danger
Deleting /var/lib/staxmax turns the machine back into a fresh, unconfigured node. Do that only to a node the cluster has already removed (see Troubleshooting), never to a live member.
Incus objects staxmax creates
| Name | What it is |
|---|---|
Storage pool stax | ZFS pool for VM disks, ISOs and images (name chosen at install; the same on every node). Without --disk it lives in a file under /var/lib/incus/disks/. |
Network lan | macvlan network on the LAN interface that VMs attach to |
Networks lan-v<n> | One per VLAN in use, made on each node from its own lan |
Snapshots named stax-… | staxmax's own replication snapshots; not shown in the UI and not to be touched |
ZFS dataset <pool>/staxmax-import | Mounted at /var/lib/staxmax-import; see above. Not an Incus object, but on the same pool. |
Instances named …-orphan-<time> | A preserved copy of a VM that lost ownership after a failover; never deleted automatically |
Every VM has Incus autostart turned off: staxmaxd decides what runs where.