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
45 changes: 43 additions & 2 deletions docs/modules/dns.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,10 @@ records), `mr/mod_dns_query.go` (tiny DNS client, statistics, post-apply read-ba
a dnsmasq built with nftset: the image ships Alpine's `dnsmasq-dnssec-nftset` (DNSSEC is compiled in but off);
plain `dnsmasq` refuses such a config (`dnsmasq --test` in the init script), so the apply rolls back.

Not included on purpose: adblock lists, DHCPv6-only (no SLAAC) mode (Android cannot use it),
- **Ad blocking** (`dns.adblock`, Cd1s/mini-router#30, off by default): blocklists as dnsmasq `local=` lines, no new
process (see below).

Not included on purpose: AdGuard Home (≈34 MiB, killed by the OOM killer with big lists), DHCPv6-only (no SLAAC) mode (Android cannot use it),
DHCPv6 lease release, MX records.

Cost: no new daemon. Flash: a few KB of Go code in `mr`. RAM: none at rest; stubby (~2 MB RSS) only
Expand Down Expand Up @@ -151,6 +154,13 @@ dns:
private_relay: allow # allow (default) | block: mask.icloud.com / mask-h2.icloud.com → NXDOMAIN
block_dot: false # true: LAN → port 853 (DoT / DoQ) refused
doh_blocklist_file: "" # /etc/mini-router/dns/doh.ips: LAN → port 443 of these IPs / CIDRs refused
adblock:
enabled: false
lists: # https only; plain domains, hosts, adblock (||name^) or dnsmasq (local=/name/) lines
- https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/wildcard/multi-onlydomains.txt # ~165k
# - https://anti-ad.net/domains.txt # ~110k, Chinese sites
allow: [example.com] # never blocked, with everything under it
max_domains: 300000 # default; an update above it keeps the previous lists
```

DNS sovereignty (`dns.sovereignty`). Encrypted DNS that bypasses the router doesn't break anything by
Expand All @@ -172,6 +182,25 @@ fake-ip split (ECH does not matter here: the split works on the DNS name, not on
then `mr apply` (or `mr fw`) loads it. Keep it under `/etc/mini-router/dns/` so backups include it.
Agents and API tokens cannot set it (a `*_file` key).

**Ad blocking** (`dns.adblock`). `mr dns adblock update` downloads the lists (https only, the router's own
connection: not through the proxy), keeps valid names (at least two labels, no IPs; element-hiding rules, exceptions
and `server=/name/#` lines are not names), drops duplicates and names under another listed name, removes the allowed
ones, and writes `/etc/mini-router/state/adblock.conf`: one `local=/name/` per domain, plus `server=/name/#` for an
allowed name under a blocked one (forwarded as usual). Both dnsmasq instances load it (`conf-file=`): a blocked name
and everything under it answer NXDOMAIN. The lists' own hosts, the NTP servers and the local domain are never blocked.

- An update never makes things worse: a list that fails to download, is larger than 64 MiB or does not look like a
domain list (under half of its lines usable, e.g. an HTML error page) keeps the previous file; so does a result
above `max_domains`. A new file restarts dnsmasq (and the proxy's dnsmasq): DNS pauses 1–2 s; if dnsmasq does not
answer again within 30 s the previous file is put back.
- Schedule: crond runs `mr dns adblock update --cron` hourly at a minute fixed per router; it downloads only when the
file is 20 h old or was built from other settings, so switching it on, or a failed update, is (re)tried within the
hour. Never while a change waits for confirmation. `mr dns adblock update` / 立即更新 runs it now.
- `mr apply` renders an empty file when there is none (dnsmasq refuses a missing `conf-file`); an existing list is
never part of a plan or a snapshot.
- Cost: no process. RAM: dnsmasq ≥ 2.86 keeps large `local=` sets compactly (CI prints dnsmasq's RSS with 150k names;
the proxy's instance holds a second copy). Flash: ~25 bytes a name before UBIFS compression, rewritten once a day.

Both dnsmasq instances (the main one and the proxy's) answer the NXDOMAIN names. The refusals are a
chain of their own (`dns_guard`, prerouting priority mangle − 1) in front of the policy marks and the
proxy's tproxy: a resolver inside a proxied range is refused too, not tunnelled. Only LAN-side bridges
Expand Down Expand Up @@ -243,11 +272,14 @@ mr dns query NAME [TYPE] [SERVER] ask dnsmasq (or SERVER ip[#port]); TYPE A
mr dns leases DHCP leases (JSON)
mr dns release IP [MAC] make dnsmasq drop a DHCPv4 lease
mr dns querylog on [MINUTES]|off|show temporary query logging (default 10 min, max 60)
mr dns adblock status ad blocking: domains, last update, per-list results (JSON)
mr dns adblock update [--cron] download the lists now (--cron: only when due; --no-reload: no restart)
```

Web UI actions (logged-in sessions only): `dns.stats` (GET), `dns.leases` (GET), `dns.release`
(POST `{ip, mac}` — the pair must exist in the lease file and the IP must be inside a LAN network),
`dns.querylog` (GET = state + last 300 lines; POST `{on, minutes}`), `dnslist` (split list editor).
`dns.querylog` (GET = state + last 300 lines; POST `{on, minutes}`), `dnslist` (split list editor), `dns.adblock`
(GET = status; POST `{update: true}` starts an update in the background; API tokens: scope operate).
No handler builds a shell command; `rc-service dnsmasq restart` is the only exec, with fixed argv.

## Checks
Expand All @@ -265,6 +297,11 @@ No handler builds a shell command; `rc-service dnsmasq restart` is the only exec
and → 443 of a listed resolver are refused (IPv4 and IPv6), DoT to a proxied range is refused before
the proxy socket could take it, the router's own 853 and the resolver's other ports still work.
- `mr/mod_dns_sovereignty_test.go`: defaults, validation, blocklist parsing (bad lines named, not echoed).
- `mr/mod_dns_adblock_test.go`: every list format, subdomain folding and allow, validation, render (empty file only
when missing), cron line; updates against a TLS test server: unchanged lists do not restart dnsmasq, `--cron`
skips a fresh file and rebuilds after a settings change, failed / HTML / oversized lists keep the file, a dnsmasq
that does not come back gets the previous file. `tools/ci.d/dns.sh` runs the real update against a local HTTPS
server (150k names) and the real dnsmasq answers them.
- stubby 0.4.3 (Alpine 3.24) accepts the rendered stubby.yml (`stubby -C … -i`, checked once in an
arm64 Alpine container; not part of CI because it needs network access).

Expand All @@ -286,6 +323,10 @@ No handler builds a shell command; `rc-service dnsmasq restart` is the only exec
或全部走 DoT(需同时开启 stubby;NTP 域名会用“引导 DNS”明文解析,保证开机对时)。
- **DHCP 选项**:网络 › DHCP / IPv6 RA › DHCP 选项,按网络设置下发的 DNS、NTP、搜索域和其他编号选项。
- **IPv6**:同页 › IPv6 通告 (RA)。一般保持 SLAAC;需要固定段地址时选“有状态 DHCPv6 + SLAAC”。
- **去广告**:网络 › DNS › 去广告 → 点“+ HaGeZi Multi NORMAL”(或填别的列表地址),打开“启用”,“保存并应用”,
再点“立即更新”。约半分钟后状态显示拦截的域名数。某个网站被误拦:把它的域名加进“白名单”再保存。
- **防止设备绕过路由器的 DNS**:网络 › DNS › 上游与缓存 › 防绕过。Firefox 金丝雀默认开;需要时打开“拦截 DoT /
DoQ”,或填一个 DoH 服务器 IP 列表文件。
- **看缓存命中率 / 排查解析**:网络 › DNS › 统计 / 查询日志。查询日志默认关闭,开启会重启 dnsmasq
(约 1 秒),到时自动关闭,重启路由器也不会保留。

Expand Down
5 changes: 5 additions & 0 deletions examples/lab.d/30-dns.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -65,3 +65,8 @@ dns:
private_relay: block # iCloud Private Relay off on this network
block_dot: true # LAN -> port 853 refused
doh_blocklist_file: @REPO@/mr/testdata/doh.ips # LAN -> 443 of these resolvers refused
adblock: # ad blocking with dnsmasq lists, no new process (tools/ci.d/dns.sh serves these)
enabled: true
lists: ["https://127.0.0.1:8453/ads.txt", "https://127.0.0.1:8453/hosts.txt"]
allow: [cdn.ads.example]
max_domains: 200000
2 changes: 1 addition & 1 deletion mr/api_token.go
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ var tokenActions = map[string]string{
"mon.now": "read", "mon.history": "read", "mon.devices": "read", "mon.conns": "read", "mon.procs": "read", "mon.dmesg": "read",
"sys.services": "read", "sys.time": "read", "sys.doctor": "read", "sys.events": "read", "sys.edge": "read",
// operate: runtime actions that do not change the config
"net.redial": "operate", "wifi.kick": "operate", "wifi.scan": "operate", "dns.release": "operate",
"net.redial": "operate", "wifi.kick": "operate", "wifi.scan": "operate", "dns.release": "operate", "dns.adblock": "operate",
"proxy.delay": "operate", "proxy.select": "operate", "service": "operate", "diag": "operate",
// apply: config changes, through plan → apply → confirm with automatic rollback
"plan": "apply", "validate": "apply", "apply": "apply", "confirm": "apply", "revert": "apply", "rollback": "apply",
Expand Down
1 change: 1 addition & 0 deletions mr/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ module commands (JSON output unless noted):
mr wan status | health WAN state; multi-WAN health
mr wifi status | stations | survey | scan PHY | kick MAC [IFNAME]
mr dns stats | leases | query NAME [TYPE] [SERVER] | release IP [MAC] | querylog on [MIN]|off|show
| adblock status | update ad blocking lists (dns.adblock)
mr proxy status | check | delay [NODE|GROUP] | select GROUP NODE | parse [--secrets] [FILE] | fetch [--secrets] URL|SUB
mr mon now | history | devices | conns [JSON] | procs | dmesg
mr sys run ACTION [TARGET] | backup [-secrets] FILE|- | restore [-confirm SECS] FILE | keys
Expand Down
10 changes: 8 additions & 2 deletions mr/mod_dns.go
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,9 @@ type DNS struct {
Records []Record `yaml:"records"` // local DNS records (home servers)
Split []Split `yaml:"split"` // per-domain upstream (DNS 分流)

// keep LAN devices on the router's DNS (mod_dns_sovereignty.go)
// keep LAN devices on the router's DNS (mod_dns_sovereignty.go); ad blocking (mod_dns_adblock.go)
Sovereignty DNSSovereignty `yaml:"sovereignty"`
Adblock Adblock `yaml:"adblock"`
}

// DoT is the stubby (DNS-over-TLS) forwarder. It listens on 127.0.0.1:Port only.
Expand Down Expand Up @@ -267,7 +268,7 @@ func renderDnsmasq(c *Config) string {
for _, l := range recordLines(c) {
b.WriteString(l + "\n")
}
for _, l := range dnsLocalOnly(c) {
for _, l := range append(dnsLocalOnly(c), adblockLines(c)...) {
b.WriteString(l + "\n")
}
w("dhcp-leasefile=%s", LeaseFile)
Expand Down Expand Up @@ -484,6 +485,7 @@ func init() {
if _, _, err := dohBlocklist(c, true); err != nil {
return err
}
adblockRender(c, out)
out.Add("/etc/dnsmasq.conf", 0644, renderDnsmasq(c))
if c.Services.Stubby.Enabled {
out.Add(StubbyConf, 0644, renderStubby(c))
Expand Down Expand Up @@ -514,6 +516,8 @@ func init() {
return "dnsmasq"
case StubbyConf:
return "stubby"
case adblockConf:
return "dnsmasq"
case "/etc/resolv.conf":
return "-"
}
Expand All @@ -532,6 +536,7 @@ func init() {
"dns.leases": apiDNSLeases,
"dns.release": apiDNSRelease,
"dns.querylog": apiDNSQueryLog,
"dns.adblock": apiDNSAdblock,
},
Commands: map[string]func(c *Config, args []string) error{
"dns": dnsCommand,
Expand Down Expand Up @@ -747,6 +752,7 @@ func dnsValidate(c *Config, v *Validator) {
}
validRecords(c, v)
sovereigntyValidate(c, v)
adblockValidate(c, v)
for _, h := range c.DNS.AddnHosts {
if !rePath.MatchString(h) {
v.Add("dns.addn_hosts: absolute path required, got %q", h)
Expand Down
Loading
Loading