baseline: api+gui traffic mode + candidates picker
Snapshot before app-launcher (cgroup/mark) work; ignore binaries/backups.
This commit is contained in:
beckline
173
selective-vpn-api/TRAFFIC_OVERRIDES_USAGE.md
Normal file
173
selective-vpn-api/TRAFFIC_OVERRIDES_USAGE.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user