Environment variables
Settings you can pass to the installer, the upgrade check and the warden command.
What this is
The Warden daemon has no environment variables of its own. Everything it needs
is in config.toml. The variables on this page belong to the installer scripts
and to a few standard names the warden command honors.
Set a variable for one command with sudo env, because plain sudo drops most
of your environment:
curl -fsSL https://get.purge.cc | sudo env PURGE_VERSION=v0.44.0 shDownload step (get.sh)
These apply to curl -fsSL https://get.purge.cc | sudo sh. See
Quick start.
| Variable | Default | Effect |
|---|---|---|
PURGE_VERSION | the latest release | Install this release instead, for example v0.44.0. |
PURGE_BASE_URL | the official download site | Download the bundle from another place, such as a mirror. It must start with https://. |
PURGE_INSTALL_DIR | /usr/local/lib/purge-warden | Where the bundle is unpacked. |
PURGE_ALLOW_PACKAGE_OVERLAP | unset | Set to 1 to continue when a purge-warden package is already installed. Read Debian & Ubuntu first. |
PURGE_DRY_RUN | unset | Set to 1 to download and check the bundle, then run the installer in dry-run mode so it changes nothing. |
Installer (install.sh)
Most installer settings are command-line options (--lan-cidr, --upstream,
--listen, --lists, --yes, --dry-run, --upgrade). They are explained in
Quick start. Two timeouts and
NO_COLOR are environment variables:
| Variable | Default | Effect |
|---|---|---|
PURGE_LISTENER_TIMEOUT | 600 | Seconds to wait for the daemon to listen on port 53 after it starts. A first start downloads the blocklists before it listens. If the daemon is still running when the wait ends, the installer exits with status 3: Warden is installed and still loading. |
BLOCK_VERIFY_TIMEOUT_SECS | 600 | Seconds to wait for the final allow and block check. If it fails, the installer exits with status 5. The daemon is running, but it did not pass the check. |
NO_COLOR | unset | Any non-empty value turns off colored installer output. |
Upgrade check
install.sh --upgrade checks the new binary against your configuration, and
asks the running daemon real questions after the swap. These variables change
that check. The defaults suit a normal host. See Upgrade.
| Variable | Default | Effect |
|---|---|---|
WARDEN_UPGRADE_DNS_SERVER | 127.0.0.1 | Address the health check asks. Change it only if the daemon listens on another address. |
WARDEN_UPGRADE_ALLOW_NAME | google.com | A name that must resolve. |
WARDEN_UPGRADE_BLOCK_NAME | doubleclick.net | A name that must be blocked. |
WARDEN_UPGRADE_BLOCK_RESPONSE | zero | How a blocked name must answer: zero, nxdomain, refused or soa_nodata. Set it explicitly whenever you change either name above; the check refuses to start otherwise. |
WARDEN_UPGRADE_HEALTH_CONTRACT | allow_and_block | allow_and_block checks both names. block_all checks only that the block name is blocked, for a host that blocks everything. |
WARDEN_UPGRADE_HEALTH_TIMEOUT_SECS | 300 | How long the check keeps trying before it fails. |
WARDEN_UPGRADE_HEALTH_INTERVAL_SECS | 1 | Seconds between tries. |
WARDEN_UPGRADE_FORWARD_TIMEOUT_SECS | 300 | How long the upgrade waits for the new daemon before it rolls back. |
WARDEN_UPGRADE_RECOVERY_TIMEOUT_SECS | 15 | How long it waits for the old daemon after a rollback. |
WARDEN_UPGRADE_RECOVERY_INTERVAL_SECS | 1 | Seconds between tries after a rollback. |
WARDEN_UPGRADE_MIGRATION_CHOICES | unset | Absolute path to a file with your answers to the questions in the findings step. It must be a regular file, not a symlink, owned by root, not writable by group or others, in a directory that no other user can change. |
WARDEN_UPGRADE_WORK_ROOT | /var/tmp | Where the upgrade keeps its plan and receipt while it runs. It must be an absolute path of real directories owned by root. The upgrade stops with nothing changed if it is not. |
The upgrade script also has overrides for file locations
(WARDEN_UPGRADE_BINARY_DEST, WARDEN_UPGRADE_UNIT_SOURCE,
WARDEN_UPGRADE_UNIT_DEST, WARDEN_UPGRADE_SERVICE,
WARDEN_UPGRADE_BACKUP_SERVICE, WARDEN_UPGRADE_BACKUP_TIMER,
WARDEN_UPGRADE_PROC_ROOT and WARDEN_UPGRADE_STATE_DIR). They exist for the project’s own test harness.
Leave them alone on a real host.
TMPDIR is ignored by the upgrade, on purpose. Use WARDEN_UPGRADE_WORK_ROOT.
The warden command
| Variable | Effect |
|---|---|
EDITOR | The editor warden config edit opens. Without it, vi. Extra arguments are allowed (EDITOR="code --wait"), but shell quoting is not. VISUAL is not read. |
XDG_CONFIG_HOME | Where Warden looks for a per-user purge-warden/config.toml. Without it, ~/.config is used. Root never reads a per-user file. See CLI reference. |