Basic configuration

Under review — wording may still change.

Seven steps from a freshly installed daemon to a network filtered the way you want it.

Warden is a single binary configured by one plain-text TOML file. You can edit that file by hand, but you rarely need to: every step below has a command and a screen in the terminal interface, and both write the same file.

Follow the steps in order the first time. Each one leaves you with something that works, so you can stop after any of them and come back later.

The base path

#	Step	What you get
1	Initialize	A system user, the directories, and a first `config.toml` with three lists already subscribed
2	Import lists	More domain feeds, from the purge.cc catalog or any URL you trust
3	Create profiles	The policies themselves — which lists apply, and how
4	Create labels	A small vocabulary that keeps your device inventory consistent
5	Manage devices	Every machine named, and pointed at the profile it deserves
6	Custom rules	Your own allow and deny rules, in Custom Lists you mount on profiles
7	Map subnets	A whole network segment on one profile, without naming each device

Steps 3, 5 and 7 are walkthroughs. When you want every field, every default and the full precedence chain, the entity pages are the reference behind them.

Where Warden reads the config

Without --config, Warden probes a fixed list and takes the first file it can actually open:

./config.toml — the working directory. Handy in development.
$XDG_CONFIG_HOME/purge-warden/config.toml, or $HOME/.config/purge-warden/config.toml.
/etc/purge-warden/config.toml — the standard system path.
/var/lib/purge-warden/config.toml — the legacy layout from before warden config relocate. Last resort; a fresh install never uses it.

Running as root changes the search

When the effective user is root, Warden searches only the two system paths and ignores both the working directory and your home directory. A ./config.toml sitting in whatever directory you happened to run sudo from is skipped with a notice on purpose: it is writable by a non-root user, and loading it would let anyone who can drop a file there repoint your upstream resolver. An explicit --config always wins.

See which file a command resolves, and the file and line each entry came from:

bash

warden config show --annotate

The service starts with no --config, so it runs the same search as the purge-warden user.

Before you reload

Validate the file, then reload. A config that fails validation is rejected and the previous one keeps serving traffic.

bash

warden config lint
warden reload

Changes you make through a command — warden device add, warden profile set, warden lists add — reload the daemon for you. There is nothing further to run.

Beyond the base path

Schedules, SafeSearch, local DNS records, upstream resolvers and the anti-bypass settings are being rewritten against the current schema and are out of the sidebar while that happens. Until they return, warden config show prints the merged config file, and warden config edit opens it in your editor and validates what you save. Run warden reload afterwards to apply it.