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 reloadrestarts Grafana.cloud capturecommits and pushes. On a privatecloud host it startsprivatecloud-capture.servicethrough sudo.cloud driftstartsprivatecloud-drift.servicethrough sudo on a privatecloud host.images checkstartsseawall-updates.servicethrough sudo where its timer is installed.proxy loginmakes an NPM user and stores its token.proxy aop loginstores a Cloudflare token,proxy aop renewswaps the client certificate at Cloudflare andproxy aop refreshrewrites CrowdSec's parser and signals CrowdSec. All three refuse--yes.proxy aop DOMAIN --guidedmakes 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.--yesis ignored.proxy migrate --resumecarries on a move to Traefik, and--certshands the hosts still on NPM's certificates to Traefik's resolver.stack rename --resumecarries on a rename.crowdsec hub --refreshfetches the hub's index into CrowdSec.jobs cancelstops a running job or takes back a queued one's confirm.stray ignorewrites the config,stack savesaves a copy of the stack, andstack editopens the file (its--yesdeploys the edit).status,tuiand the facts timer bring seawall's alert rules to the installed build's once per build, and restart Grafana.- The hidden
updates applyis the night's run (seawall-autoupdate.serviceonly).
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 code | Means |
|---|---|
0 | The command ran. |
1 | The 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). |
2 | Any other error. A stack that doesn't settle counts as one. |
130 | Stopped 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>.
| Change | Why it's severe |
|---|---|
stack update of a database to a newer major | A database major migrates its data files, and a rollback can't read them back |
stack migrate | It stops the stack and removes it from one manager, then starts it in the other |
stack move | It takes the stack down and moves its folder |
host upgrade of Docker Engine | Upgrading the Docker engine restarts every container |
host upgrade of Docker Engine within its minor, live restore on | Upgrading the Docker engine restarts it; live restore keeps the containers running |
stack reconcile --take deployed over local edits | The disk copy's own edits are replaced by what is deployed (a backup is kept) |
backup restore | The 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 prune | It's gone for good: no backup reads what no container uses |
container shell --root | A 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 read | A 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 /48 | The 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 folders | Its bind folders become volumes on the owner's runtime, and --back can't bring them back into the folders yet |
init --only userland-proxy | IPv6 visitors to a container without IPv6 are lost, as only docker-proxy carried them over |
networks rename | Everything 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 --keys | Each stack on it is recreated |
stack rename | The stack is down while its data is copied, and what names its containers (routes, silences, dashboards) has to follow |
stack remove | The stack stops and goes from its manager, with its own networks, its ports and its routes |
align with severe steps | The steps marked severe go ahead with this one name, without asking each |
stray rm of a Git checkout or another user's files | The folder moves into seawall's trash, which only you can open, and a copy is kept |
host fix lock | The account's password stops working |
host fix expire | The account can't log in at all, keys included, and its cron jobs stop |
proxy migrate | Every site is down for the seconds the ports change hands, and a failure after that puts the old proxy back |
host reclaim clean build-cache | Cache only: the next build makes it again |
host fix sshd | A 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 setting | The 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 container | What'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 line | It starts a container the host's root is handed to |
grafana rules adopt | This 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 open | What 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 down | A 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.