Filtering process

Warden’s configuration has seven nouns: blocklists, admin rules, profiles, devices, groups, subnets, schedules. Once you see how they reference each other and in what order the resolver consults them, the rest of the documentation reads as variations on a single theme. This page is that theme.

How a query gets resolved

For each query, Warden runs a single cascade in two phases: first picks the profile, then asks that profile what to do with the domain.

Phase 1 — which profile applies? — walks five levels. The first match wins. Phase 2 — what does that profile say about this domain? — walks the rule layers inside the chosen profile.

Phase 1 — which profile applies? · first match wins

L2 Schedule active for this device? [[schedules]] yes → profile
L1 Client IP/MAC has a device row? [[devices]] yes → profile
L3 Device belongs to a matching group? [[groups]] yes → profile
L4 Client IP inside a subnet CIDR? [[subnets]] yes → profile
L5 default_profile set? [server] yes → profile
REFUSEDhardcoded — ignores any block_response

Phase 2 — what does that profile say about the domain?

R1 Device allow_rules hit? yes → Allow
R2 Device deny_rules hit? yes → Block
R3 Profile admin-rule allow hit? yes → Allow
R4 Profile admin-rule deny hit? yes → Block
R5 Domain in any subscribed blocklist? [[blocklists]] yes → Block
Allowno layer objected

Pin	Why
Schedule beats the device’s own profile	L2 is checked before L1. A schedule on a device that already has a profile would do nothing otherwise.
Schedules need a device row	A schedule is keyed to a device id (or a group id, via `device.groups`). A client resolved at L4 (subnet) or L5 (default) cannot trigger one. Time-bounded behaviour for a device-less client is a subnet with its own profile.
Groups do not take raw IPs	A `[[groups]]` row references device ids only. A client without a device row never reaches L3. “Kids’ VLAN at 8pm” is usually subnet → strict profile, not a group plus a schedule.
Longest prefix, not file order	When two `[[subnets]]` overlap, the more specific CIDR wins. The optional `priority` field is informational.
`override_profile_deny` is a narrow gate	A device allow can override a blocklist hit with no flag. The flag is required only when the device allow conflicts with a profile admin-rule deny on the same domain. The validator refuses that write unless `override_profile_deny = true`.

Strict-by-default fallback

If no level matches and default_profile is unset, the answer is REFUSED — never a permissive default.

Leave default_profile unset and any client that matches no device, group, or subnet drops to L5 and is refused. The RCODE=REFUSED at L5 is hardcoded — it ignores any profile’s block_response.

Set default_profile only when you want a catch-all (for example every guest gets an ads-blocked profile).

The cast

Profiles are the centre. Everything else either points at a profile or is referenced by one.

A profile is a bundle of policy: which blocklists to subscribe to, which admin rules to attach, what to answer with when a query is blocked. Devices, groups, and subnets are three ways of saying “this client gets that profile”. Schedules are a time-bounded override that swaps in a different profile. Blocklists and admin rules are the raw policy that profiles compose.

Entity	Identified by	Points to	Referenced by
`[profiles.id]`	id	`blocklists`, `admin_rules`	devices, groups, subnets, schedules, `server.default_profile`
`[[devices]]`	`ip` and/or `mac`	`profile`, `groups`, `allow_rules`, `deny_rules`	groups (via id), schedules
`[[groups]]`	id, `priority`	`profile`, `devices`	devices (via `device.groups`), schedules
`[[subnets]]`	id, `cidrs`	`profile`	—
`[[schedules]]`	`target_type` + `target_id`	a device or a group, `profile`	—
`[[blocklists]]`	id	external feed URL	profiles
`[[admin_rules]]`	id	one rule (`allow`/`deny`/regex)	profiles, devices

A device points at one profile (optional). It can belong to many groups.
A group has one profile and many devices.
A subnet has one profile and many CIDRs.
A blocklist or an admin rule is referenced by many profiles.
A schedule has exactly one target (a device or a group, never both) and one overlay profile.

The split between identity (devices, groups, subnets) and policy (profiles, blocklists, admin_rules) is deliberate. Identity entities point at a profile. A device may also carry local allow_rules / deny_rules — those are overrides, not a second policy bundle. That is why the same profile can govern a laptop, the kids’ tablets, and the guest VLAN.

How those entities are split across files: Declarative configuration.

Where each entity is documented

This page is the map. The territory lives one click away.

Profiles — Profiles
Devices, Groups, Subnets — Devices, Groups, Subnets
Admin rules — Admin rules
Schedules — Schedules
Blocklists — Blocklists
The full TOML schema — Warden TOML schema

Verify it in the code

Every claim on this page is one function away in the source.

The profile ladder (L1–L5)

src/profilesresolver.rs → ProfileResolver::resolve()

The rule layers (R1–R5)

src/filterengine.rs → FilterEngine::evaluate()

src/filterengine.rs → evaluate_inner()

src/filterevaluator.rs → priority_scan()

Schedule override of L1

src/profilesschedule.rs → active_schedule_profile()

override_profile_deny gating

src/config/schemavalidator.rs → validate()

src/profilesresolver.rs → apply_overlay()

The hardcoded L5 REFUSED

src/dnshandler.rs → handle_inner()

src/dnshandler.rs → send_refused()