luci-app-zt-gateway/README.md

# luci-app-zt-gateway

A LuCI application for OpenWRT that lets users switch which remote ZeroTier node
acts as the internet exit gateway for WIBLAN clients (`10.11.13.0/24`).

Users select a region/gateway, choose a switch mode, and the app reconfigures
kernel routing, conntrack, hotplug scripts, and UCI network routes with minimal
disruption.

## Switch modes

- **Force** — instant cutover (~1-2s disruption); existing connections break and
  clients auto-reconnect through the new gateway. Flushes conntrack for the
  WIBLAN subnet.
- **Graceful drain** — zero disruption; existing connections keep using the old
  gateway via fwmark + a drain routing table, while new connections go through
  the new gateway immediately. Auto-falls-back to a force switch after a
  configurable timeout if drain does not complete.

## Files

```
luci-app-zt-gateway/
├── Makefile                                # OpenWRT build (luci.mk)
├── htdocs/luci-static/resources/view/zt-gateway/overview.js   # LuCI UI
├── root/etc/config/zt-gateway              # UCI config: gateway registry + state
├── root/usr/sbin/zt-gateway-switch         # shell: actual switch logic
├── root/usr/share/rpcd/acl.d/luci-app-zt-gateway.json        # ACL
├── root/usr/share/rpcd/ucode/zt-gateway.uc # rpcd backend (ubus)
└── root/usr/share/luci/menu.d/luci-app-zt-gateway.json        # menu entry
└── docker-compose.yml                      # local Docker test harness
└── Dockerfile.router                       # test image (archlinux + tools)
└── docker/router-entrypoint.sh            # brings up br-zt + baseline routing
└── docker/gw-entrypoint.sh                # simulated ZT exit node startup
```

The `zt-gateway-switch` script is callable directly from SSH for testing; the
rpcd/ucode backend wraps it for the LuCI UI and exposes these ubus methods
under the `zt-gateway` object:

| Method         | Args                          | Description                                    |
| -------------- | ----------------------------- | ---------------------------------------------- |
| `status`       | —                             | active gateway, settings, gateway registry    |
| `switch`       | `{ region, mode }`            | execute a force or graceful switch              |
| `health`       | `{ region }`                 | ping a gateway over br-zt, return latency       |
| `drain_status` | —                             | graceful drain progress + remaining flows      |
| `cancel_drain` | —                             | cancel drain and force-switch to the new gw    |

## UCI config

`/etc/config/zt-gateway` holds the gateway registry and active state:

```
config global 'global'
    option active_gateway 'amsterdam'   # region key of active gateway
    option switch_mode 'force'           # 'force' | 'graceful'
    option drain_timeout '600'           # graceful drain timeout (seconds)
    option health_interval '60'
    option auto_failback '0'

config gateway
    option region 'amsterdam'
    option label 'Amsterdam (ocirosea641)'
    option ip '10.11.12.3'
    option default '1'
    option health_check 'ping'
```

## Build & install

Build against the OpenWRT SDK with `luci.mk` (architecture-independent —
`LUCI_PKGARCH:=all`). Full instructions are in
[`.omp/plans/zerotier-gateway-switching.md`](.omp/plans/zerotier-gateway-switching.md).

A manual `opkg-build` cheat sheet, the `apk` install path for OpenWRT 25.12+,
and post-install cache clearing are all documented there too.

## Local test harness (Docker)

End-to-end verification without a physical router is possible with the bundled
`docker-compose.yml` + `Dockerfile.router` + `docker/*-entrypoint.sh`. The
harness emulates two bridge networks (WIBLAN clients at `10.99.13.0/24` and
ZeroTier exit gateways at `10.99.12.0/24`) plus two simulated exit nodes, and
exercises `zt-gateway-switch` against real `iproute2`, `iptables`, and the
host kernel's conntrack table.

Run it with `docker compose up -d --build`, then `docker exec openwrt-router
zt-gateway-switch <ip> <mode> [drain_timeout]`.

## Verified behavior

The following scenarios have been exercised against the Docker harness:

- Force switch: `ip route show table 100` reflects the new gateway, host route
  and mwan3 table 1 return route preserved.
- Graceful drain: table 100 → new gateway, table 101 → old gateway, fwmark
  `0x100` rule at priority 99 inserted above the priority-100 src rule,
  ESTABLISHED WIBLAN connections keep flowing through the old gateway until
  they naturally age out, after which the mangle rules, drain table, and
  pidfiles are cleaned up automatically.
- Pre-flight: switching to an unreachable gateway aborts with exit code 2 and
  leaves routes untouched (verified for both `force` and `graceful` modes).
- Drain timeout: a forced-fallback fires after the configured timeout,
  preserving the new gateway in table 100 and tearing down drain state.

## Persistence model

The gateway IP is recorded in five places on the router; the switch script
updates them all atomically:

| Location                          | What                                   |
| --------------------------------- | -------------------------------------- |
| Kernel: host route                | `<gw_ip> dev br-zt`                    |
| Kernel: table 100 default         | `default via <gw_ip> dev br-zt table 100` |
| UCI: `/etc/config/network`        | `zt_gateway_host` + `zt_gateway_default` routes |
| Hotplug: `99-zerotier-bridge`     | host route + table 100 route + mwan3 table 1 return |
| Boot: `/etc/rc.local`             | all three routes                       |

The hotplug and rc.local scripts are rewritten via a dot-escaped `sed` replace
so a reboot boots against the new gateway.

## License

Apache-2.0