Files

T

omarandClaude Opus 5 32aac89139 docs: stop the docs promising a safety net that ships disarmed

Every install recipe walked the reader through `shaterd apply` + `shaterd
confirm` as if commit-confirm were armed. It is not: DefaultGlobals() never
seeds ConfirmTimeout, the shipped config carries confirm_timeout '0', and
ArmRollback returns at once on a non-positive timeout. A reader following the
README believed an apply that cut their SSH would undo itself. It would not.
README/README.en/INSTALL now arm it in the recipe and say what 0 means; the
apply-flow diagram gained the edge it always took on a stock box.

The boot armor was documented nowhere at all (`grep -rli armor --include=*.md`
returned zero) while shipping enabled and blocking LAN->WAN on every boot.
INSTALL 4 now says what it is, why SSH/LuCI stay up on purpose, every condition
under which it refuses to arm, and how to switch it off.

Also removed or corrected, each checked against the code, not inherited:

* MASQUE/CONNECT-IP is advertised in both READMEs and absent from parse,
  generate and model -- registry names it among the types deliberately left
  unregistered. Dropped, with the fork-vs-product distinction spelled out.
  The inverse too: Hysteria2/TUIC/XHTTP were tagged [T1] while shipped under
  with_quic/with_xhttp; ShadowTLS is generate+registry only, no parser.
* `direct (flow-offload on)` -- no offload/flowtable/flow_offloading anywhere
  in openwrt/, shater/ or panel/src. The product does not do this.
* shater-core deps were two releases stale in two places, one of which vouched
  for a config.buildinfo check that never covered kmod-tun. Ruling narrowed to
  what was actually checked.
* PORTING's "Full schema" -- the shipped config points at it -- was missing
  l3_tunnel and untunnelable_egress (UCI is their only path; the panel does not
  show them) and the blocklist/allowlist/device/alert sections, while listing a
  `config preset` that ReadUCI has no branch for.
* ARCHITECTURE had no L3 ingress and no kernel egress at all, though both are
  [MVP] and one creates an fw4 zone in the user's firewall config. New 3a.
* nftset-for-routing in the DNS diagram: that is the v0.1 mechanism, gone in v0.2.
* CONTEXT described a pre-Phase-1 repo and a 24.10.3 testbed. The testbed is
  ImmortalWrt 25.12.1 r37978-cd0a06bfd3fd (read off the box), which is not a
  detail: .apk does not install on 24.10 at all.
* The gate existed and no .md mentioned it. README/README.en/CONTEXT now do.
* release.yml's header still described publishing as either/or after the rolling
  pointer became unconditional. Comment only.
* Shipped /etc/config/shater: schema_version '1' against CurrentSchemaVersion=2;
  a pointer to a dns_filter line that was not in the globals block (added, '0');
  and `option sniff '1'` on the inbound -- an option the model deliberately does
  not have, which the first panel save would have silently washed out.
* lx-changelog pointed at a D25 heading that does not exist.
* ROADMAP 2b and 5 were done and unmarked.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BHw89tdWddzhjUc4bAH4tS

2026-07-26 23:35:06 +03:00

6.6 KiB

Raw Blame History

shater

A self-hosted internet-control appliance for OpenWrt routers. One box turns a home or office network into a transparent VPN gateway, a network-wide ad/tracker/malware blocker, per-device parental control, and a live traffic dashboard — all local, all configured from a rich built-in web panel.

The primary README is Russian — README.md. This is a condensed English mirror.

What it is

shater is a network proxy stack for OpenWrt / ImmortalWrt / BananaWRT routers (Banana Pi BPI-R3, BPI-R4 and compatible). It transparently routes all LAN traffic through a proxy (split by domain/geo/client), filters DNS, gathers statistics, and is managed from a built-in web panel.

The engine is a fork of sing-box via sing-box-lx, compiled into a single Go binary shaterd together with the control plane, DNS filter, stats aggregator and the web panel itself. Broad protocol set: VLESS/VMess/Trojan/Shadowsocks, Reality/XTLS, WireGuard, AmneziaWG 2.0, Hysteria2, TUIC, XHTTP — exactly what shater/parse can read and shater/registry registers in the engine.

A thin LuCI launcher (mini-dashboard + "Open panel" button) hands the browser a single-use token into the standalone SPA the daemon serves on its own port (default :8088).

Highlights

Transparent TPROXY data plane (TCP + UDP), SNI/Host/QUIC sniffing, no DNS leaks — :53 interception is on by default and covers the queries a client sends to the router itself, not just the ones aimed around it (globals.dns_intercept, D24).
First-match routing by source / destination / list / geo / client → outbound / selector / chain / direct / block; node groups with balancer/observatory; multi-hop chains; per-rule egress.
Fail-closed kill-switch (dead group → block, never a silent direct leak); own inet shater nft table; atomic apply with nft -c validation. Commit-confirm auto-rollback exists but ships OFF (confirm_timeout=0) — arm it yourself.
DNS filtering & blocklists with flexible sources (inline / file / url / geosite), compiled .srs matcher; Block-DoH/DoT to stop filter bypass.
Subscriptions (Clash / sing-box / Xray-JSON) and manual nodes; node health board.
Per-device control (proxy/blocklist toggles, exit country, per-device block/allow, schedules) and per-domain/client/device statistics from in-process DNS events.

Full list with MVP/T1/T2 tags — docs-shater/FEATURES.md.

Install

One signed apk feed (OpenWrt / ImmortalWrt / BananaWRT 25.12+), one release per arch. Verbatim commands, the manual .apk install and the rolling-vs-pinned choice are in docs-shater/INSTALL.md.

wget -O /etc/apk/keys/shater-apk.pem   "https://git.qomar.pw/omar/shater/releases/download/apk-latest-$(cat /etc/apk/arch)/shater-apk.pem"
echo "https://git.qomar.pw/omar/shater/releases/download/apk-latest-$(cat /etc/apk/arch)/packages.adb"   > /etc/apk/repositories.d/shater.list
apk update && apk add luci-app-shater         # -> shater-core -> shaterd

apk-latest-<arch> is a moving pointer refreshed by every release run — install once and apk update && apk upgrade shaterd shater-core luci-app-shater byedpi keeps the router current. Point the repo line at apk-vX.Y.Z-<arch> instead to pin a build; that file then has to be edited by hand for every upgrade.

shater ships inert (globals off) so install never breaks connectivity. After configuring nodes/rules:

uci set shater.globals.enabled=1
uci set shater.globals.confirm_timeout=120   # commit-confirm ships OFF — arm it
uci commit shater
shaterd apply && shaterd confirm

Without that middle line shaterd apply arms no auto-rollback (and says so), so an apply that costs you SSH/LuCI access has to be undone by hand.

Once an enabled, fail-closed config has been applied, /etc/init.d/shater-armor loads a saved fail-closed plane at boot, before the daemon exists: LAN→WAN forwarding is blocked until shaterd applies, while SSH/LuCI/the panel stay reachable on purpose (the chain hooks forward only). What arms it, what refuses to arm, and how to switch it off — INSTALL.md §4.

Build from source

scripts/build-shaterd.sh [VERSION] [--fast] builds the SPA (Vite), embeds it via //go:embed, cross-builds musl-static {amd64, arm64} and UPX-packs the artifact into openwrt/shaterd/files/. Details in docs-shater/INSTALL.md.

bash scripts/run-tests.sh is the test gate: the whole suite under the shipped build tags (scripts/router-tags.sh), on linux (it re-execs in Docker from a non-linux host), with -race, plus three machine checks against a silent skip — the tag set may only add test files, every package with tests must report ok by name, and every TestIntegration* must produce a verdict by name. scripts/check-router-tags.sh separately proves no feature declared in FEATURES.md lost a build tag it needs. A green gate is necessary but not sufficient: it does not see the kernel, procd or nftables seams.

Repository layout

Path	What
`shater/`	Go control plane, DNS filter, stats aggregator, engine host
`panel/`	Admin SPA (Vite + React + TS) and its Go server
`openwrt/`	Packages: `shaterd`, `shater-core`, `luci-app-shater`, `byedpi`
`docs-shater/`	Product documentation
`scripts/`, `ci/`, `.gitea/workflows/`	Build script, apk feed/release scripts, CI
`SPECS/`, `docs-lx/`	Engine-fork constitution/specs and feature-config reference
`docs/`, `mkdocs.yml`	Upstream sing-box docs (mkdocs) — kept as-is
`adapter/ cmd/ dns/ route/ option/ protocol/ transport/ …`	sing-box-lx engine tree

CI, upstream & license

CI (.gitea/workflows/release.yml) builds all 4 packages and publishes a signed per-arch apk repo (EC key shater-apk.pem). A vX.Y.Z tag → the pinnable apk-vX.Y.Z-<arch>; every run also refreshes the rolling apk-latest-<arch> and asserts over the API that it really serves the version just built.

The engine is the sing-box-lx fork — a thin downstream of upstream sing-box that lives by rebase, never merge; its constitution is SPECS/CONSTITUTION.md. Licensed under GPL-3.0, like upstream sing-box. Unofficial fork, not affiliated with SagerNet.

6.6 KiB Raw Blame History