How commands work

A change is a dry run first, except the commands below that act at once. This page covers --yes, exit codes, names and the config file.

Dry runs and --yes

seawall stack update nextcloud         # dry run, changes nothing
seawall stack update nextcloud --yes   # makes the change

A command that changes something prints its plan and stops. Add --yes to make the change. These act at once. None needs --yes:

  • grafana reload restarts Grafana.
  • cloud capture commits and pushes. On a privatecloud host it starts privatecloud-capture.service through sudo.
  • cloud drift starts privatecloud-drift.service through sudo on a privatecloud host.
  • images check starts seawall-updates.service through sudo where its timer is installed.
  • proxy login makes an NPM user and stores its token.
  • proxy aop login stores a Cloudflare token, proxy aop renew swaps the client certificate at Cloudflare and proxy aop refresh rewrites CrowdSec's parser and signals CrowdSec. All three refuse --yes.
  • proxy aop DOMAIN --guided makes a client certificate and a CA key. On a renewal it also rewrites Traefik's CA files and TLS option and redeploys Traefik if its compose changes. --yes is ignored.
  • proxy migrate --resume carries on a move to Traefik, and --certs hands the hosts still on NPM's certificates to Traefik's resolver.
  • stack rename --resume carries on a rename.
  • crowdsec hub --refresh fetches the hub's index into CrowdSec.
  • jobs cancel stops a running job or takes back a queued one's confirm.
  • stray ignore writes the config, stack save saves a copy of the stack, and stack edit opens the file (its --yes deploys the edit).
  • status, tui and the facts timer bring seawall's alert rules to the installed build's once per build, and restart Grafana.
  • The hidden updates apply is the night's run (seawall-autoupdate.service only).

On a terminal two commands ask before they act. init shows its plan and asks "Carry out these steps? [y/N]". The wizard, seawall new, shows the compose file and asks "Write these files? [y/N]". Off a terminal init asks nothing and takes --yes as every other command does. The wizard needs a terminal.

Exit codeMeans
0The command ran.
1The command ran and said what failed, such as backup run or backup restore-test where part of it failed, a change refused by a stack or host lock, or a stop or start whose job failed. With the global --check a report found something (drift, lint errors, findings).
2Any other error. A stack that doesn't settle counts as one.
130Stopped at a question or by Ctrl+C.
seawall --check security || echo "findings"

Some changes are severe. They can't be undone or reach past one stack. They need what they act on typed (a stack, an account, a port) as well as --yes. On a terminal you type the name. Without one, pass --confirm <name>.

ChangeWhy it's severe
stack update of a database to a newer majorA database major migrates its data files, and a rollback can't read them back
stack migrateIt stops the stack and removes it from one manager, then starts it in the other
stack moveIt takes the stack down and moves its folder
host upgrade of Docker EngineUpgrading the Docker engine restarts every container
host upgrade of Docker Engine within its minor, live restore onUpgrading the Docker engine restarts it; live restore keeps the containers running
stack reconcile --take deployed over local editsThe disk copy's own edits are replaced by what is deployed (a backup is kept)
backup restoreThe stack's volumes and folders are replaced by the snapshot's; what's there now is kept aside, as the plan says
volumes rm, networks rm and images pruneIt's gone for good: no backup reads what no container uses
container shell --rootA root shell owns the container and its data, and undoes the work of running it as its own user
cloud.host_files naming files only root can readA file only root can read may hold a secret: it's copied for your group and kept in the config repo
proxy route add to something root on this host, open to more than one /16 or /48The route leads to something root on this host, and lets in more of the internet than one /16 or /48
stack runtime --to for a stack with bind foldersIts bind folders become volumes on the owner's runtime, and --back can't bring them back into the folders yet
init --only userland-proxyIPv6 visitors to a container without IPv6 are lost, as only docker-proxy carried them over
networks renameEverything on the network is unreachable for a few seconds, the proxy's backends included, and once the old network is gone no stack can go back to it
networks rename --keysEach stack on it is recreated
stack renameThe stack is down while its data is copied, and what names its containers (routes, silences, dashboards) has to follow
stack removeThe stack stops and goes from its manager, with its own networks, its ports and its routes
align with severe stepsThe steps marked severe go ahead with this one name, without asking each
stray rm of a Git checkout or another user's filesThe folder moves into seawall's trash, which only you can open, and a copy is kept
host fix lockThe account's password stops working
host fix expireThe account can't log in at all, keys included, and its cron jobs stop
proxy migrateEvery site is down for the seconds the ports change hands, and a failure after that puts the old proxy back
host reclaim clean build-cacheCache only: the next build makes it again
host fix sshdA setting that keeps your login out locks you out; it undoes itself in 5 minutes unless a second login keeps it
stack env set of a database's own settingThe database keeps its own password: only the app's changes, so the app may no longer log in
ports add of an open port or a privileged containerWhat's accepted stays as it is, and its alert stops
stack start, deploy, update or stray adopt --start of a root grant without its allow lineIt starts a container the host's root is handed to
grafana rules adoptThis host's copies of seawall's alert rules are replaced at once, their own queries, timings and severities with them
cloud sync with a security-set file changed or a change alert openWhat changed outside seawall becomes the repo's: drift stops naming it, and a restore puts it back
config set of a setting that turns a defence downA defence goes down with it: what it guarded stays open until the setting is put back

A stack can be named by its manager's name (Portainer's stack or the Compose project), its folder under the stacks folder or the folder's last part. Every change goes to the journal with the tag seawall. seawall audit lists them.

Output is plain text when piped or when NO_COLOR is set. SEAWALL_COLOR=always forces colour.

Configuration

seawall config           # the settings screen
seawall config --print   # every value in force, as TOML

Settings live in ~/.config/seawall/seawall.toml. The file holds only values that differ from the defaults. contrib/seawall.example.toml in the repository lists every key with its default. On the screen enter edits a value, d restores its default and s saves.

manager.default sets whether new stacks run through Compose or Portainer. With none written, Compose runs them. Where a Portainer container is here and the config writes none, seawall asks Portainer nothing, reads no stack and says seawall config --at manager.default sets it. A running stack's manager is read from the host (see Who runs a stack). [manager.stacks] names the manager for one stack and overrides that reading. The commands are the same either way. A Compose stack keeps its secrets in a 0600 .env beside its compose file.