Skip to content
vpn-confinement vpn-confinement

vpn-confinement

vpn-confinement provides fail-closed WireGuard confinement for selected NixOS systemd services. It is designed for deployments where some workloads should use the tunnel while the host and other services stay on normal networking.

When to use it

Section titled “When to use it”

Use vpn-confinement when you want to:

  • confine only the services that should use VPN egress
  • keep host networking unchanged for non-confined workloads
  • apply DNS and firewall policy at the namespace boundary
  • tear services down when the namespace or WireGuard path disappears

Security characteristics

Section titled “Security characteristics”
  • The trust boundary is the namespace, not the individual service.
  • Confinement uses namespace-local nftables policy and generated resolver files.
  • In the common path, set vpn.namespace explicitly on each confined service or socket.
  • dns.mode = "strict" is intended to reduce classic resolver leak paths, not to guarantee that all DNS exfiltration techniques are impossible.
  • securityProfile = "balanced" is the normal secure mode.
  • securityProfile = "highAssurance" is the strict preset for destination-constrained egress and stronger assertions.

Typical setup

Section titled “Typical setup”
  1. Import the module and enable services.vpnConfinement.
  2. Define one namespace per trust domain with a WireGuard interface and DNS policy.
  3. Opt specific services or sockets into a namespace with vpn.namespace.

Use the Generated Options reference for exact option names, defaults, and configuration details.

Common path first

Section titled “Common path first”

If you are deploying this for the first time, start here:

Use advanced options only when you have a clear compatibility requirement:

Advanced-only examples:

  • wireguard.socketNamespace
  • raw hostLink.* tuning
  • hostname endpoints
Section titled “Read next”
Architecture Implementation model, namespace lifecycle, and enforcement boundaries.
Threat Model Guarantees, non-goals, weaker modes, and current caveats.
Generated Options Full generated reference for the module's Nix options and defaults.
Common Deployments Recommended defaults and common setup patterns.
Reverse Proxy Host reverse proxy to namespace service patterns.
Section titled “Project links”