Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

No config file: the machines, flags, and environment variables.

Machines

sshwarm takes the first of:

  1. --hosts <file> or --flake <dir>
  2. SSHWARM_HOSTS or SSHWARM_FLAKE
  3. $XDG_CONFIG_HOME/sshwarm/hosts.toml, by default ~/.config/sshwarm/hosts.toml

A hosts file and a flake together are an error.

Hosts file

[[host]]
name = "web-1"               # required: sshwarm's name for it
host = "web-1.example.org"   # default: name
user = "deploy"              # default: ~/.ssh/config's, else yours
key  = "~/.ssh/web"          # default: ~/.ssh/config's, or your agent

ssh looks host (or name) up in ~/.ssh/config for anything else: port, jump host… Unknown keys are an error.

Nix flake

sshwarm --flake ./nix

Reads the flake’s deploy.nodes, as deploy-rs does: each node’s hostname, and its sshUser and sshOpts, or deploy’s. Needs nix.

Flags

FlagVariableDefault
--hosts <file>SSHWARM_HOSTShosts file
--flake <dir>SSHWARM_FLAKEflake with deploy.nodes
--timeout <duration>SSHWARM_TIMEOUT20sprobe timeout, per machine
--refresh <duration>SSHWARM_REFRESH30show often the browser probes
--read-onlySSHWARM_READ_ONLYoffno actions, no shells

A flag beats its variable. SSHWARM_READ_ONLY is on unless empty, 0 or false.

Commands: status [--format text|json] [machine...], and probe <machine>, which prints a machine’s raw probe output. sshwarm <command> --help for more.

Requirements

Each machine runs Linux with systemd and bash. ssh must log in without a prompt: a key or an agent, and a known host key.

Tothe ssh user
see the machine and its unitsneeds nothing more
read logsis root, or in systemd-journal
see, start and stop compose stacks and containersruns docker: docker group, rootless, or passwordless sudo
start and stop units, rebootis root, or runs systemctl with passwordless sudo

Pending reboots are detected on NixOS, Debian, Ubuntu, Fedora, RHEL and Arch. On NixOS, sshwarm also shows the last deploy and its git revision, if the flake sets system.configurationRevision.

Connections

The browser keeps one ssh connection per machine (ControlMaster), its socket in ~/.ssh, closed a minute after you quit. It leaves ssh alone if your ssh config sets ControlPath or ControlMaster for the machine, or ~/.ssh isn’t writable.