mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-05 19:18:25 +00:00
Johnathan Corgan
84976b1fa2
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.
126 lines
5.4 KiB
Markdown
126 lines
5.4 KiB
Markdown
# `fips-gateway`
|
|
|
|
Long-running service that bridges a LAN segment into the FIPS mesh.
|
|
|
|
## Synopsis
|
|
|
|
```text
|
|
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](../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](#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](#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](configuration.md#gateway-gateway) of the
|
|
configuration reference.
|
|
|
|
The same default search paths apply as for `fips`
|
|
(see [`fips`](cli-fips.md#files)); `-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](../how-to/deploy-gateway.md) (manual
|
|
Linux host) and
|
|
[../tutorials/deploy-fips-gateway.md](../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](control-socket.md#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`](cli-fipstop.md), which polls the gateway socket
|
|
automatically.
|
|
|
|
## See also
|
|
|
|
- [`fips`](cli-fips.md) — the daemon. Required to be running on the
|
|
same host.
|
|
- [`fipstop`](cli-fipstop.md) — the live-status TUI; its Gateway tab
|
|
polls the gateway control socket.
|
|
- [configuration.md § Gateway](configuration.md#gateway-gateway) —
|
|
full `gateway.*` block reference.
|
|
- [control-socket.md § Gateway Command Catalog](control-socket.md#gateway-command-catalog)
|
|
— wire protocol for the gateway socket.
|
|
- [../design/fips-gateway.md](../design/fips-gateway.md) — design,
|
|
NAT pipeline, virtual IP pool lifecycle.
|
|
- [../how-to/deploy-gateway.md](../how-to/deploy-gateway.md) — manual
|
|
Linux deployment.
|
|
- [../how-to/troubleshoot-gateway.md](../how-to/troubleshoot-gateway.md)
|
|
— diagnostic recipes.
|
|
- [../tutorials/deploy-fips-gateway.md](../tutorials/deploy-fips-gateway.md)
|
|
— OpenWrt walk-through.
|