mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-04 05:46:14 +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.
149 lines
6.6 KiB
Markdown
149 lines
6.6 KiB
Markdown
# `fipsctl`
|
|
|
|
Command-line client for the FIPS daemon's control socket.
|
|
|
|
## Synopsis
|
|
|
|
```text
|
|
fipsctl [-s SOCKET] <subcommand> [args...]
|
|
```
|
|
|
|
## Description
|
|
|
|
`fipsctl` connects to a running daemon over its control socket
|
|
(Unix domain socket on Linux/macOS, TCP loopback on Windows), sends
|
|
one JSON request, and pretty-prints the response. Exits with a
|
|
non-zero status if the socket cannot be reached, the daemon returns an
|
|
error, or the request times out.
|
|
|
|
`fipsctl keygen` is a special case: it does not contact the daemon and
|
|
operates purely on local files.
|
|
|
|
For the line-delimited JSON wire protocol, see
|
|
[control-socket.md](control-socket.md). For the YAML configuration
|
|
that defines the socket location, see
|
|
[configuration.md](configuration.md).
|
|
|
|
## Global Options
|
|
|
|
| Flag | Argument | Description |
|
|
| ---- | -------- | ----------- |
|
|
| `-s`, `--socket` | `PATH` | Override the control-socket path (Linux/macOS) or TCP port (Windows). |
|
|
| `-V`, `--version` | — | Print the short version. |
|
|
| `--version` | — | Print the long version. |
|
|
| `-h`, `--help` | — | Print usage and exit. Per-subcommand help via `fipsctl <subcommand> --help`. |
|
|
|
|
## Subcommands
|
|
|
|
### `show <what>`
|
|
|
|
Read-only queries against the daemon. Each subcommand maps 1:1 to a
|
|
control-socket query (see [control-socket.md](control-socket.md)) and
|
|
prints the response's `data` object as pretty JSON.
|
|
|
|
| Subcommand | Control-socket command | Returns |
|
|
| ---------- | ---------------------- | ------- |
|
|
| `show status` | `show_status` | Node-level status: identity, version, peer/link/session counts, TUN state, recent sparklines. |
|
|
| `show peers` | `show_peers` | Authenticated peer list with link IDs, transport addresses, MMP metrics, Noise/rekey state. |
|
|
| `show links` | `show_links` | Active links (one per FMP-authenticated peer): direction, state, byte counters. |
|
|
| `show tree` | `show_tree` | Spanning-tree state: root, my coordinates, parent, peer declarations. |
|
|
| `show sessions` | `show_sessions` | End-to-end FSP sessions: state, traffic counters, session-MMP metrics, path MTU. |
|
|
| `show bloom` | `show_bloom` | Bloom-filter state: own filter sequence, leaf dependents, per-peer filter summaries. |
|
|
| `show mmp` | `show_mmp` | MMP metrics summary: per-peer link-layer metrics and per-session session-layer metrics. |
|
|
| `show cache` | `show_cache` | Coordinate cache: TTL, fill ratio, per-destination coords and path MTU. |
|
|
| `show connections` | `show_connections` | Pending handshake connections: state, idle time, resend count. |
|
|
| `show transports` | `show_transports` | Transport instances: type, state, MTU, local address, per-transport stats. |
|
|
| `show routing` | `show_routing` | Routing summary: pending lookups, retry state, forwarding/discovery/error/congestion counters. |
|
|
| `show identity-cache` | `show_identity_cache` | Cached `(node_addr → npub)` entries with last-seen timestamps. |
|
|
|
|
### `acl <what>`
|
|
|
|
| Subcommand | Control-socket command | Returns |
|
|
| ---------- | ---------------------- | ------- |
|
|
| `acl show` | `show_acl` | Loaded peer-ACL state: allow/deny files, effective mode, default decision, entry counts. |
|
|
|
|
### `stats <what>`
|
|
|
|
Time-series metrics from the in-process history rings.
|
|
|
|
| Subcommand | Control-socket command | Description |
|
|
| ---------- | ---------------------- | ----------- |
|
|
| `stats list` | `show_stats_list` | Enumerate available metrics, their units, and the per-ring retention windows. |
|
|
| `stats peers` | `show_stats_peers` | List peers tracked in stats history (active or recently active). |
|
|
| `stats history <metric> [options]` | `show_stats_history` | Fetch a time-series window for one metric. |
|
|
|
|
`stats history` options:
|
|
|
|
| Flag | Argument | Default | Description |
|
|
| ---- | -------- | ------- | ----------- |
|
|
| `--peer` | `npub` or hostname | *(none)* | Required for per-peer metrics; resolves through `/etc/fips/hosts` if not an npub. |
|
|
| `--window` | `<N>s` / `<N>m` / `<N>h` | `10m` | Window duration. |
|
|
| `--granularity` | `1s` or `1m` | `1s` | Ring resolution. `1s` uses the fast ring; `1m` uses the slow ring. |
|
|
| `--plot` | — | off | Render a Unicode-block sparkline to stdout instead of JSON. |
|
|
|
|
### `keygen [options]`
|
|
|
|
Generate a new FIPS identity keypair locally. Does not contact the
|
|
daemon.
|
|
|
|
| Flag | Argument | Default | Description |
|
|
| ---- | -------- | ------- | ----------- |
|
|
| `-d`, `--dir` | `DIR` | `/etc/fips` (Unix), `%APPDATA%\fips` (Windows) | Output directory for `fips.key` and `fips.pub`. |
|
|
| `-f`, `--force` | — | off | Overwrite an existing `fips.key`. |
|
|
| `-s`, `--stdout` | — | off | Print `nsec` then `npub` to stdout instead of writing files. |
|
|
|
|
`fips.key` is written with mode `0600` and `fips.pub` with mode `0644`
|
|
on Unix. After running `keygen`, set `node.identity.persistent: true`
|
|
in `fips.yaml` or the daemon will overwrite the keys on next start.
|
|
|
|
### `connect <peer> <address> <transport>`
|
|
|
|
Tell the daemon to dial a peer over a specific transport.
|
|
|
|
| Argument | Description |
|
|
| -------- | ----------- |
|
|
| `peer` | npub (bech32) or hostname from `/etc/fips/hosts`. |
|
|
| `address` | Transport endpoint, e.g. `192.168.1.10:2121`, `[2001:db8::1]:2121`, or a Tor onion. FIPS-mesh ULAs (`fd00::/8`) are rejected for the IP-based transports (udp, tcp, ethernet). |
|
|
| `transport` | One of `udp`, `tcp`, `tor`, `ethernet`. |
|
|
|
|
### `disconnect <peer>`
|
|
|
|
Tell the daemon to drop a peer link.
|
|
|
|
| Argument | Description |
|
|
| -------- | ----------- |
|
|
| `peer` | npub (bech32) or hostname from `/etc/fips/hosts`. |
|
|
|
|
## Exit Codes
|
|
|
|
| Code | Meaning |
|
|
| ---- | ------- |
|
|
| `0` | Daemon returned `{"status":"ok",...}`. |
|
|
| `1` | Argument parse failure, control-socket connection failure, daemon returned `{"status":"error",...}`, or local I/O failure (keygen). The error message is printed to stderr. |
|
|
|
|
## Environment
|
|
|
|
| Variable | Description |
|
|
| -------- | ----------- |
|
|
| `XDG_RUNTIME_DIR` | Used to derive the default control-socket path when `/run/fips` is absent. |
|
|
|
|
`fipsctl` does not consume `RUST_LOG`; logging is for the daemon.
|
|
|
|
## Files
|
|
|
|
| Path | Purpose |
|
|
| ---- | ------- |
|
|
| `/etc/fips/hosts` | Maps hostnames to npubs for the `connect`, `disconnect`, and `--peer` arguments. See [configuration.md](configuration.md). |
|
|
| Control socket (default) | Same resolution as the daemon: `/run/fips/control.sock` if present, else `$XDG_RUNTIME_DIR/fips/control.sock`, else `/tmp/fips-control.sock` (Unix); TCP `localhost:21210` (Windows). |
|
|
|
|
If you get `Permission denied` connecting to the socket on Linux,
|
|
add your user to the `fips` group (`sudo usermod -aG fips $USER`)
|
|
and log out and back in.
|
|
|
|
## See also
|
|
|
|
- [`fips`](cli-fips.md) — the daemon.
|
|
- [`fipstop`](cli-fipstop.md) — live-status TUI.
|
|
- [control-socket.md](control-socket.md) — wire protocol.
|
|
- [configuration.md](configuration.md) — YAML reference.
|