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.
174 lines
6.1 KiB
Markdown
174 lines
6.1 KiB
Markdown
# Use Shortnames Instead of Long Npubs
|
|
|
|
A FIPS node's canonical address is `<npub>.fips`. The npub is
|
|
63 characters of bech32 — fine for the daemon, awkward to type
|
|
or fit in a docs example. The local DNS resolver consults a
|
|
host map before falling back to direct-npub resolution, so
|
|
short names like `test-us01.fips` work as substitutes wherever
|
|
`<npub>.fips` would.
|
|
|
|
This guide covers the two ways to populate that map and when
|
|
to use which.
|
|
|
|
## When to use which
|
|
|
|
Two independent mechanisms feed the same DNS responder:
|
|
|
|
| Mechanism | Source | Scope | Reload |
|
|
|-----------|--------|-------|--------|
|
|
| Hosts file | `/etc/fips/hosts` | Node-local, intended for shared rosters | Auto on mtime change |
|
|
| Peer alias | `alias:` field on a `peers:` entry | Node-local, scoped to configured peers | Daemon restart |
|
|
|
|
Pick the hosts file when:
|
|
|
|
- The shortname refers to a peer your operator-team agrees to
|
|
call by that name across machines (the public test mesh
|
|
ships this way).
|
|
- You want the destination's name to resolve in DNS or appear
|
|
in `fipsctl show peers` display even though it isn't in your
|
|
`peers:` block — e.g., a mesh node you reach transitively
|
|
through your direct peers. The hosts-file entry is for name
|
|
resolution and display only; it does not stand in for the
|
|
npub a peer-config entry requires.
|
|
|
|
Pick the peer alias when:
|
|
|
|
- The shortname is just a label *you* use locally for a peer
|
|
that's already in your `peers:` block.
|
|
- You want the alias to live with the rest of the peer config
|
|
(one place to look) rather than in a separate file.
|
|
|
|
The two coexist. If both reference the same shortname,
|
|
`/etc/fips/hosts` wins — the file is treated as the
|
|
authoritative shared roster.
|
|
|
|
## What ships in the default `/etc/fips/hosts`
|
|
|
|
The installer drops `/etc/fips/hosts` populated with the
|
|
public test mesh roster:
|
|
|
|
```text
|
|
test-us01 npub1qmc3cvfz0yu2hx96nq3gp55zdan2qclealn7xshgr448d3nh6lks7zel98
|
|
test-us02 npub10yffd020a4ag8zcy75f9pruq3rnghvvhd5hphl9s62zgp35s560qrksp9u
|
|
test-us03 npub136yqae6na688fs75g95ppps3lxe07fvxefj77938zf47uhm6074sxw8ctm
|
|
test-us03-next npub15m6c4ghuegx4pcde6tra8f7smn8vfv2wundyxwhkjynuerkrzmgsy09sh3
|
|
test-us04 npub1gd7ye2qp2lphhzx75fynnjzaxx4dqanddecet0wtt5ss5ek8h9ps62wdkf
|
|
test-de01 npub1260n42s06vzc7796w0fh3ny7zcpw6tlk4gq3940gmfrzl5c9pv2s3657q8
|
|
test-es01 npub17lpmzulpc98d8ff727k6e98atxn3phzupzsqqwe54ytduym747ws4tw5zm
|
|
test-uk01 npub1u0z26dc4qeneu5rvwvmpfhtwh3522ed6rlgxr9jarrfnjrc6ew4qxjysrs
|
|
```
|
|
|
|
These resolve out of the box — `ping6 test-us01.fips` works
|
|
even before you've added any peer to your config, as long as
|
|
the destination is reachable through your mesh links.
|
|
|
|
If you don't intend to interact with the public test mesh,
|
|
the entries are safe to comment out or delete. They are
|
|
plain hosts-file lines, not protocol participants — removing
|
|
them only changes name resolution on your machine.
|
|
|
|
## Add an entry to `/etc/fips/hosts`
|
|
|
|
Append a line to `/etc/fips/hosts`:
|
|
|
|
```text
|
|
my-laptop npub1abc...xyz
|
|
```
|
|
|
|
Format rules:
|
|
|
|
- One hostname and one npub per line, separated by
|
|
whitespace.
|
|
- Hostnames are lowercase letters, digits, and hyphens; max
|
|
63 characters.
|
|
- Comments start with `#` and continue to end of line; blank
|
|
lines are ignored.
|
|
- On duplicate hostnames, the last entry wins.
|
|
|
|
The daemon picks up the change on the next DNS query — no
|
|
restart required (the file's mtime is checked on each query).
|
|
Verify:
|
|
|
|
```sh
|
|
dig my-laptop.fips AAAA +short
|
|
```
|
|
|
|
Expect one `fd97:...` AAAA record.
|
|
|
|
`/etc/fips/hosts` is shipped as a dpkg conffile (and the AUR
|
|
equivalent), so package upgrades preserve your edits. The
|
|
file is `0644 root:root` — readable by anyone, writable by
|
|
root.
|
|
|
|
## Add a peer alias
|
|
|
|
In `/etc/fips/fips.yaml`, set the `alias:` field on the peer
|
|
entry:
|
|
|
|
```yaml
|
|
peers:
|
|
- npub: "npub1abc...xyz"
|
|
alias: "my-laptop"
|
|
addresses:
|
|
- transport: udp
|
|
addr: "192.0.2.10:2121"
|
|
connect_policy: auto_connect
|
|
```
|
|
|
|
Restart the daemon for the alias to take effect:
|
|
|
|
```sh
|
|
sudo systemctl restart fips
|
|
dig my-laptop.fips AAAA +short
|
|
```
|
|
|
|
The alias also shows up in `fipsctl show peers` `display_name`
|
|
column, so log entries and CLI output reference the peer by
|
|
shortname instead of truncated npub.
|
|
|
|
## Resolution order
|
|
|
|
When the DNS responder receives a query for `<name>.fips`:
|
|
|
|
1. **Hosts file lookup.** If `<name>` matches an entry in
|
|
`/etc/fips/hosts`, the daemon returns the AAAA record
|
|
derived from that entry's npub.
|
|
2. **Peer alias lookup.** If `<name>` matches the `alias`
|
|
field on a configured peer, return that peer's AAAA.
|
|
3. **Direct npub resolution.** If `<name>` is itself a valid
|
|
bech32 npub (the canonical 63-char `npub1...` form), the
|
|
daemon returns the AAAA derived from that npub directly.
|
|
4. **NXDOMAIN.** If none of the above match, the query
|
|
returns no answer.
|
|
|
|
The order means the hosts file overrides peer aliases on
|
|
conflict. That's deliberate: the file represents
|
|
operator-shared naming, the peer alias is a node-local label.
|
|
|
|
## Cross-references and ACLs
|
|
|
|
Aliases interact with the peer ACL — if you maintain
|
|
`peers.allow` or `peers.deny` lists keyed on hostnames rather
|
|
than npubs, those names go through the same hosts-file
|
|
resolution. See
|
|
[../reference/security.md](../reference/security.md) for the
|
|
ACL format and the alias-resolution semantics.
|
|
|
|
`fipsctl connect` and `fipsctl disconnect` accept a shortname
|
|
where they expect an npub. Resolution for these commands goes
|
|
through `/etc/fips/hosts` only — peer-config `alias:` entries
|
|
are not loaded by `fipsctl`, so a shortname that exists only as
|
|
a peer alias must still be referenced by full npub on the CLI.
|
|
See [../reference/cli-fipsctl.md](../reference/cli-fipsctl.md).
|
|
|
|
## See also
|
|
|
|
- [../reference/configuration.md § Host Mapping](../reference/configuration.md#host-mapping)
|
|
— minimal reference entry for the host-map mechanism.
|
|
- [../reference/cli-fipsctl.md](../reference/cli-fipsctl.md)
|
|
— `fipsctl` arguments that accept shortnames.
|
|
- [../reference/security.md](../reference/security.md)
|
|
— peer ACL semantics with aliased entries.
|
|
- [../design/fips-ipv6-adapter.md](../design/fips-ipv6-adapter.md)
|
|
— the DNS resolver design and the npub-to-IPv6 derivation.
|