elmprodvpn/selective-vpn-api/TRAFFIC_OVERRIDES_USAGE.md

Traffic Mode and Overrides Usage

This document describes how to use traffic mode extensions in the current build:

• traffic modes: selective, full_tunnel, direct
• auto_local_bypass
• policy overrides by source subnet / UID / cgroup (systemd)
• detected candidates UI (Add detected...)

1) Modes

• selective: only marked traffic goes to VPN table (agvpn)
• full_tunnel: all traffic goes to VPN table
• direct: base VPN routing rules are removed

Notes:

• DNS mode is independent from traffic mode.
• Modes are controlled from GUI dialog Traffic mode settings.

2) Auto-local bypass

Option: Auto-local bypass (LAN/container subnets).

When enabled, backend mirrors local routes from main table into agvpn table:

• link-scope routes
• private/local ranges
• common container interfaces (docker*, br-*, veth*, cni*)

Purpose: reduce LAN/container breakage in full_tunnel.

Important:

• auto_local_bypass does NOT make containers use direct internet in full_tunnel.
• If you want containers to be direct in full_tunnel, use Force Direct subnets.

3) Policy overrides (Advanced)

Configured in dialog tab Policy overrides (Advanced).

Layout:

• Force VPN column
• Force Direct column

Each column provides the same types of overrides:

• Source subnets
• UIDs
• Cgroups / services

3.1) Source subnets

Meaning: force routing for traffic by source subnet.

Input format:

• subnet: 172.18.0.0/16
• single IP is accepted and normalized to /32
• one value per line (comma/semicolon separated values are also accepted)

Practical usage:

• Docker/bridge networks are best controlled via Source subnets.

3.2) UIDs

Meaning: force routing for host-local processes by UID/uidrange.

Input format:

• UID: 1000
• UID range: 1000-1010
• one value per line

Important limitation:

• UID rules generally affect host OUTPUT traffic, not forwarded traffic from Docker bridges.

3.3) Cgroups / services

Meaning: select workloads by systemd cgroup, backend resolves them to UID rules at apply time.

Input format:

• cgroup path or cgroup name, one per line
• examples:
  • /system.slice/jellyfin.service
  • system.slice/docker.service

Current implementation model:

1. backend scans matching cgroup directory (recursively) and reads cgroup.procs
2. resolves each PID owner UID from /proc/<pid>/status
3. creates uidrange policy rules from those UIDs

Important limitations:

• cgroup override is currently UID-based after resolution.
• if multiple workloads run under same UID (for example root), they cannot be separated by UID policy rules.
• if cgroup has no running processes at apply time, no UID rules are created from that cgroup.

4) Detected candidates (Add detected...)

Button: Add detected... (in Policy overrides (Advanced)).

This opens a selector populated by the backend endpoint:

• GET /api/v1/traffic/candidates

Tabs:

• Subnets: LAN + docker/bridge subnets detected from ip -4 route show table main
• Services: running systemd units -> mapped to cgroup like system.slice/<unit>.service
• UIDs: UIDs detected from running processes (ps -eo uid,user,comm)

Presets (Subnets tab):

• Keep LAN direct
• Keep Docker direct

Safety model:

• Selecting items only fills the text fields.
• Nothing changes on the host until you click Apply overrides.

5) Rule priority and precedence

Managed ip rule priorities:

• direct subnet overrides: 11600+
• direct UID overrides: 11680+
• VPN subnet overrides: 11720+
• VPN UID overrides: 11800+
• full tunnel base rule: 11900
• selective base rule: 12000

This means direct overrides are evaluated before VPN overrides and before base mode rules.

6) Recommended workflow

1. Select traffic mode.
2. Select preferred iface (or auto).
3. Toggle auto_local_bypass as needed.
4. Fill overrides (subnet/UID/cgroup), optionally using Add detected....
5. Click Apply overrides.
6. Click Test mode (on Routes tab).
7. If needed, click Clear routes (save cache) and/or Restore cached routes.

7) Observability

GUI status line shows:

• desired/applied mode
• bypass route count
• override count
• resolved cgroup UID count
• cgroup warning text (if any)

8) Troubleshooting quick checks

ip rule show
ip -4 route show table agvpn
nft list ruleset | sed -n '/table inet agvpn/,$p'

If mode health is not OK:

• verify selected iface exists and is up
• verify agvpn table has default route in VPN modes
• verify subnet/UID/cgroup entries are valid and currently active