mirror of https://github.com/jmcorgan/fips.git synced 2026-10-05 19:18:25 +00:00

Files

T

Johnathan Corgan 84976b1fa2 fips-gateway: exit when the DNS listener cannot bind or stops

The resolver ran as a detached task whose error was only logged, so a
gateway whose DNS port was taken stayed up with .fips resolution dead
and every health check passing.

The listener is now bound before the address pool, NAT table and routes
are created, and a bind failure exits with status 1. When the port is
already in use, the error names the service most likely to hold it and
how to find the holder with ss or netstat. A resolver task that stops
while the gateway runs also ends the process, after NAT and routes are
torn down, so systemd or procd restarts it or shows it failed.

The resolver now forwards to the upstream address the startup probe
resolved, so an upstream written as a hostname no longer passes the
probe and then kills the resolver.

The dns-resolver harness gains a check that a gateway configured on the
daemon's DNS port exits with the hint before it creates the pool or the
NAT table. The troubleshooting guide describes the new failure, and the
exit-code table no longer lists a control-socket bind failure, which
only warns.

2026-09-27 19:35:48 +00:00

5.4 KiB

Raw Blame History

`fips-gateway`

Long-running service that bridges a LAN segment into the FIPS mesh.

Synopsis

fips-gateway [-c FILE] [-l LEVEL]

Description

fips-gateway runs alongside fips on the same host, reads the same fips.yaml, and exposes two complementary functions to the LAN it fronts:

Outbound (LAN -> mesh). Allocates a virtual IPv6 from a managed pool when a LAN client resolves <npub>.fips, installs nftables DNAT/SNAT/masquerade rules so the client's traffic is rewritten and carried into the mesh through the daemon's fips0 adapter.
Inbound (mesh -> LAN). Installs nftables DNAT and LAN-side masquerade rules so mesh-side traffic arriving on fips0 for the configured listen ports is rewritten to a LAN host:port, per the gateway.port_forwards[] block.

The service runs alongside fips, not as a replacement for it: the daemon must be running on the same host with the TUN adapter and DNS resolver enabled. The gateway is read-only with respect to the daemon's state, and connects to the daemon's resolver only — it is not a peer. For the architecture, see ../design/fips-gateway.md.

fips-gateway is Linux-only. The binary errors out and exits with status 1 on any other platform, since the NAT pipeline is built on nftables and proxy NDP. See Configuration for the platform notes that follow from this.

Options

Flag	Argument	Default	Description
`-c`, `--config`	`FILE`	(default search paths)	Use `FILE` as the configuration. Skips the default search paths.
`-l`, `--log-level`	`LEVEL`	`info`	Tracing level: `trace`, `debug`, `info`, `warn`, `error`. Overridden by `RUST_LOG` if set (see Environment).
`-V`	—	—	Print the short version.
`--version`	—	—	Print the long version (short version plus build target triple).
`-h`, `--help`	—	—	Print usage and exit.

Configuration

fips-gateway reads the same fips.yaml as fips; the gateway is configured under the top-level gateway: block. The block must include at minimum enabled: true, pool, and lan_interface. For each field — pool, LAN interface, DNS listener, conntrack overrides, and inbound port_forwards[] — see the Gateway section of the configuration reference.

The same default search paths apply as for fips (see fips); -c FILE overrides the search. The gateway must be able to read the same configuration file the daemon is reading, or the two will disagree about pool, DNS port, and LAN interface.

For deployment recipes, see ../how-to/deploy-gateway.md (manual Linux host) and ../tutorials/deploy-fips-gateway.md (OpenWrt walk-through).

Exit Codes

Code	Meaning
`0`	Clean shutdown after `SIGINT` / `SIGTERM`.
`1`	Non-Linux platform, configuration load failure, missing or invalid `gateway:` block, the DNS listener could not bind or stopped while running, or NAT/network setup failure. The reason is printed to stderr or the log before exit. A control-socket bind failure is logged as a warning and the gateway continues without the socket.

Environment

Variable	Description
`RUST_LOG`	Tracing filter directive. Takes precedence over `--log-level`. Examples: `info`, `debug`, `fips=trace,fips::gateway=debug`.

Files

Path	Purpose
`/etc/fips/fips.yaml`	Gateway configuration (top-level `gateway:` block). Same file the daemon reads.
`/run/fips/gateway.sock`	Gateway control socket. Hardcoded path; chowned to group `fips` (mode `0770`) at startup so members of that group can query without sudo.
`inet fips_gateway` (nftables)	NAT table the gateway installs and tears down. View with `nft list table inet fips_gateway`.

The gateway also adds and removes a local <pool-cidr> dev lo route in the local routing table so the kernel accepts pool addresses as locally-owned.

Control Socket

fips-gateway exposes a JSON line-protocol control socket separate from the daemon's. The command set (show_gateway, show_mappings) and JSON shapes are documented in the Gateway Command Catalog.

There is no fipsctl subcommand for the gateway — query the socket directly with nc -U, or watch the Gateway tab in fipstop, which polls the gateway socket automatically.

5.4 KiB Raw Blame History

fips-gateway