CLI reference

The warden command: global rules, exit codes, and the warden config verbs.

What this is

A reference for warden, the one binary that ships with purge-warden. This page covers the rules that apply to every command, the exit codes a script can rely on, and the warden config verbs that work on the configuration as a whole. Commands that manage one kind of thing (warden device …, warden blocklist …, warden profile …, warden custom-list …) are documented on their own configure pages. Run warden --help or warden <command> --help for the full list on your machine.

Warden does not have a generic config get <key> or config set <key> <value>. You change the configuration in these ways:

• warden config edit opens the configuration in $EDITOR and checks it when you save.
• The per-thing commands (warden device add, warden blocklist set, warden profile …, warden subnet add, warden local-dns add, warden device quiet, warden custom-list … and so on). Each one reloads the running daemon for you.
• warden config restore <archive> puts back a known-good configuration in one operation.

Conventions

• Which user. The files in /etc/purge-warden and /var/lib/purge-warden belong to the purge-warden user, and the daemon only talks to that user. The installed /usr/local/bin/warden is a small wrapper that runs the real binary as that user for you. Run as root or through sudo, it drops to purge-warden. Run as another user with sudo available, it uses sudo -u purge-warden. So warden status and sudo warden config backup both work as written.

• The real binary. The binary is /usr/local/libexec/purge-warden/warden. A few commands need to run as root and refuse the wrapper’s user: warden init and warden config relocate. Call the real binary for them, with sudo.

• Passing --config. An explicit --config <path> skips the wrapper’s routing. The command then runs as whoever you are. It goes before the subcommand: warden --config /path/config.toml config lint. The wrapper also runs the binary as you, without switching user, when the current directory holds a config.toml.

• Where the configuration is found. With no --config, Warden uses the first of these that it can open:

  1. ./config.toml
  2. $XDG_CONFIG_HOME/purge-warden/config.toml, or ~/.config/purge-warden/config.toml when $XDG_CONFIG_HOME is not set
  3. /etc/purge-warden/config.toml
  4. /var/lib/purge-warden/config.toml (the layout of hosts installed before 0.44.0)

  When root runs warden without --config, the first two are skipped, so a file planted in a shared directory cannot be picked up. The systemd units pass no --config either: they use the same search, effectively /etc and then /var/lib.

• Safe writes. Every write goes through a temporary file in the same directory, a check, then a rename. If the check fails, the live file is unchanged.

• Reloading. The per-thing commands reload the daemon on their own. warden config edit does not; run warden reload or systemctl reload purge-warden after it.

• Output. Most read commands print text or tables. --json exists on some of them (status, device list, stats …, and logs --format json), but not on any warden config command.

Exit codes

Every warden command uses the same exit codes, so a script can branch on them without reading the output.

The custom-list and profile mount commands use 3 for a conflict (for example a revision mismatch or a list that is still mounted) and add their own codes 4 (failed before the commit, or the reply was lost) and 5 (committed but not active yet). See their pages.

Retired verbs

Some verbs from older releases still appear in --help. They are retired in 0.44.0. They accept their old arguments, write nothing, and point you to the replacement. Do not use them in scripts.

Use warden custom-list to write the rules and warden profile mount to attach the list. See Custom rules.

warden config

The configuration commands live under warden config. There are eight:

warden config show

warden config show [--resolved] [--annotate] [--section <name>]

Prints the configuration as merged TOML.

Without --resolved, the output is TOML. With --resolved, it is a text report. For machine use, pipe the plain TOML through a TOML tool such as tomlq or yq -p toml.

warden config edit

warden config edit

Opens a private copy of the configuration in $EDITOR (vi if it is not set). The live file is never open in the editor. When you save and quit, Warden checks the copy. The live configuration changes only if the copy is valid.

If the copy is refused, or the editor exits with an error, the live configuration stays as it was, the copy is kept, and the command prints its path. On a cluster secondary, a change to the policy that comes from the primary is refused; make that change on the primary.

This command does not reload the daemon. Chain it with a reload:

sudo warden config edit && sudo systemctl reload purge-warden

warden config lint

warden config lint [--strict]

Loads and checks the configuration without touching the running daemon. Warnings are printed to stderr. By default they do not fail the command, because a warning means the daemon still starts and serves.

Safe to gate a deploy on: warden config lint && systemctl reload purge-warden.

warden config diff

warden config diff <other>

Compares the live configuration with <other>, a path to another configuration file. “They differ” is a successful answer, so it has its own exit code:

warden config backup

warden config backup [--out <dir> | --auto | --reset-auto-failure]

Writes config-<UTC-timestamp>.tar.gz to [backup] dir, or to a backups/ directory next to the master when that is not set. With --out <dir>, it writes there instead. When the configuration does not load, the directory follows the rule in Where archives go. --auto and --reset-auto-failure are for the scheduled backup. The three flags exclude one another.

Exit 0 on success, an automatic run that was not due, or an --auto run that skipped a configuration that does not load. Exit 75 if another backup is running.

For what is in an archive, the schedule and limits, see Backup & restore.

warden config restore

warden config restore <archive>
warden config restore --list
warden config restore --latest

Checks the archive, then replaces the live configuration in one transaction and asks the daemon to reload. It never changes the node’s cluster membership. It refuses an archive from Warden 0.41 or earlier.

Restore keeps no copy of the current configuration: if you may want it back, run warden config backup first. See Backup & restore for the steps and the refusals.

warden config render-default

warden config render-default

Prints the built-in default configuration to stdout. It needs no root, writes no file, and ignores which configuration Warden would otherwise use. Useful for comparing your configuration with the shipped default:

warden config render-default > /tmp/default.toml
warden config diff /tmp/default.toml

warden config relocate

sudo /usr/local/libexec/purge-warden/warden config relocate [--dry-run] [--reverse]

Moves the configuration set from /var/lib/purge-warden to /etc/purge-warden. It runs offline, as root, with the real binary, and it refuses --config. --dry-run runs every check and moves nothing. --reverse moves the set back, or rolls back an incomplete forward run.

The full runbook, with the refusals, is in Upgrade.

warden reload

warden reload

Asks the running daemon, over its authenticated control socket, to reload its configuration and lists. Use it after warden config edit. Here the reload is the whole operation, so a daemon that is not running is a failure.

warden migrate

warden migrate v4-to-v5 is the schema 4 to schema 5 migration. The upgrade runs it for you inside its transaction. The manual form exists only as a recovery tool; see Upgrade.

See also

• Backup & restore: the operational guide for config backup and config restore.
• Upgrade: install.sh --upgrade and warden config relocate.
• Basic configuration: where the configuration lives, and how to validate and reload it.
• File paths: where Warden reads and writes on disk.
• Environment variables: $EDITOR, $XDG_CONFIG_HOME and the installer settings.