# 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

```bash
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