mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-30 19:46:15 +00:00
Johnathan Corgan
5abf9a9325
Restructures /docs/ by reader purpose (tutorials, how-to, reference, design), adds the new-user-progression and operator-recipe content the prior layout lacked, runs an accuracy pass against current source across the pre-existing design docs, and rewrites the gateway feature-set documentation end-to-end around its actual operational profile (a niche feature designed for systems already serving DHCP/DNS to a LAN, with two independent halves — outbound LAN→mesh, inbound mesh→LAN — sharing one nftables table, one binary, and one control socket). Top-level README and getting-started rewritten around two equally-weighted deployment modes (overlay on existing IP networks; ground-up over non-IP transports). ## Additions - 11 new tutorials in docs/tutorials/: an 8-step new-user progression from single-daemon test-mesh peering through to a ground-up two-device mesh, an IPv6-adapter side-trip walkthrough, an Advanced Tutorials index, and a hand-held OpenWrt walk-through for fips-gateway deployment that exercises both halves of the feature. - 12 new how-tos in docs/how-to/: firewall activation, Nostr discovery (resolve / advertise / open across five scenarios), Tor onion (directory + control_port modes), UDP buffer tuning, unprivileged-user setup, persistent identity, host aliases, Bluetooth LE peering, MTU diagnostics, manual Linux-host gateway deployment (covers both halves), gateway troubleshooting (organised by half), and a section index. - 9 new reference docs in docs/reference/: configuration, wire formats, control-socket protocol, four CLI references (fips, fipsctl, fipstop, fips-gateway), security posture matrix, and Nostr events catalog. Configuration and wire-formats are renamed-and-extended from prior design/ versions; the other seven are net-new. - 6 new design docs: fips-concepts, fips-architecture, and fips-prior-work split out of the deleted fips-intro.md; consolidated fips-mmp and fips-mtu aggregations; and a new generic port-advertisement-and-nat-traversal doc (Nostr-signaled port advertisement plus UDP NAT-traversal protocol, FIPS as an example implementation, suitable for eventual NIP submission). - Top-level docs/getting-started.md walking through the binary-installer-only Install story. - packaging/common/hosts pre-populated with the eight public test-mesh nodes so shortnames resolve out of the box on every fresh install. ## Changes - 23 wire-format diagrams relocated to reference/diagrams/ alongside the wire-formats move. - 4 design diagrams corrected against source code (fips-protocol-stack, fips-identity-derivation, fips-coordinate-discovery, fips-routing-decision). - 10 pre-existing design docs reconciled with current source. Numeric corrections: stale link-MMP report bounds (now [1s, 5s] with 200 ms cold-start floor); UDP default MTU (now 1280, IPv6 minimum); node_addr formula (SHA-256(pubkey)[..16]); Noise patterns (IK at link, XK at session); peer-ACL semantics (strict allowlist requires ALL in peers.deny); daemon DNS upstream ([::1]:5354); on-the-wire bloom-filter size (1,071 bytes); obsolete Cargo-feature references (PR #79 dropped them) removed. - Transport framing tightened across the docs: TCP is for UDP-filtered networks (not NAT traversal); Tor is a deployment mode (not failover); WebSocket dropped (not a shipped FIPS transport); WiFi promoted to Implemented via Ethernet in infrastructure mode; classic-Bluetooth row removed (BLE is the only Bluetooth-mode transport). - docs/design/fips-gateway.md rewritten end-to-end to lead with the niche-feature framing and the two-halves structure. Title moved from "FIPS Outbound LAN Gateway" to "FIPS Gateway"; architecture section describes the common machinery (the fips-gateway service, the nftables table, the control socket) before splitting into separate "Outbound Half" and "Inbound Half" sections of equal weight; security considerations split per-half; no Future Work section (speculative directions live in the project tracker, not in protocol design docs). Inbound port forwarding is a first-class half rather than a buried "Implemented Extensions" subsection. - Gateway terminology unified across all gateway docs as a separate Linux service running alongside the fips daemon (its own systemd unit / OpenWrt init script). Container- pattern terms (sidecar) are reserved for the Docker/Kubernetes sidecar deployment examples — the testing/sidecar/ tree, examples/k8s-sidecar/, examples/sidecar-nostr-relay/, examples/wireguard-sidecar-macos/, and the related CHANGELOG / top-level README entries — where the term carries its standard container meaning. - Net-new design body content: rekey section in fips-mesh-layer (Noise IK msg1/msg2 over the established link, K-bit cutover, drain window, smaller-NodeAddr-wins tie-breaker on dual-init); Mesh Size Estimation and Antipoison FPR Cap sections in fips-bloom-filters; Mesh-Interface Query Filter subsection in fips-ipv6-adapter; failure-suppression knobs and clock- skew tolerance in fips-nostr-discovery; loop-rejection and mid-chain ancestor swap added to spanning-tree propagation / stability rules; Priority Chain in fips-mesh-operation renumbered to match the routing-decision diagram. - Top-level README: dropped the stale nostr-discovery cargo-feature parenthetical. docs/README.md and the four section READMEs (tutorials, how-to, reference, design) refreshed for the new structure; index rows reflect both halves of the gateway feature and the new fips-gateway CLI reference. - Cargo.toml [package.metadata.deb] assets path updated for the fips-security.md move; .gitignore /reference/ rule anchored to repo root so docs/reference/ is trackable. - packaging/openwrt-ipk/files/etc/fips/fips.yaml configuration-doc URL updated to the new docs/reference/configuration.md location. ## Deletions - docs/design/fips-intro.md (split into the three new intro design docs). - docs/design/document-relationships.svg (orphan, no longer referenced). - docs/proposals/ tree removed; the only proposal it contained (the Nostr UDP hole-punch protocol) was rewritten as the new generic design/port-advertisement-and-nat-traversal.md.
196 lines
5.8 KiB
Markdown
196 lines
5.8 KiB
Markdown
# Run the FIPS Daemon as an Unprivileged User
|
|
|
|
By default, the FIPS daemon runs as `root` — the shipped Debian
|
|
systemd unit configures this, and no further setup is required.
|
|
The trade-off is that the daemon has full root authority,
|
|
including outside its actual network needs. Acceptable for
|
|
single-purpose hosts; less desirable for shared hosts.
|
|
|
|
This guide covers the alternative: drop privileges and run the
|
|
daemon under a dedicated unprivileged user account. The TUN
|
|
device that the FIPS IPv6 adapter creates requires
|
|
`CAP_NET_ADMIN` on Linux; the recipe below grants that privilege
|
|
via a file capability on the binary, plus everything else the
|
|
daemon needs to keep working without root: a service user
|
|
account, file permissions on the config directory, and a systemd
|
|
unit override to drop privileges.
|
|
|
|
For the design context (why the adapter needs a TUN, how the
|
|
adapter integrates with the kernel routing table), see
|
|
[../design/fips-ipv6-adapter.md](../design/fips-ipv6-adapter.md).
|
|
|
|
## Prerequisites
|
|
|
|
- FIPS package installed (the postinst already creates the `fips`
|
|
system group used for control-socket access).
|
|
- `setcap` available (`apt install libcap2-bin` on Debian/Ubuntu;
|
|
it is a standard utility on most distributions).
|
|
- Operator access to systemd unit overrides (`systemctl edit`).
|
|
|
|
## Step 1: Create a `fips` system user
|
|
|
|
The package creates a `fips` system *group* but no matching user.
|
|
Add a system user that belongs to the `fips` group:
|
|
|
|
```sh
|
|
sudo useradd --system --gid fips --no-create-home --shell /usr/sbin/nologin fips
|
|
```
|
|
|
|
The user has no home directory and no login shell — this account
|
|
exists only to run the daemon.
|
|
|
|
## Step 2: Grant `CAP_NET_ADMIN` to the binary
|
|
|
|
Apply the file capability so the daemon can create the TUN device
|
|
without root authority:
|
|
|
|
```sh
|
|
sudo setcap cap_net_admin+ep /usr/bin/fips
|
|
```
|
|
|
|
Verify:
|
|
|
|
```sh
|
|
getcap /usr/bin/fips
|
|
# /usr/bin/fips cap_net_admin=ep
|
|
```
|
|
|
|
The binary can now create TUN devices when run by any user.
|
|
|
|
**File-capability caveats:**
|
|
|
|
- The capability is attached to the binary file. **Re-applying
|
|
the capability after every package upgrade is required**,
|
|
because package upgrades replace the binary file and lose the
|
|
cap. The systemd override in Step 4 includes an `ExecStartPre`
|
|
line that automates this.
|
|
- File capabilities are stripped when the binary is copied across
|
|
most filesystems and when it is downloaded via web tooling. If
|
|
you build from source and install manually, remember to
|
|
re-`setcap` after each rebuild.
|
|
- `LD_LIBRARY_PATH` and similar environment-driven loader
|
|
controls are stripped at exec time when file capabilities are
|
|
present; this is normally what you want, but development
|
|
workflows that rely on custom library paths may be surprised.
|
|
|
|
## Step 3: Adjust config-file permissions
|
|
|
|
The shipped `/etc/fips/fips.yaml` is mode `0600` and owned by
|
|
`root:root`. The daemon needs to read it and, if persistent
|
|
identity is enabled, write `/etc/fips/fips.key` into the same
|
|
directory.
|
|
|
|
```sh
|
|
sudo chown -R fips:fips /etc/fips
|
|
sudo chmod 0640 /etc/fips/fips.yaml
|
|
```
|
|
|
|
If `node.identity.persistent: true` is set and `fips.key` does
|
|
not exist yet, leave `/etc/fips` itself writable by the `fips`
|
|
user so the daemon can create it on first start. After the key
|
|
file exists, you can tighten further:
|
|
|
|
```sh
|
|
sudo chmod 0600 /etc/fips/fips.key
|
|
```
|
|
|
|
## Step 4: Drop privileges in the systemd unit
|
|
|
|
Create an override:
|
|
|
|
```sh
|
|
sudo systemctl edit fips.service
|
|
```
|
|
|
|
Add:
|
|
|
|
```ini
|
|
[Service]
|
|
User=fips
|
|
Group=fips
|
|
AmbientCapabilities=CAP_NET_ADMIN
|
|
NoNewPrivileges=no
|
|
ExecStartPre=/sbin/setcap cap_net_admin+ep /usr/bin/fips
|
|
```
|
|
|
|
`User=` / `Group=` set the service identity.
|
|
`AmbientCapabilities=` ensures the file capability granted in
|
|
Step 2 actually carries into the daemon's process tree.
|
|
`NoNewPrivileges=no` is required for file-capability execution
|
|
to work — systemd defaults this to `yes` for hardened units,
|
|
which would block the `setcap` from taking effect.
|
|
`ExecStartPre=` re-applies the capability before each start,
|
|
which makes the package-upgrade path self-heal.
|
|
|
|
The unit's `RuntimeDirectory=fips` directive already arranges
|
|
for `/run/fips/` to be created with the right ownership at
|
|
service start, now as `fips:fips 0750` instead of
|
|
`root:fips 0750`.
|
|
|
|
Reload and restart:
|
|
|
|
```sh
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl restart fips
|
|
```
|
|
|
|
## Step 5: Verify
|
|
|
|
Confirm the daemon is running as `fips`:
|
|
|
|
```sh
|
|
ps -eo user,cmd | grep '[/]usr/bin/fips'
|
|
# fips /usr/bin/fips --config /etc/fips/fips.yaml
|
|
```
|
|
|
|
Confirm the TUN device came up (the `setcap` worked):
|
|
|
|
```sh
|
|
ip link show fips0
|
|
# fips0: <POINTOPOINT,UP,...> mtu 1280 ...
|
|
```
|
|
|
|
Confirm the control socket is bound and accessible to the `fips`
|
|
group:
|
|
|
|
```sh
|
|
ls -la /run/fips/control.sock
|
|
# srwxrwx--- 1 fips fips ... /run/fips/control.sock
|
|
```
|
|
|
|
Add yourself to the `fips` group so you can use `fipsctl` /
|
|
`fipstop` without `sudo`:
|
|
|
|
```sh
|
|
sudo usermod -aG fips $USER
|
|
# log out and back in for the group change to take effect
|
|
```
|
|
|
|
Then:
|
|
|
|
```sh
|
|
fipsctl show node
|
|
```
|
|
|
|
## Caveats
|
|
|
|
- **`fips-firewall.service` still runs as root.** Loading nftables
|
|
rules into the kernel requires root regardless. The firewall
|
|
unit is intentionally separate from the daemon unit.
|
|
- **Bluetooth peers (`transports.ble.*`)** require additional
|
|
privileges the `CAP_NET_ADMIN` setcap doesn't cover. If you use
|
|
the BLE transport, you'll likely need to keep running as root
|
|
or layer additional capability/D-Bus configuration; that path
|
|
is not covered here.
|
|
|
|
## See also
|
|
|
|
- [persistent-identity.md](persistent-identity.md) — how the
|
|
daemon manages `/etc/fips/fips.key`
|
|
- [../design/fips-ipv6-adapter.md](../design/fips-ipv6-adapter.md)
|
|
— IPv6 adapter design, TUN interface architecture
|
|
- [../reference/security.md](../reference/security.md) —
|
|
consolidated security surface
|
|
- [../reference/configuration.md](../reference/configuration.md)
|
|
— `tun.*` configuration block
|