Hierarchies
The seven nouns of a Warden config, and how they wire together into one policy per client.
The model
Warden’s config has seven entities. Sort them into two jobs and the whole model falls into place.
Every Warden config is built from seven nouns: profiles, devices, groups, subnets, schedules, blocklists, and Custom Lists. They split cleanly along one line:
- Identity — who is this client? Devices, groups, and subnets are three ways of recognising a client and binding it to a profile.
- Policy — what does that client get? Blocklists and Custom Lists are the raw filtering material; a profile bundles them into one named behaviour.
A profile is the hinge between the two. Identity entities point at a profile; a profile points at the policy it enforces. Nothing else connects — that is what keeps the model small enough to hold in your head.
The map
Profiles are the centre. Identity feeds in from the left, policy hangs off the right, and a schedule can swap the profile for a while.
Identity · who is the client?
- device
- group
- subnet
- default_profile
Policy · what's enforced?
- blocklists
- custom_lists
Read it in one breath: a device, group, or subnet points at exactly one profile — and if none match, the server’s default_profile catches the client. Every blocklist reaches that profile with the list’s own base, unless the profile overrides it for that list (deny, allow or ignore); the profile also mounts its own Custom Lists. A schedule is the only time-aware piece: it swaps in a different profile for a matched device or group during its window, then hands control back.
The roles
What each entity is for, which side of the identity/policy line it sits on, and how many profiles it touches.
| Entity | Role | Layer | To a profile |
|---|---|---|---|
| Profile | The policy bundle: blocklists, Custom Lists, the block response, optional local records | Policy — the hub | is the hub |
| Device | One client, pinned by IP and/or MAC | Identity | points at 1 (optional) |
| Group | A named set of devices that share a profile | Identity | 1 profile, many devices |
| Subnet | A CIDR range with a fallback profile (longest prefix wins) | Identity | 1 profile, many CIDRs |
| Schedule | A time-bounded swap to a different profile, for a device or group | Overlay | swaps to 1 |
| Blocklist | A list of domains, fetched over HTTPS or imported from a local file; its base is deny, allow, or ignore | Policy source | referenced by many |
| Custom List | A file of your own rules — allow, deny, wildcard, or regex | Policy source | mounted by many |
A few cardinality facts the table compresses:
- A device points at one profile (optional) and can belong to many groups.
- A group has one profile and many devices; a subnet has one profile and many CIDRs.
- A blocklist or a Custom List is used by many profiles — write it once, mount it anywhere.
- A schedule has exactly one target (a device or a group, never both) and one overlay profile.
Identity never carries policy
The split between identity and policy is deliberate — and it is why one profile can govern a dozen clients without duplication.
Identity entities — devices, groups, subnets — never hold inline filtering rules. They only point at a profile. All the real policy (which lists, which rules, what to answer with when a query is blocked) lives on the profile. That separation is what lets a single kids profile govern a tablet, a laptop, and a whole VLAN without three copies of the same ruleset: change the profile once, and every client bound to it updates.
Since 0.44.0 there is no exception to this. A device cannot carry allow or deny rules of its own. An exception for one client means a profile for that client, with a Custom List mounted on it.
Where each entity continues
This page is the map. Each noun has its own guide with the full schema, CLI, and worked examples.
- Profiles — the policy bundle every other entity points at.
- Devices, Groups, Subnets — the three identity layers.
- Schedules — time-bounded profile overlays.
- Blocklists and Custom rules — the policy sources a profile draws on.
See also
You’ve just seen how the entities are wired. For the order the resolver consults them — which profile wins when a client matches a device, a group, and a subnet all at once — see filtering process. This page is the structure; that one is the runtime.