pbr: add docs/tor.md reference notes

[egc112]

What

Adds docs/tor.md — reference notes on how Tor routing works in pbr — and links it from README.md.

Tor is the one supported "interface" that isn't a network interface, and almost everything about how it behaves has been undocumented. Between them, the docs carried a single line:

Tor tunnels supported in nft mode only (interface name must match tor).

That leaves out the five hardcoded redirect rules, which policy options are discarded, how a destination-based Tor policy depends on dnsmasq, and why a .onion setup can fail silently on a stock OpenWrt — the last of which took a long support thread to get to the bottom of.

Contents

• The mechanism — Tor is a dstnat redirect, not a routed interface: no routing table, no firewall mark, no gateway. What that implies.
• What pbr does, in order — detection, reading the ports from torrc, registering the synthetic interface, turning a policy into five rules, hooking the chain into fw4.
• The five rules — and the consequence that only ports 53, 80 and 443 are ever redirected, so a Tor policy is not a kill switch.
• Source-matched vs domain-matched policies — what each depends on, and why the second brings in a dependency pbr cannot verify.
• Every way a domain-matched .onion policy fails quietly — ten of them, including OpenWrt's /usr/share/dnsmasq/rfc6761.conf declaring .onion local and overriding any server=/onion/127.0.0.1#9053.
• Symptom-driven troubleshooting — starting from the one nslookup pair that splits "Tor is fine, dnsmasq is losing the answer" from "the problem is in Tor".
• Reference torrc, the two valid dnsmasq designs, and the IPv6 TransPort trap.

Why in this repo rather than the docs site

The docs site gets a shorter, user-facing Tor section (see the companion PR below) and links here for the depth. Keeping the fiddly parts in one place stops the two copies drifting — particularly the rfc6761.conf details and the reference torrc, which would otherwise be restated in both.

Packaging

Not packaged. The Makefile installs explicit paths under files/, so docs/ is repo-only and adds nothing to the device.

Note on provenance

The file carries a header stating it was written by Claude from a support-thread investigation, and that while most of it is verified against the source, the dnsmasq and Tor manuals, and tests on a live router, some is inference. Several confident-sounding conclusions during that investigation turned out to be wrong before the real cause surfaced, and the header says so. Happy to soften or drop that if it reads wrong for a repo file.

Companion

mossdef-org/docs.mossdef.org#27 adds the docs-site section that links here. That link points at blob/1.2.3/docs/tor.md, so this PR should merge first or the published link 404s.

🤖 Generated with Claude Code

[egc112]

Closing — tor.md belongs in the docs repository rather than here.

It now lives at pbr/tor.md in mossdef-org/docs.mossdef.org#27, alongside the user-facing Tor section in pbr/1.2.3/README.md that links to it. Keeping both in one repo also removes the cross-repo merge dependency this PR had, and the window where the published link would have 404'd.

No content is lost — the file is unchanged apart from a relative link back to the README section.