Build from source

Under review — wording may still change.

Compile Warden yourself and install it with the same installer the bundle uses.

Most people should use the quick start. It is faster and it needs no compiler. Build from source when your machine is not x86_64 (the bundle is published for x86_64 only), when you want to turn on an optional feature, or when you want to read what you run.

You compile the binary, then run scripts/install.sh from the same checkout. The installer does everything the bundle install does: it creates the purge-warden user, writes /etc/purge-warden/config.toml, installs the systemd units, starts the service and checks that it blocks. You do not run warden init yourself.

Requirements

A Linux distribution with systemd. The installer supports Debian 12 or newer, Ubuntu 22.04 or newer, Fedora 40 or newer, and RHEL 9 and rebuilds. On a Raspberry Pi with a 64-bit Raspberry Pi OS, build as Building for ARM (aarch64) describes. A Raspberry Pi runs Warden only with a small set of lists. On any other distribution it stops, and you install the files by hand as BUILDING.md describes.
Root, or sudo.
About 2 GB of free disk space for the build, and at least 50 MB for the binary.
Rust 1.94 or newer.

Because you build on your own machine, the binary links the glibc that machine already has. There is no minimum glibc version to meet.

1. Install build tools

You need a C compiler, make, pkg-config, git, cmake and a Rust toolchain. Warden’s TLS stack is pure Rust (rustls), so there is no OpenSSL package to install.

bash
# Fedora / RHEL
sudo dnf install gcc gcc-c++ make cmake git curl pkgconf-pkg-config

# Debian / Ubuntu
sudo apt install build-essential pkg-config git curl cmake

Install Rust with rustup if you do not have it:

bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source ~/.cargo/env

2. Get the source

bash
git clone https://github.com/purge-cc/Warden
cd Warden

Run every command below from this directory. The installer finds its support files, such as the systemd units, relative to the checkout.

3. Build

bash

cargo build --release

This produces target/release/warden, the daemon and the CLI in one executable.

Warning

The release profile is tuned for a small, fast binary (fat LTO, a single codegen unit). The build is slow and needs a fair amount of free RAM, so expect several minutes. On a small machine, close other work first.

The cluster feature is on by default. Two more features are off by default. Turn one on at build time if you need it, for example cargo build --release --features dnssec. The other is doq.

4. Install

Run the installer from the checkout. When it finds target/release/warden it uses it:

bash

sudo ./scripts/install.sh

To use a binary from another path, name it:

bash

sudo ./scripts/install.sh --binary /path/to/warden

To let the installer do step 1 and 3 for you, use --build-from-source. It installs the build tools, installs rustup if there is no cargo, and runs cargo build --release in the checkout:

bash

sudo ./scripts/install.sh --build-from-source

The installer asks you to confirm before it changes anything. The options are the same as for the bundle install: --lan-cidr, --upstream, --listen, --lists, --yes and --dry-run. Quick start explains each one, and what the installer does with port 53, the firewall and SELinux.

Do not use make install

make install is for a first install only, and it skips the configuration check. make upgrade run from a 0.43.0 or older tree overwrites the warden wrapper and skips the check. Use scripts/install.sh for installs and scripts/install.sh --upgrade for upgrades.

5. Verify

verify

$ dig @127.0.0.1 doubleclick.net # → 0.0.0.0 (blocked) $ dig @127.0.0.1 google.com # → real address (allowed)

The installer runs these two checks and exits with status 5 if either fails. On first start Warden downloads its blocklists before it answers, so allow a few minutes on a slow link. If it is still loading when the installer’s wait ends, the installer skips the checks and exits with status 3: see Installer exit statuses.

Point your router’s or devices’ DNS at this machine’s IP to protect the whole network. See the quick start.

Upgrading

Pull the latest source, rebuild, and run the installer in upgrade mode:

bash
git pull
cargo build --release
sudo ./scripts/install.sh --upgrade

The upgrade checks your configuration with the new binary, migrates a 0.41 configuration, replaces the binary and the units, and rolls back if the new version fails its check. Do not run warden init again. See Upgrade.

Removing

bash
sudo ./scripts/uninstall.sh            # keep config and data
sudo ./scripts/uninstall.sh --purge    # also delete /etc/purge-warden, /var/lib/purge-warden and the user

Without --purge, your configuration is kept in /etc/purge-warden and your lists and statistics in /var/lib/purge-warden. A host installed before 0.43.0 keeps its configuration in /var/lib/purge-warden too. The next install adopts the kept configuration: see Reinstall over a kept configuration. While a configuration change is unfinished, an uninstall without --purge refuses and removes nothing; with --purge it goes ahead. The quick start explains it.

The uninstaller asks you to confirm on your terminal. With no terminal (a script, or ssh without a tty), it stops with exit code 1 and removes nothing unless you add --yes.

Building for ARM (aarch64)

The bundle is for x86_64 only, so an aarch64 machine such as a 64-bit Raspberry Pi builds from source. The installer runs on aarch64 with --build-from-source or with --binary pointing at your build. The default lists need about 700 MB of RAM and about 1.4 GB at a list update, so a Raspberry Pi runs Warden only with a small set of lists: see Memory and list size.

Cross-compiling for aarch64 is best-effort and untested on real hardware. BUILDING.md in the repository describes the aarch64-unknown-linux-musl route. The shipped systemd unit filters system calls, and that filter kills a static musl binary, so a musl build needs the unit’s hardening relaxed.