Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions docs/MODULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ file, applies with snapshot + verify + auto-rollback, and serves the web UI API
| net | 10 | `mr/mod_net*.go`, `mr/hooks.go` | `rootfs/www/ui/net.js` | `lan`, `networks`, `wan`, `multiwan`, `policy_routes`, `static_routes`, `multicast` | links, bridges, VLANs, WAN (PPPoE/DHCP), multi-WAN failover, routing, IPv6 WAN side (dhcpcd), port status |
| wifi | 20 | `mr/mod_wifi*.go` | `ui/wifi.js` | `wifi` | radios, SSIDs, hostapd, stations; tuning: multicast-to-unicast, 802.11v band steering, radio health + self-heal (`mr wifi tick`, a crond line in sys's crontab block; its events are type `wifi`) |
| dns | 30 | `mr/mod_dns*.go` | `ui/dns.js` | `dhcp`, `dns`, `networks[].dhcp` (type `Pool`) | dnsmasq: DNS, DHCP, RA/DHCPv6, split lists, local records, stubby.yml, query log; `rootfs/etc/conf.d/dnsmasq` |
| dev | 35 | `mr/mod_dev*.go` | `ui/dev.js` | `devices`, `groups` | device inventory and groups other sections refer to by name (resolved at validate / render; dnsmasq dhcp-host lines through the dns module), `mr pause` / `mr unpause` (runtime nft sets with timeouts, inserted by fwLoad) |
| fw | 40 | `mr/mod_fw*.go` | `ui/fw.js` | `firewall` | nftables skeleton + hooks, zones, forwards, rules, NAT, IPv6 pinholes, access control |
| mon | 50 | `mr/mod_mon*.go` | `ui/mon.js` | — | realtime graphs, per-device traffic, connections, system load; its per-minute sampler (`mon-collect`) also starts sys's `mr event tick` when due |
| proxy | 55 | `mr/mod_proxy*.go` | `ui/proxy.js` | `proxy` | selective transparent proxy: sing-box, fake-ip DNS, tproxy, bypass devices |
Expand All @@ -39,9 +40,13 @@ Register exactly one `Module` in `init()`:
Reject newlines / control chars / quotes wherever they could break out of a config line.
- `Render(c, out)` — add generated files (`out.Add(path, mode, data)`); must not touch the system.
- `NetSh(c, phase, b)` — idempotent POSIX sh for `network.sh`, phases `links` → `wifi` → `routes` → `tail`.
- `Nft(c, hook, n)` — nftables lines at hook points (`defs`, `input`, `forward_early`, `forward`,
`mark`, `dstnat`, `srcnat`, `output`), see `nftHooks`. A module that needs its own base chain
(different priority) declares it in `defs`. `n.W(format, args...)` writes one line.
- `Nft(c, hook, n)` — nftables lines at hook points (`defs`, `input`, `forward_first`, `forward_early`,
`forward`, `mark`, `dstnat`, `srcnat`, `output`), see `nftHooks`. `forward_first` is the top of
filter/forward, before flow offload and the established accept: only for drops that must also stop
established connections (policy route `fallback: drop`). A module that needs its own base chain
(different priority) declares it in `defs`. `n.W(format, args...)` writes one line. Runtime state
that must survive reloads but never appears in the rendered file (learned sets, `mr pause`) is
appended by `fwLoad` in the same nft transaction, under `/run/mini-router/fw.lock`.
- `FlowDevs(c)` — netdevs for the offload flowtable. `Dnsmasq(c)` — extra dnsmasq.conf lines.
- `Services(c)` / `Managed` — OpenRC services wanted / owned. `Restart(path)` — service to restart
when a generated file changes (`"-"` = none). `RestartOrder` — relative restart order.
Expand Down Expand Up @@ -106,7 +111,10 @@ by mon's sampler). Messages are English, one line, cleaned (`eventClean`): text
markup. A new type needs an entry in `eventTypes` / `eventLabels` and the web UI's `EVT` map (`sys.js`).

Cross-module helpers: `c.LANNets()`, `c.BridgeFor(network)`, `c.LANBridges()`, `c.WANIfnames()`,
`c.WANTable(name)`, `c.WANByName(name)`, `c.Secret(key)`.
`c.WANTable(name)`, `c.WANByName(name)`, `c.Secret(key)`. Device inventory (dev, `mod_dev.go`): a key
that names devices resolves them with `devRefMACs` / `devMACs` (a device or `group:NAME` → MACs),
`devHostIP` (a device → its `ip`), validates with `devCheckRefs` (an unknown name is an error at the
place that uses it); `c.knownHosts()` = `dhcp.hosts` + one entry per device MAC (names, fixed addresses).

Secrets (passwords, keys) live in `secrets.yaml`; router.yaml stores the secret **name**
(`*_secret` fields). The UI sets secrets by name and can never read them back.
Expand Down
5 changes: 3 additions & 2 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,8 @@ undone by a rollback. Revoking also drops the hash, so a name used again never b

| Scope | Actions |
|---|---|
| `read` | `status`, `config`, `schema`, `history`, `history.diff`, `job`, `net`, `net.ports`, `net.routes`, `net.wan`, `wifi.status`, `wifi.stations`, `wifi.survey`, `wifi.health`, `dns.stats`, `dns.leases`, `fw.stats`, `proxy.status`, `mon.now`, `mon.history`, `mon.devices`, `mon.conns`, `mon.procs`, `mon.dmesg`, `sys.services`, `sys.time`, `sys.doctor` (runs the health checks), `sys.events` (the event log), `sys.edge` |
| `operate` | + `net.redial`, `wifi.kick`, `wifi.scan`, `dns.release`, `proxy.delay`, `proxy.select`, `service` (start / stop / restart), `diag` |
| `read` | `status`, `config`, `config.raw`, `schema`, `history`, `history.diff`, `job`, `net`, `net.ports`, `net.routes`, `net.wan`, `wifi.status`, `wifi.stations`, `wifi.survey`, `wifi.health`, `dns.stats`, `dns.leases`, `fw.stats`, `proxy.status`, `proxy.routes`, `mon.now`, `mon.history`, `mon.devices`, `mon.conns`, `mon.procs`, `mon.dmesg`, `sys.services`, `sys.time`, `sys.doctor` (runs the health checks), `sys.events` (the event log), `sys.edge`, `dev.paused` (active pauses) |
| `operate` | + `net.redial`, `wifi.kick`, `wifi.scan`, `dns.release`, `dns.adblock`, `proxy.delay`, `proxy.select`, `service` (start / stop / restart), `diag`, `dev.pause` (`{target, duration}`: a device, `group:NAME`, dhcp.hosts name or MAC; `30m` … `7d`), `dev.unpause` (`{target}`, `all`) |
| `apply` | + `plan`, `validate`, `apply`, `confirm`, `revert`, `rollback` |

Never, whatever the scope: login / sessions, the web UI password, logs (`logs`, `sys.logs`: they can
Expand Down Expand Up @@ -78,6 +78,7 @@ R=http://192.168.1.1/cgi-bin/api; H="Authorization: Bearer $MR_TOKEN"
curl -sH "$H" "$R?a=status"
curl -sH "$H" "$R?a=mon.devices"
curl -sH "$H" -d '{"mac":"aa:bb:cc:dd:ee:ff"}' "$R?a=wifi.kick" # operate
curl -sH "$H" -d '{"target":"group:kids","duration":"1h"}' "$R?a=dev.pause" # operate: no internet for an hour
```

POST bodies are JSON. Errors: `{"error": "..."}` with the HTTP status (400 bad input, 401 no / bad /
Expand Down
152 changes: 152 additions & 0 deletions docs/modules/dev.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
# dev — device inventory, groups, pausing a device

Cd1s/mini-router#15. Files: `mr/mod_dev.go` (inventory, groups, name resolution), `mr/mod_dev_pause.go`
(`mr pause`), `rootfs/www/ui/dev.js` (网络 › 设备), `tools/ci.d/dev.sh`, lab fragment `examples/lab.d/35-dev.yaml`.
Nothing resident, no new package, no new process.

## Inventory (`devices`, `groups`)

A device is a name for one or more MACs (cable + WiFi, a phone's per-network private address),
optionally with a fixed IPv4. Other sections refer to it by name instead of repeating MACs / addresses:

```yaml
devices:
- name: office-pc # [a-z]([a-z0-9-]{0,30}[a-z0-9])?: a DNS label that cannot be read as an IP / MAC / lease time
macs: ["02:00:00:00:10:01"] # 1-8 unicast MACs; a MAC belongs to one device and is not also in dhcp.hosts
ip: 192.168.1.70 # optional fixed IPv4 inside a LAN-side network (a static lease)
type: pc # optional label: pc, phone, tablet, tv, console, iot, server, printer, other, …
owner: alice # optional label (the person)
desc: "" # optional, UI only
- {name: kid-tablet, macs: ["aa:bb:cc:00:00:21", "aa:bb:cc:00:00:22"], type: tablet, owner: kid}
groups:
kids: [kid-tablet, game-console] # name: reName ([a-z][a-z0-9_-]{0,14}); 1-256 devices; written group:kids elsewhere
```

Where names work (resolved when the config is validated and rendered — router.yaml is never rewritten,
the older keys keep working unchanged):

| Key | Takes | Becomes |
|---|---|---|
| `firewall.forwards[].to` | an IPv4 or a device with `ip` | the DNAT target |
| `firewall.access[].devices` | devices, `group:NAME` (next to / instead of `macs`) | all their MACs (1-64 in total) |
| `policy_routes[].device` | a device or `group:NAME` (instead of `mac`) | `ether saddr { its MACs }` |
| `proxy.bypass[].device` | a device or `group:NAME` (instead of `mac`) | its MACs in `@proxy_bypass` |
| `guard.always_bypass` | device names too | every MAC of the device must be bypassed |
| `sys.wol`, `mr wol`, `schedules` `wol` | device names too | the device's first MAC |
| `mr pause`, `dev.pause` | device, `group:NAME`, dhcp.hosts name, MAC | all its MACs |

A name that does not exist is a validation error at the place that uses it
(`firewall.forwards[3].to: unknown device "office-pc" (devices:)`), so deleting a device that is still
referenced lists every reference; a forward to a device without `ip` is refused.

**dhcp.hosts and devices — one source of truth.** Every device is one dnsmasq line, rendered by the dns
module after the `dhcp.hosts` lines: `dhcp-host=MAC[,MAC…][,IP],NAME[,lease]`. The inventory name is the
device's DHCP / DNS name (`office-pc.lan`); `ip:` makes it a static lease exactly like a `dhcp.hosts` entry.
A MAC, name or address may be in `dhcp.hosts` or in `devices`, never in both (validation), so there are
no two places that disagree. `dhcp.hosts` stays as it is (the web UI can move an entry into the inventory:
网络 › 设备 › 从终端添加 › 静态分配); `dhcp.host_leases` accepts device MACs. Several MACs with one `ip`
share it: only one of them can hold the lease at a time (right for cable / WiFi of one laptop; give a
device that uses both at once no `ip`, or two devices). The inventory also names devices in 终端设备,
流量统计 / 连接 (mon), WOL, and new-device events (an inventory MAC is never "new").

## Pausing a device (`mr pause`)

Runtime only: no config change, no confirm window, nothing resident; the kernel ends the pause.

mr pause kid-tablet 1h # device, group:kids, a dhcp.hosts name or a MAC; 30m, 2h30m, 1d … (1s – 7d)
mr pause list [--json] # MAC, name, what was paused, time left, addresses
mr unpause kid-tablet | all # end it early

Web UI: 暂停 on 网络 › 设备 (devices and groups) and 状态 › 终端设备 (every DHCP client; a MAC of the
inventory pauses the whole device), durations 30 分钟 / 1 / 2 小时 / 到明早 7:00 / custom; active pauses
on 总览 with 恢复. API: `GET dev.paused` (read), `POST dev.pause {target, duration}` and
`POST dev.unpause {target}` (operate; recorded in `/etc/router-changes.log` like other web UI actions).

How it works:

- State: `/run/mini-router/pause.json` (tmpfs — a reboot ends every pause): the MACs, when each pause
ends in **seconds since boot** (the clock the kernel's set timeouts run on, so NTP setting the clock at
boot changes nothing), who paused it, and the device's addresses (neighbour table, DHCP lease, fixed ip).
- `fwLoad` (every firewall reload: apply, PPPoE / DHCP hooks, `mr fw`, `mr pause`) adds, in the same nft
transaction as the ruleset: sets `paused` (ether_addr), `paused_4`, `paused_6` with per-element
timeouts = the time left, and inserts at the top of both chains:

forward: iifname {LAN-side} ether saddr @paused oifname {WANs} counter drop comment "pause"
iifname {WANs} ip daddr @paused_4 counter drop comment "pause" (and ip6 / @paused_6)
input: iifname {LAN-side} ether saddr @paused fib daddr type != { local, broadcast, multicast, anycast } drop

(input: a transparent proxy takes the device's traffic through input; DHCP, DNS, ND to the router keep
working). None of this is in the rendered `nftables.nft`, so `mr plan` never shows it.
- Cutting what already runs: a pause replaces the whole table. That replaces the flowtable, which sends
every offloaded flow (PPE / WED or software fast path) back to the CPU path; the paused device's packets
then meet the drops in both directions (replies from the WAN first — hence the address sets), everyone
else's flows are offloaded again by their next packet. The issue proposed deleting the device's conntrack
entries; the platform kernel has no `nf_conntrack_netlink` (checked on the router: no `conntrack` tool,
no module), and a reload does the same job without one.
- An address another MAC holds now (neighbour table) is left out, so a lease given away while the paused
device was gone is not cut. The addresses matter only for connections from before the pause.
- The end: the kernel drops the elements; the (then empty) rules stay until the next reload.
- Reloads are serialized (`/run/mini-router/fw.lock`) and read the state under that lock, so a PPPoE hook
reloading during `mr pause` cannot load a copy without the pause last. `mr pause` checks that the
loaded `@paused` set holds the MACs and fails otherwise.

Not offloaded while paused (dropped instead); a device that is not paused is never affected.

## Cost

Binary: stripped linux/arm64 `mr` 10 158 240 → 10 223 776 bytes (+64 KiB; text +74.5 KiB) for the whole
issue (inventory, name resolution, pause, policy fallback, API); init allocation unchanged (lazy regexps).
RAM: nothing resident; while a pause is active 3 small sets and 4 rules. Flash: none for a pause from
the CLI; one line in `/etc/router-changes.log` per pause / unpause from the web UI / API. Home config:
no inventory → rendered files unchanged (`tools/ci.d/dev.sh` checks that no pause state is in them).

## Left out (see the issue)

- `watch: true` (online / offline events per device), `firewall.unknown_devices: allow | notify | isolate`
(new-device *notification* exists: event `new_device`; isolation of unknown MACs needs a default-deny
set of known MACs and would lock out every phone with a new private address), device type guessing
(OUI table + DHCP fingerprints), a per-device detail page (lease / signal / traffic / connections /
rules on one screen), `runtime.json` for all temporary states.

## 怎么用

**网页**

- **网络 › 设备**:设备清单。每行显示名称、类型 / 归属 / 所在分组、MAC(可多个)、IP(固定的或当前租约)、
是否在线(WiFi 在线 / 有租约)、是否暂停、被几处引用(鼠标悬停看是哪里)。
- “从终端添加…”:从 DHCP 终端里挑一台加进清单;也可以把“静态分配”里的旧条目移进清单(移完旧条目自动删掉)。
- “编辑”:改名会同时改掉端口转发、设备管控、策略路由、代理例外、分组里对它的引用;填“固定 IPv4”= 静态分配。
- “删除”:还有地方在用时列出这些地方,不让删;只在分组里的会顺带移出分组。
- “暂停”:选 30 分钟 / 1 小时 / 2 小时 / 到明早 7:00 或自己填(如 45m、1d,最长 7 天)。只断外网,内网、
DHCP、DNS 照常;正在看的视频、在玩的游戏立即断开;到时自动恢复,也可以点“恢复”。不改配置、没有确认倒计时。
- “分组”:建 `kids` 这样的分组,“暂停整组”一次停掉一家人的设备;其他地方写 `group:kids`。
- **状态 › 终端设备**:每个 DHCP 终端都有“暂停”按钮(属于清单里的设备时整台设备一起暂停)。
- **总览**:有设备在暂停时显示“暂停上网中”卡片,可直接恢复。
- **防火墙 › 设备管控**、**路由 › 策略路由**、**代理 › 例外设备**、**端口转发**:都可以直接选 / 写设备名或 `group:分组`。

清单、分组的改动和其他配置一样点底部“保存并应用”;暂停 / 恢复立即生效,不需要应用。

**命令行 / agent**

```sh
mr pause kid-tablet 1h # 暂停一小时
mr pause group:kids 9h # 整组
mr pause aa:bb:cc:dd:ee:ff 30m # 不在清单里的设备按 MAC
mr pause list # 谁在暂停、还剩多久
mr unpause kid-tablet # 提前恢复(all = 全部)
```

router.yaml(改完 `mr validate` → `mr plan` → `mr apply --confirm 120` → `mr confirm`):

```yaml
devices:
- {name: nas, macs: ["aa:bb:cc:dd:ee:10"], ip: 192.168.1.10, type: server}
- {name: kid-tablet, macs: ["aa:bb:cc:dd:ee:21"], type: tablet, owner: kid}
groups:
kids: [kid-tablet]
firewall:
forwards: [{name: nas-https, proto: [tcp], port: "8443", to: nas, to_port: "443"}]
access: [{name: kids-night, devices: ["group:kids"], schedule: [{days: [sun, mon, tue, wed, thu], time: "21:30-07:00"}]}]
policy_routes:
- {name: nas-wan2-only, device: nas, via: wan2, fallback: drop} # wan2 断线时 nas 断网,不换线
```
6 changes: 5 additions & 1 deletion docs/modules/dns.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,11 @@ it off the internet.
`hosts[].name` may not be something dnsmasq reads as a lease time or keyword in `dhcp-host=`
(`12345`, `5m`, `2w`, `infinite`, `ignore` — the last one would stop DHCP for that device);
"设为静态" in the UI turns such a DHCP-supplied name into `host-<n>`.
`host_leases` keys must be MACs of `dhcp.hosts` entries. (It is a separate map because the core test
Devices of the inventory (`devices:`, dev module, [dev.md](dev.md)) are rendered here too, after the
`dhcp.hosts` lines: one `dhcp-host=MAC[,MAC…][,IP],NAME[,lease]` per device (the name becomes its DHCP / DNS
name; `ip:` makes it a static lease). A MAC, name or address may be in `dhcp.hosts` or in `devices`, not in
both. `host_leases` keys must be MACs of `dhcp.hosts` entries or devices (a device takes the lease time of its
first MAC that has one). (It is a separate map because the core test
`render_test.go` builds `Host` with a positional literal; moving it to `hosts[].lease` needs that one
line changed — see the integration notes.)

Expand Down
Loading
Loading