Skip to content
The Gateway

Concepts

This page is the glossary. Read it once and the rest of the documentation will make immediate sense.

Networking objects

Section titled “Networking objects”

Device

Section titled “Device”

A specific endpoint on the LAN, identified by MAC address. The Gateway tracks devices regardless of their current IP — DHCP leases come and go, MAC doesn’t.

Device group

Section titled “Device group”

A named collection of devices, used for matching policies and DNS rules in bulk. kids, iot, engineering are typical groups.

Trust class

Section titled “Trust class”

A coarse role attached to a device: admin, operator, viewer, diagnostics, guest. Trust classes gate what the device is allowed to do (e.g. reach the UI, hit specific APIs). They do not drive routing — that’s what policies are for.

Privacy class

Section titled “Privacy class”

The posture attached to a device: which leak protections to enforce, whether IPv6 is allowed, whether QUIC is blocked, whether direct fallback is permitted. Built-ins: balanced, private, paranoid. See Privacy & kill-switch.

Routing objects

Section titled “Routing objects”

Tunnel

Section titled “Tunnel”

Any layer-3 path the daemon can route through. Today: WireGuard, OpenVPN, SOCKS5, or a raw WAN interface (for dual-WAN balancing). Each tunnel has its own routing table and fwmark range.

Bridge

Section titled “Bridge”

An authenticated proxy node on a VPS in uncensored space. The Gateway routes specific domains through a bridge instead of through a tunnel. Default transport is TLS; obfs4 is supported for DPI-heavy networks (QUIC and MASQUE selectors exist but the client currently falls back to TLS — see Bridge proxies for status).

Route profile

Section titled “Route profile”

A reusable bundle of routing settings — action, tunnel/pool/bridge, privacy_level, fail_policy, dns — that you reference from one or more policies. Keep duplication out of your policy list.

Routing policy

Section titled “Routing policy”

The rule that matches traffic and applies a route profile. A policy has a match (device / group / domain / interface / port / time) and an action (the profile or an inline route). Policies are evaluated in priority order; first match wins. See Routing policies.

Exception

Section titled “Exception”

A time-bounded override to a policy: “let this device bypass the VPN for 30 minutes”. Exceptions auto-expire, are logged to the audit trail, and disappear from the active policy set.

Privacy guarantees

Section titled “Privacy guarantees”

Kill-switch

Section titled “Kill-switch”

A reference-counted, fail-closed nftables rule that drops traffic for policies bound to a tunnel when that tunnel is down. Reference counting means overlapping policies can’t accidentally un-engage it. The kill-switch is per-policy, not global — one policy failing doesn’t blackhole the rest of the network.

Privacy level

Section titled “Privacy level”

A number 0–5 that controls the traffic-splitting engine’s behaviour: selection algorithm (latency / round-robin / crypto-random), jitter, packet padding, cover-traffic rate, HTB shaping, rotation interval. Higher level = stronger privacy, more overhead.

Fail policy

Section titled “Fail policy”

What happens to a policy’s traffic when its egress is down:

  • closed — drop. No leak.
  • open — fall back to direct egress. Convenient but leaks.

Multi-node objects

Section titled “Multi-node objects”

Mesh

Section titled “Mesh”

Overlay connectivity between two or more nodes (Tailscale or self-hosted Headscale). Gives every node a stable hostname inside the mesh and bidirectional NAT-traversed connectivity. See Mesh networking.

Federation

Section titled “Federation”

Configuration sharing between gatewayd instances over a mesh or REST connection. Each peer keeps its own SQLite; sync is per peer, per direction. Each peer relationship has a sync_policy (none/push/pull/bidirectional) plus two CSV allowlists (sync_resources outbound, allowed_receive_resources inbound) drawn from the kind catalog (bridges, routing, dns, devices, profiles, tunnels, segments, settings, nodes). See Federation.

Mesh vs federation

Section titled “Mesh vs federation”

Mesh is about whether boxes can reach each other. Federation is about who owns which configuration.

You usually want both. Federation typically runs over a mesh tunnel.

Operational objects

Section titled “Operational objects”

Reconciler

Section titled “Reconciler”

The loop that scans every kernel-level resource The Gateway owns (nftables tables, ip rule, ip route, redsocks processes, tunnel interfaces) once a minute and re-applies the desired state if anything drifted. This is what makes the daemon self-healing.

Alert rule

Section titled “Alert rule”

A (category, condition, severity, action) tuple that fires on policy violations, tunnel failures, leak detections, or drift. Dispatched via webhook or Telegram. See Alerts & monitoring.

Drift event

Section titled “Drift event”

A logged occurrence of the reconciler finding something it had to fix. Visible on the Reconciliation page; can be alerted on if it repeats.

Audit entry

Section titled “Audit entry”

Every config-changing API call is logged with operator, timestamp, before/after, and source IP. Retained for at least 90 days by default. Visible on the Audit page.

Anomaly

Section titled “Anomaly”

A heuristic event distinct from an alert rule. The observe subsystem fires anomalies on rolling-baseline deviations (DNS spike, traffic spike, new device, port scan); the optional Bluetooth IDS fires its own set (bt_* types). Anomalies surface on the Anomalies page and via GET /api/v1/anomalies — they don’t auto-page unless wired through an alert rule. See Alerts → Anomaly detection.

Dead-man’s switch

Section titled “Dead-man’s switch”

An opt-in safeguard that auto-wipes sensitive SQLite tables if no admin has authenticated within the configured window (default 72 hours). The wipe is the soft level — the manual POST /api/v1/system/wipe endpoint accepts medium and hard for escalated cases. See Threat model.

Configuration surfaces

Section titled “Configuration surfaces”

Bootstrap config

Section titled “Bootstrap config”

/var/lib/gateway/config.yaml. Read once at daemon startup. Anything the daemon needs before SQLite is reachable: listen address, network interfaces, the very first tunnel. See Configuration.

Runtime settings (kv_settings)

Section titled “Runtime settings (kv_settings)”

The mutable settings table in SQLite. Managed through the web UI / API / gwctl. Holds policies, devices, alert rules, privacy classes, DNS rules and similar everyday state. See the Settings reference.

Quick mental model

Section titled “Quick mental model”
Devices ─belong to─► Device groups
   │
   ├─have a─► Privacy class       (posture: IPv6, QUIC, WebRTC, force-DNS)
   ├─have a─► Trust class         (role: admin, operator, viewer)
   │
   ▼
 Routing policy  ─uses─►  Route profile  ─points at─►  Tunnel / Bridge / Direct
   │                                                          │
   │                                                          ▼
   └─protects with─►  Kill-switch (reference-counted)    Splitting engine
                                                              │
                                                              ▼
                                                       Privacy level 0–5
Section titled “Related”