Files

T

omarandClaude Fable 5 c257d6c5cc docs(readme): rewrite root README as Russian shater product face

- README.md: new Russian product README (what/features/architecture
  mermaid/install both feeds/build/repo layout/CI/upstream/docs/license)
- README.en.md: concise English mirror (root readme was previously English)
- README.ru.md: demoted to a pointer stub (was the sing-box-lx fork readme,
  a competing Russian README) -> points to README.md + engine-fork docs
- docs-shater/README.md: folder index

Install commands copied verbatim from docs-shater/INSTALL.md; all links
verified against existing files.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-24 23:31:06 +03:00

5.1 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, MASQUE/CONNECT-IP.

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.
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 and commit-confirm auto-rollback.
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

Two signed feeds. Pick by the router's OpenWrt version. Verbatim commands and the manual .ipk/.apk install are in docs-shater/INSTALL.md.

opkg (OpenWrt 24.10):

wget -O /etc/opkg/keys/5ac4b177689cb8e0 \
  https://git.qomar.pw/omar/shater/releases/download/latest/shater-feed.pub
echo "src/gz shater https://git.qomar.pw/omar/shater/releases/download/latest" \
  >> /etc/opkg/customfeeds.conf
opkg update && opkg install luci-app-shater   # -> shater-core -> shaterd

apk (OpenWrt / ImmortalWrt / BananaWRT 25.12+):

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

shater ships inert (globals off) so install never breaks connectivity. After configuring nodes/rules: uci set shater.globals.enabled=1 && uci commit shater, then shaterd apply and shaterd confirm.

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.

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, 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 signed feeds: opkg (usign, key 5ac4b177689cb8e0) and apk (EC key shater-apk.pem). A vX.Y.Z tag → versioned release; workflow_dispatch → rolling latest.

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.

5.1 KiB Raw Blame History