File paths
Where Warden puts its program, its configuration and its data.
What this is
A map of the files a Warden install creates. The rule is simple: the
configuration lives in /etc/purge-warden, and the state (lists, audit
log, backups, the control token) lives in /var/lib/purge-warden. Runtime files
live in /run/purge-warden.
A host installed before 0.44.0 keeps its configuration in
/var/lib/purge-warden until you run warden config relocate. Both layouts
are listed below. See Upgrade.
Program files
| Path | What it is |
|---|---|
/usr/local/bin/warden | A small wrapper script. It runs the real binary as the purge-warden user, unless you pass --config or the current directory holds a config.toml. This is the command you type. |
/usr/local/libexec/purge-warden/warden | The real binary: daemon and command line in one. The systemd units run this file. |
/usr/local/lib/purge-warden/ | The unpacked bundle: the installer scripts, the systemd unit files and the uninstaller. PURGE_INSTALL_DIR changes it. |
/etc/systemd/system/purge-warden.service | The daemon unit. |
/etc/systemd/system/purge-warden-backup.service | The backup job. |
/etc/systemd/system/purge-warden-backup.timer | The backup schedule. |
See systemd service.
Configuration: /etc/purge-warden
The directory belongs to the purge-warden user. This is the layout of a
fresh install of 0.44.0 or later.
| Path | What it is |
|---|---|
config.toml | The master configuration, mode 0640. |
secrets.toml | Secrets, next to the master. It must be mode 0600, or Warden refuses to start. |
packs/<id>.txt | Custom lists you create with warden custom-list. |
| Include files | Any file the master includes. Warden backs up the whole include graph. |
.warden-* | Warden’s own bookkeeping, such as .warden-node-corpus (Warden Nodes). Do not edit or delete these. Backups skip them. |
Warden finds the master in this order and uses the first one it can open:
./config.toml$XDG_CONFIG_HOME/purge-warden/config.toml, or~/.config/purge-warden/config.toml/etc/purge-warden/config.toml/var/lib/purge-warden/config.toml
Root skips the first two. An explicit --config <path> overrides all four.
State: /var/lib/purge-warden
State stays here in every layout. The directory has mode 0750.
| Path | What it is |
|---|---|
audit/audit.log | The append-only audit log, mode 0640. Read it with warden audit tail. |
backups/ | Config archives, config-<UTC-timestamp>.tar.gz. The directory is set by [backup] dir. |
backups/.auto_state, backups/.lock | The automatic backup’s state and lock. See Backup & restore. |
lists/ | Downloaded blocklists. |
query.log, query.log.YYYY-MM-DD | The query log and its rotated days. The log rotates at UTC midnight, and a day over query_log_max_size_mb gets extra query.log.YYYY-MM-DD.N files. Days older than retention_days (default 7) are deleted. See how much the log keeps. |
.warden-relocate.json, .warden-relocate.done.json | The receipt of warden config relocate. The first exists while a move is unfinished, the second after it completed. |
token | The control token the warden command uses to talk to the daemon. |
config.toml and packs/ | Only on a host that has not been relocated yet. These belong to the configuration, not to the state. |
The query log location is set by query_log_path in the [tracking] section.
The default, ./query.log, and any other relative path are taken relative to
this directory. An absolute path is used as written.
Runtime: /run/purge-warden
systemd creates this directory (mode 0755) when the service starts and
removes it when the service stops.
| Path | What it is |
|---|---|
control.sock | The control socket. The warden command and the dashboard talk to the daemon through it. |
purge-warden.pid | The daemon’s process ID. |
Installer files
| Path | What it is |
|---|---|
/var/log/purge-warden-install-<date>-<time>.log | The installer’s log. A new file for every run. |
/var/tmp/purge-warden-* | Temporary plan, receipt and snapshot directories of install.sh --upgrade. They exist while an upgrade runs, and stay after a killed one. WARDEN_UPGRADE_WORK_ROOT changes the parent. |
/usr/local/libexec/purge-warden/warden.s6-old, /etc/systemd/system/purge-warden.service.s6-old | Copies of the old binary and unit, kept while an upgrade swaps files. If they remain after an upgrade, see Troubleshooting. |
.warden-migration/ in the config directory | A fence. It exists while a schema migration is in progress. See Troubleshooting. |