Johnathan Corgan
6a564e26ac
Everything the release needs except the version number, which stays at 0.5.0-dev until the tag. The changelog entry covers only the work that is new on this line. The point release's forty-six entries arrived under their own heading with the forward merge and are left alone; the twenty that remained are regrouped by topic and eight more added for changes no entry covered. Three of those eight matter to someone upgrading. Five root modules and four re-exports left the public library surface and Node::connections narrowed, none of it recorded anywhere; the entry names what to use instead and distinguishes the removed connection-phase enum from the Noise type of the same name, which is a different type that still exists. Tracing targets moved, so an existing RUST_LOG filter stops matching rather than erroring. And the handshake resend interval key no longer governs the first resend, which is now a constant, though it still governs later ones. Seven more entries cover the work that landed after the first content pass was written: the experimental native datagram API, the fipsctl probe diagnostic, per-instance transport addressing, the app-owned UDP socket seam, and the connect, disconnect and path-MTU fixes. The four bug fixes among them all reach the deployed line, so the release notes no longer claim this release carries exactly one fix for a shipped bug; it carries four. There is no security section, because after the split every security entry belongs to the point release. The release notes say so plainly rather than leaving a reader upgrading across both releases to conclude this one carries no security work. The notes are organized by audience, since the release spans OpenWrt routers, embedders, FreeBSD, and the existing platforms, and a single list serves none of them. The native datagram API is given a section of its own rather than folded into the embedding seam: it is a client-facing API rather than a way to host a node, and its one rule with no Berkeley-socket counterpart, that the v1 wire carries no half-close, needs to be somewhere a client author will read it. FreeBSD is advertised as supported on x86_64 only, stated wherever the platform appears. Android is advertised as an embedding seam and not as a supported platform: a compile-gated library surface with no artifact and no host application guide. The configuration table rename is carried through every shipped file that taught the old spelling: nine documentation files, the OpenWrt sample config and a test generator, twenty-two sites in all. Guides written this same cycle were among them, which is how the omission was found. The documentation that arrived with the native API was checked for the same omission and was already clean. The compatibility tests keep the old spelling deliberately, since they exist to test the fold. The changelog section is the fold of master's [Unreleased], not a snapshot of it. An earlier version of this commit took a copy that then drifted, so each section ended up holding a bullet the other did not and re-folding them would have picked a winner silently. Both causes were fixed on master instead — the NixOS module had never been recorded there, and the pre-release batch of fixes was new — so [Unreleased] is a strict superset and this is a copy rather than a merge. [0.5.0] carries all forty-six bullets byte for byte, [Unreleased] is empty, and [0.4.2] is untouched, checked by hashing it against master's copy. The BLE work landed after the content pass and gets one summary entry in the changelog and one section in the release notes rather than nine bullets: the ble_available gate replacing target_os = "linux", packet-boundary recovery for stream-oriented backends, peer recognition by node identity instead of a rotating link address, the L2CAP PSM moving into the backend seam and onto the advertisement, the embedder-supplied Android radio, bounded probe retry, and inbound handshakes moved off the accept loop. The two release-notes copies no longer share their link paths. Relative links resolve from one directory only, so the seven written for docs/releases/ all 404ed from the root copy. The root copy now uses paths from the repository root and the versioned copy keeps the ../ form; both sets were resolved against the tree. The same two links are broken the same way in the v0.4.0 through v0.4.2 notes, left as shipped history. The contributor tallies are re-derived against maint..HEAD rather than adjusted: twenty commits from outside the project and 171 from me, with Arjen at fifteen and fr34aky at two. An earlier count of twelve and 138 was carried from a measurement taken three days before this content was written, and the BLE branch widened the gap after it. Arjen's NixOS flake module, the UDP sin6_scope_id fix and most of the BLE rework were uncredited, as was fr34aky's L2CAP PSM seam. They want one last re-derive at tag time if anything lands before the tag. A sweep of all 99 tracked markdown files against the tree corrected fifty-three of them. Four told the reader to run a build.sh that does not exist; the only harness builder is testing/scripts/build.sh. The BLE build prerequisites were described as optional on the strength of a probe that build.rs does not perform, and bluez was named a build prerequisite when libdbus-sys asks only for libdbus-1-dev and pkg-config and bluez is the runtime daemon. Link cost is the primary sort key in next-hop ranking, not reserved for future use; Ethernet runs on macOS as well as Linux; the BLE MTU is the L2CAP CoC MTU rather than a negotiated ATT_MTU; effective Ethernet MTU is 1497; the LAN discovery subsystem is src/mdns and eight citations still named a src/discovery that never existed here. The connectivity states in three tutorials were invented, and their jq filters matched nothing including healthy peers. One command filtered on a literal fd97: address prefix, which only the first byte of fixes, so it returned empty for all but one reader in 256 and every later step using the variable failed silently. transports.tor.advertise_on_nostr was undocumented despite being validated against node.rendezvous.nostr.enabled. The transport design document gains the BLE section it never had, written from the source: the backend cascade and its compile_error tripwire, the platform gate, the PSM advertisement wire layout and the byte budget that forces a 16-bit service-data key, and the probe and admission bounds. Three source files carried the same class of staleness and are corrected with the documentation: the OpenWrt ipk usage line and Makefile error text both named a packaging/openwrt that does not exist, and chaos.sh parsed --subnet without listing it. Folded in with the content commit, having been prepared alongside it: The three GitHub Action pins that had gone stale. Every third-party action is pinned to a commit SHA, nothing reports that a pin has aged, and re-resolving all ten against their tags found dorny/test-reporter@v2, taiki-e/install-action@v2 and vmactions/freebsd-vm@v1 had moved. The three install-action@nextest references stay unpinned, since that action reads the tool to install from the ref name. check-action-pins.sh passes at 75 references and all nine workflow files parse. The lockfile refresh, which is the mutating half of the dependency sweep. Thirty-six packages move to their latest semver-compatible versions and every one is transitive; nothing declared in Cargo.toml changes version. No advisory forces any of them. It was taken before the validation battery, because a gate run against a lockfile that later moves proves nothing about what ships. The sha2 0.10 to 0.11, hkdf 0.12 to 0.13 and bech32 0.11 to 0.12 majors, three of the four deferred at v0.4.0 for change surface rather than security. All three land with no source change. sha2 and hkdf must move together, since both depend on digest 0.11, and neither changes an algorithm. That matters because the chaining-key KDF in the Noise handshake is built on Hkdf::<Sha256>, where an output change would be a wire break rather than a compile error; no known-answer vectors exist for that path, so the wire-compatibility gate is what covers it. secp256k1 0.31 is deliberately absent, since nostr's own requirement would leave two copies of the ECC library in the tree. The README support matrix, rebuilt as one feature table broken out by Linux variety. A single Linux column hid that Debian, Ubuntu, Arch and NixOS are one glibc build differing in packaging, that OpenWrt is musl and drops BLE, and that Android is not a daemon platform. Transport rows sort by how many platforms carry them. A Native API row reads its platform set from the cfg gates. The installer row becomes a package format row naming the artifact, and only the .deb is exercised per release. Four changelog and release-note gaps the BLE re-walk found: a Bluetooth LE bullet stranded inside the released 0.4.2 section, a missing Fixed entry for the scan and probe loop counting a pool-refused connection as an established link, the unnamed embedder call that installs an application-owned radio, and the fact that stopping the transport now stops scanning as well as advertising. Three release-document gaps found walking the unsurveyed commits: the UDP reuse-flag fix stated in the direction opposite to the one it was made, with the silent second-daemon bind it prevents left unsaid; the corrected native-API socket paragraph carried into both release-note copies, which still named SOCK_SEQPACKET on FreeBSD and two kernels where three are handled; and the coordinate-cache hardening, which shipped with no text anywhere despite adding four operator-visible status fields. That last entry states plainly that the checks are mitigations and not a closure, since the coordinate is still not authenticated. Also folded in, the documentation pass that followed the content commit: A stage-pipeline diagram for the probe, embedded in the fipsctl reference under the five-stage list. It draws the five stages left to right with each stage's failure reasons below it, and the bypass that skips both lookup stages when the coordinates are cached or the target is a direct peer. Its branches come from the probe state machine rather than from the report, so the path stage is drawn as the one failure that does not stop the probe. A rewrite of the README's "What FIPS does" section. It now opens with what a machine running FIPS gets, rather than with the two deployment modes, and gives the self-organizing and permissionless property its own paragraph since it holds for both modes. A regrouping of the README's feature list into the mesh, getting traffic onto it, and running a node, with a bullet added for the native datagram API, which had none despite sitting in the support matrix. The Quick start now leads with the released packages rather than a source build. It also fixes a real defect: the package enables fips.service and fips-dns.service and starts neither on a fresh install, so .fips name resolution was silently dead until the next reboot and neither page said to start the service. A rewrite of the release notes. They opened with seven subsections of upgrade caveats and reached the first feature two hundred lines in; they now open with a summary of the release and elaborate below it in the same order. Android is stated as supported through an embedded crate rather than as a standalone daemon, consistently across all three documents. The OpenWrt pair is corrected: it is 802.11s between routers with FIPS supplying encryption, authentication and routing, plus a convention of an open !FIPS SSID a client joins over WiFi, not meshing over a router's own radios. The probe's path output is described as the least-common-ancestor walk, which is the worst-case fallback route rather than the route a packet takes. Detail that did not change what a reader does was cut from the notes and kept in the changelog.
20 KiB
Deploy a fips-gateway on an OpenWrt AP
In every other tutorial in this set you put FIPS on the host that
needs to talk to the mesh. This one is the exception. Here you stand
up a fips-gateway on an OpenWrt access point so the unmodified LAN
behind it — phones, laptops, smart-home gear — can reach mesh
destinations by <npub>.fips without any FIPS software of their own,
and so a service running on a LAN box can be exposed to mesh peers
through a port forward. Two halves, one binary, one config.
This is advanced material. It assumes you have already worked
through join-the-test-mesh on some other
machine, you understand what <npub>.fips means, and now you want to
fold an existing LAN into the mesh from the edge router rather than
installing FIPS on every device. The whole exercise should take about
forty-five minutes.
What you'll build
┌──────────────────────────────────────────────────────────────┐
│ OpenWrt access point │
│ │
│ br-lan ┌──────────────┐ fips0 ┌──────────────┐ │
│ (LAN side) ◀──│ fips-gateway │──────────▶│ fips daemon │ │
│ │ (service) │ │ │──┼─▶ mesh
│ │ │ fd97:.. │ fd97:.. │ │
│ │ fd01::/112 │ │ │ │
│ │ pool │ │ │ │
│ └──────┬───────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ nftables NAT │
│ (inet fips_gateway) │
└─────────────────┬────────────────────────────────────────────┘
│ br-lan
▼
┌──────────────────────────────────────────────┐
│ LAN clients (phones, laptops, smart-home) │
│ │
│ no FIPS install — just IPv6 + DNS │
│ ▲ │
│ │ curl http://test-us01.fips/ │
│ └────── DNS to dnsmasq ──▶ gateway DNS │
│ │
└──────────────────────────────────────────────┘
By the end you will have:
- An OpenWrt AP whose LAN clients can fetch
http://test-us01.fips/with no FIPS software installed on them. - An inbound port forward exposing one LAN service to the mesh as
<your-gateway-npub>.fips:<port>. - An understanding of which LAN-side glue OpenWrt automates for you (DNS forwarding, RA route, IPv6 prefix) and which the operator owns (port forwards, mesh firewall).
Why an OpenWrt AP
The gateway has very specific dependencies on the box it runs on. It
needs to own DNS for the LAN, it needs to advertise an IPv6 route to
the LAN, it needs a stable LAN-side interface, and it needs to be the
default IPv6 router for the segment. An OpenWrt-based access point
already does all of those things — it runs dnsmasq, it runs
odhcpd for IPv6 RA, it owns br-lan, and clients are already using
it as their gateway. The OpenWrt ipk leans into that: the gateway:
block in /etc/fips/fips.yaml is pre-populated, and the
/etc/init.d/fips-gateway init script wires up the LAN-side glue
automatically when you start the service.
On a non-OpenWrt host the same integration is manual; that path is covered by ../how-to/deploy-gateway.md.
Prerequisites
- An OpenWrt 22.03+ AP serving DHCP and DNS to a wired or wireless LAN segment.
- The FIPS ipk installed and a working FIPS daemon on the AP. If you haven't done that yet, follow ../../packaging/openwrt-ipk/README.md for the install, then come back here.
- The AP joined to the mesh — at least one healthy peer link. If it isn't, work through join-the-test-mesh on the AP first.
- Root SSH to the AP. Every command in this tutorial runs on the AP.
- A LAN client (phone, laptop) to test the outbound half from.
Step 1: Verify the FIPS daemon is up
Confirm the daemon is running, the TUN is up, and at least one mesh peer is reachable:
service fips status
ip -6 addr show fips0
fipsctl show peers
You should see:
service fips statusreportsrunning.fips0exists and has oneinet6 fd97:...address. That is the AP's mesh-side identity.fipsctl show peerslists at least one peer with active connectivity (notidle/ not zero bytes).
Confirm the AP can resolve a known mesh node by name:
ping6 -c 2 test-us01.fips
If any of these fail, fix the daemon side first — the gateway is a separate service that runs alongside a working daemon, not a substitute for one.
Step 2: Inspect the pre-populated gateway config
The OpenWrt ipk ships /etc/fips/fips.yaml with the gateway: block
already filled in. View the relevant section:
sed -n '/^gateway:/,$p' /etc/fips/fips.yaml
You will see roughly:
gateway:
enabled: true
pool: "fd01::/112" # virtual IP range (up to 65535 addresses)
lan_interface: "br-lan" # LAN-facing interface for proxy NDP
dns:
listen: "[::1]:5353" # gateway DNS bind (IPv6 loopback only)
upstream: "[::1]:5354" # FIPS daemon DNS resolver (matches daemon default)
ttl: 60 # DNS TTL and mapping lifetime (seconds)
pool_grace_period: 60 # seconds after last session before reclaiming
Three things to notice:
pool: "fd01::/112"— the virtual-IP CIDR the gateway hands out to LAN clients. 65 536 addresses, the gateway's hard cap. Pick a differentfdXX::/Nprefix iffd01::/112collides with anything on your network.lan_interface: "br-lan"— the OpenWrt LAN bridge. The gateway installs proxy-NDP entries on this interface so LAN clients can ARP-equivalent for pool addresses.dns.listen: "[::1]:5353"— the gateway's DNS bind, pinned to IPv6 loopback only. dnsmasq, which owns LAN port 53, forwards.fipsqueries to it. The init script wires up that forwarding; you don't bind to a LAN address yourself.
For the full reference, see ../reference/configuration.md § Gateway.
Step 3: Enable and start fips-gateway
The service is shipped disabled — enable it once and start it:
service fips-gateway enable
service fips-gateway start
Behind that single command, the init script
(/etc/init.d/fips-gateway) does five things:
- Loads gateway sysctls.
net.ipv6.conf.all.proxy_ndp=1andnet.ipv6.conf.all.forwarding=1from/etc/sysctl.d/fips-gateway.conf. - Reconfigures dnsmasq via UCI so
.fipsqueries arriving at the LAN's port 53 are forwarded to the gateway's loopback listener on port 5353 instead of going straight to the daemon's resolver on port 5354. (Dnsmasq still owns 53; the gateway sits in front of the daemon for.fipsonly.) - Adds a global-scope IPv6 prefix to
br-lan. Without a non-ULA address on the local interface, Android and Chrome suppress AAAA queries entirely — they assume the LAN has no real IPv6 and don't bother. The init script adds a small benchmarking-range prefix to convince them otherwise. - Adds an RA route for the virtual pool. A UCI
route6entry underdhcptellsodhcpdto advertise the pool CIDR via Router Advertisement (RFC 4191), so LAN clients learn how to reach pool addresses automatically. No per-client static routes needed. - Spawns
fips-gatewayunder procd with--config /etc/fips/fips.yaml, with crash-respawn.
Verify it is running:
service fips-gateway status
logread | grep fips-gateway | tail
Expect a running status and a startup log line of the form
fips-gateway 0.x.y starting, followed by entries for DNS bind, NAT
table install, and pool initialisation.
What just changed on the LAN. The AP is now offering two things it wasn't offering a moment ago: AAAA records under
.fipsthat resolve to virtual IPs infd01::/112, and a route to that CIDR in its Router Advertisements. Existing LAN clients pick both up the next time they re-resolve a name and the next timeodhcpdsends an RA, respectively. No reboot required on the client side.
Step 4: Test the outbound half from a LAN client
Before bringing a LAN client into the picture, confirm from the AP itself that the mesh side is still healthy after the gateway start:
ping6 -c 2 test-us01.fips
This isolates the router-to-mesh path before involving the LAN
segment. If this fails, the troubleshooting target is the daemon /
mesh side, not the gateway-to-client side. If it succeeds and the
LAN-client test below fails, the target is the LAN segment —
proxy_ndp, the RA pool route, or DNS forwarding through dnsmasq.
Now from a phone or laptop on the AP's LAN — anything that does IPv6 and DNS, with no FIPS software installed — try one of the public test mesh nodes:
dig test-us01.fips AAAA
ping6 -c 4 test-us01.fips
curl -6 http://test-us01.fips/
Expectations:
digreturns an AAAA infd01::..., notfd97:.... Thefd01:address is the gateway's virtual-IP allocation; the LAN client never sees the raw mesh address.ping6succeeds. ICMPv6 echo travels through the NAT pipeline and back.curlfetches the page (whatever the test mesh is currently serving ontest-us01).
What just happened end to end. Your client asked dnsmasq for
test-us01.fips. Dnsmasq forwarded the query to the gateway's loopback listener on port 5353. The gateway forwarded the query on to the daemon's resolver on port 5354. The daemon answered withtest-us01's mesh address (fd97:...). The gateway allocated a virtual IP fromfd01::/112, installed nftables DNAT/SNAT/ masquerade rules pinning that virtual IP to the mesh address, installed a proxy-NDP entry onbr-lanso the client could resolve the virtual IP at the link layer, and returned the virtual IP in the AAAA reply. Your client then routed traffic to the virtual IP via the RA-advertised pool route, the AP's kernel rewrote the destination to the mesh address, and the daemon's adapter carried the packets across the mesh. Return traffic followed conntrack back. The client never knew the mesh existed.
Step 5 (optional): Inspect the gateway state
The gateway exposes its own control socket separate from the daemon's. Two useful queries:
echo '{"command":"show_gateway"}' | nc -U /run/fips/gateway.sock
echo '{"command":"show_mappings"}' | nc -U /run/fips/gateway.sock
show_gateway reports pool utilisation, the DNS listen address,
uptime, and the conntrack/NAT counters. show_mappings lists each
allocated virtual IP, the mesh address it points at, the DNS name
that triggered the allocation, and the mapping's lifecycle state
(Allocated, Active, Draining).
For the full command catalog and JSON shapes, see
../reference/control-socket.md § Gateway Command Catalog.
The same data is rendered visually in the Gateway tab of
fipstop.
If you want to see the kernel rules the gateway installed:
nft list table inet fips_gateway
You will see DNAT, SNAT, and masquerade chains populated with one rule per active mapping.
Step 6 (Optional): Add an inbound port-forward for a LAN service
The outbound half is the steady-state use of a gateway. The inbound
half — exposing a LAN service to mesh peers — is a separate decision,
configured per service under gateway.port_forwards[].
For the worked example, run a one-page static web server on the AP
itself, bound to its br-lan address, and expose it to the mesh
through a port-forward. Anything would do — the point of the exercise
is the port-forward, not the service. We use what is already on the
AP: busybox httpd. In a real deployment the LAN-side target would
typically be a separate host (a NAS, a home server, a dev box on the
LAN); the rule shape is identical.
Find the AP's br-lan IPv6 address and save it for the rest of the
step:
BR_LAN_ADDR=$(ip -6 addr show br-lan \
| awk '/inet6 fd|inet6 2/ && !/scope link/ {print $2}' \
| head -1 | cut -d/ -f1)
echo "$BR_LAN_ADDR"
Pick from the global-scope benchmarking prefix the init script added
in Step 3, or your own ULA if br-lan has one — anything except a
link-local fe80::/10 address.
Set up a one-file docroot and start a foreground busybox httpd
bound to that LAN address on port 8000:
mkdir -p /tmp/mesh-demo
echo '<h1>Hello from the mesh-gateway demo</h1>' > /tmp/mesh-demo/index.html
busybox httpd -f -p "[${BR_LAN_ADDR}]:8000" -h /tmp/mesh-demo
Leave it running in this shell. Open a second SSH session on the AP to add the port-forward.
Edit /etc/fips/fips.yaml. Inside the existing gateway: block,
add a port_forwards: list:
gateway:
enabled: true
pool: "fd01::/112"
lan_interface: "br-lan"
dns:
upstream: "[::1]:5354"
ttl: 60
pool_grace_period: 60
port_forwards:
- listen_port: 8080
proto: tcp
target: "[<BR_LAN_ADDR>]:8000"
Substitute the real address for <BR_LAN_ADDR>. The IPv6 form
([addr]:port) is required — IPv4 targets are rejected at config
load.
Restart the gateway so it re-reads the config:
service fips-gateway restart
From any other mesh node, fetch the demo page through the gateway using the AP's npub:
# on the AP, get the npub:
NPUB=$(cat /etc/fips/fips.pub)
echo "$NPUB"
Then on the remote mesh node:
curl -6 "http://${NPUB}.fips:8080/"
Expect:
<h1>Hello from the mesh-gateway demo</h1>
The connection landed on the gateway's fips0 ingress on TCP/8080,
nftables DNAT rewrote the destination to [BR_LAN_ADDR]:8000,
LAN-side masquerade rewrote the source so busybox httpd saw a
LAN-routable address, and the response retraced via conntrack.
What you exposed. With the port-forward active, every mesh peer that can route to your AP can hit
${NPUB}.fips:8080/and reach this service. That is exactly what the inbound half is for — but if you want to scope visibility to a specific subset of peers, the FIPS mesh firewall is the layer that does it; see ../how-to/enable-mesh-firewall.md. The port-forward rule and the firewall rule are independent: the port-forward installs the rewrite; the firewall decides who is allowed to reach the listen port.
Step 7: Tidy up
In the first shell, stop busybox httpd with Ctrl-C. The demo
docroot at /tmp/mesh-demo can stay — it is wiped on reboot — or
remove it now (rm -rf /tmp/mesh-demo).
If you want to keep the outbound half but withdraw the inbound
forward, remove the port_forwards: entry from /etc/fips/fips.yaml
and service fips-gateway restart. The mesh-side listener disappears
and so does the corresponding nftables rule.
To turn the gateway off entirely:
service fips-gateway stop
service fips-gateway disable
The init script's stop_service handler reverses the LAN-side
integration on the way out: dnsmasq's .fips forwarder is pointed
back at the daemon's port 5354, the RA route for the pool is
withdrawn from odhcpd, and the global-scope IPv6 prefix on
br-lan is removed. The LAN reverts to the state it was in before
you ran service fips-gateway start in Step 3.
The daemon and the rest of /etc/fips/ are untouched. Existing mesh
peering on the AP itself continues to work.
What you've learned
- The gateway is a niche feature for a niche box. Most FIPS hosts run the daemon and reach the mesh directly. The gateway exists so an AP can fold an entire unmodified LAN behind it into the mesh in one place.
- Two halves of the same binary. Outbound mode hands LAN clients
virtual IPs and NATs them onto the mesh; inbound mode listens on
fips0and forwards to LAN targets. They share one nftables table, one control socket, and one config block, but each half has its own use case. - OpenWrt does the LAN-side glue for you. The init script reconfigures dnsmasq, installs the RA route, adds the global IPv6 prefix, and loads sysctls. On a non-OpenWrt host that integration is manual — see ../how-to/deploy-gateway.md.
- Inbound forwards stay manual on every distro. The
port_forwards[]block is uniform across hosts, and on every distro you still own the decision of which LAN target to expose and on which mesh-side port. - The mesh firewall is a separate decision. Opening a port
forward on the gateway side does not open it on the firewall
side; if
fips-firewall.serviceis enabled, you still need a drop-in that admits the listen port.
Troubleshooting
If something doesn't work as described above, the operator-recipe guide ../how-to/troubleshoot-gateway.md groups the common failures by symptom:
| Symptom | Where to look |
|---|---|
LAN client gets fd97:..., not fd01:... |
DNS path: dnsmasq still pointing at port 5354. See "DNS queries fail". |
dig succeeds with a pool address but ping6 times out |
Pool route or proxy NDP. See "Virtual IP unreachable from client". |
ping6 works but TCP times out |
NAT pipeline or mesh-side firewall. See "Ping works but TCP does not". |
| Gateway service won't start | "No gateway section in configuration" recipe. |
Inbound curl hits the listen port but never reaches the LAN target |
Mesh-side firewall first, then the port-forward rule. |
The first thing the troubleshoot guide does in any of these cases is
ask the gateway directly via show_gateway and show_mappings. If
the mapping you expect is not there, the failure is on the DNS path;
if it is there in state: Active but traffic still fails, the
failure is downstream.
What's next
- ../how-to/deploy-gateway.md — Manual deployment on a non-OpenWrt Linux host. Same gateway, same config, but you wire up dnsmasq/Unbound/etc. yourself, install a pool route per LAN client (or via your own RA daemon), and manage the systemd unit instead of the procd init script.
- ../design/fips-gateway.md — The design doc: NAT pipeline (DNAT, SNAT, masquerade, inbound DNAT), virtual-IP pool lifecycle (Allocated -> Active -> Draining -> reclaimed), DNS resolution flow, conntrack integration.
- ../reference/configuration.md § Gateway
— Every field of the
gateway:block, including the conntrack timeout overrides not used in this tutorial. - ../reference/cli-fips-gateway.md
— The
fips-gatewaybinary's CLI options, exit codes, and environment variables.