mirror of https://github.com/jmcorgan/fips.git synced 2026-07-30 19:46:15 +00:00

Files

T

Johnathan Corgan 5abf9a9325 docs: four-section /docs/ restructure with new-user content, accuracy pass, and gateway feature-set rewrite

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.

2026-05-08 03:02:12 +00:00

9.2 KiB

Raw Blame History

Getting Started with FIPS

FIPS (Free Internetworking Peering System) is a self-organizing encrypted mesh network built on Nostr identities. Your machine becomes a node in the mesh with a self-generated cryptographic identity, and existing networking software — SSH, web servers, file transfer, anything IPv6-native — runs over the mesh unchanged.

There are two common ways to deploy FIPS, and the rest of this guide and the linked docs branch accordingly:

As an overlay on top of existing IP networks (Ethernet, WiFi, the public internet, Tor), FIPS lets your node reach any other peer regardless of NAT, ISP, or physical location.
From the ground up over non-IP transports — raw Ethernet, WiFi, Bluetooth — FIPS provides a complete permissionless network without any pre-existing IP infrastructure, ISP, or DNS.

The two paths share a lot of common ground — install, identity, configuration. They diverge mainly in transport setup and the deployment topology you choose.

There is no central server. Any node can run; any pair of running nodes can mesh.

What you'll need

A Linux, macOS, or Windows host. Linux is the most exercised platform; macOS and Windows installers are available.
The pre-built installer for your platform (see the Releases page), or a source checkout if you want to build the installer yourself.
For the source-build path only: a working Rust toolchain (the version pinned in rust-toolchain.toml is auto-installed by rustup), and the platform-specific build dependencies listed in packaging/README.md.

Install

FIPS is installed by running a binary installer for your platform. The installer drops the daemon and CLI tools into system locations, installs systemd / launchd / Windows-service unit files, places a default fips.yaml, and creates the fips system group. There is no cargo install path: the daemon needs more than just binaries copied into place.

You can either build the installer yourself from source, or download a pre-built one from the release distribution. Both paths produce the same installer artifacts and the same post-install state.

From the release distribution

The most direct path. The release distribution carries a per-platform installer:

Debian/Ubuntu — .deb package
Arch Linux — fips AUR package
OpenWrt — .ipk package
macOS — .pkg installer
Windows — .zip with service-install scripts
Generic systemd Linux — .tar.gz with an install.sh script

See the project README's Installation section for download links and per-platform invocations.

From source

For development, custom builds, or unsupported architectures. The packaging/ tree builds the same installer formats locally; you then apply the resulting installer the same way you would a downloaded one.

git clone https://github.com/jmcorgan/fips.git
cd fips/packaging
make deb         # or: tarball, ipk, aur, pkg, zip, all

The resulting installer lands in deploy/ at the project root. Apply it the same way you would a downloaded one (for example sudo dpkg -i deploy/fips_*.deb on Debian/Ubuntu).

See packaging/README.md for per-format build details, cross-target options, and the full make target list.

What's installed and running

Here's what the installer leaves on your machine, what's running, and what you'll need to set up yourself.

Binaries installed system-wide:

fips (daemon)
fipsctl (control-socket client)
fipstop (live-status TUI)
fips-gateway

Files placed on disk:

/etc/fips/fips.yaml — default daemon config (preserved on upgrade).
/etc/fips/fips.nft — mesh-interface nftables baseline (used only when the firewall service is enabled).
/etc/fips/fips.d/ — empty drop-in directory for operator nftables additions.
Systemd, launchd, or Windows-service unit files for the four fips services.

System changes:

A fips system group is created. Add your user to it (sudo usermod -aG fips $USER, then re-login) to run fipsctl and fipstop without sudo.
The runtime directory /run/fips/ exists with mode 0750 root:fips.

Services enabled and started on boot:

fips.service — the daemon. Brings up the fips0 TUN adapter, listens on the configured transports, and exposes the control socket at /run/fips/control.sock.
fips-dns.service — wires .fips hostname resolution into the host resolver (a /etc/systemd/resolved.conf.d/ drop-in pointing at [::1]:5354 on systemd hosts).

Services installed but not enabled (operator opt-in):

fips-firewall.service — applies /etc/fips/fips.nft to the mesh interface. See how-to/enable-mesh-firewall.md.

What's working out of the box:

The daemon is running with a fresh ephemeral identity — a new Nostr keypair is generated on every start.
The fips0 TUN adapter exists with the daemon's mesh address.
The daemon's transport listeners are up: UDP 0.0.0.0:2121 and TCP 0.0.0.0:8443. They are inert at this point because no other node knows your daemon's npub yet — see "What's not yet configured" below.
.fips hostname resolution is plumbed into the host resolver.

What's not yet configured — these are what guide your next steps:

No peers. The daemon has nobody to talk to until you add a static peer entry, enable Nostr-mediated discovery, or bring up a transport (Ethernet, Bluetooth) where peers find each other automatically on the same physical link.
Ephemeral identity. Your node's npub changes every restart. The persistent-identity tutorial walks through pinning the daemon to a stable Nostr keypair for any node others will reference by name.
Mesh firewall not active. Inbound exposure on fips0 follows the host's existing firewall rules until you enable the baseline service.

Reaching mesh nodes by name

A FIPS node is identified by its Nostr public key (npub1...). For ordinary IP software running over the mesh — SSH, web browsers, ping, file transfer — use the form <npub>.fips as the destination; the local .fips resolver translates that to the corresponding mesh IPv6 address so the FIPS node can be found. The resolver runs entirely on your machine and does not generate any external DNS traffic.

For shorter forms, the resolver also consults two host maps before falling back to direct npub lookup: /etc/fips/hosts (shipped pre-populated with the public test mesh roster, and freely editable for your own entries) and the alias: field on configured peers in fips.yaml. So test-us01.fips, my-laptop.fips, or any other shortname you map resolves the same way <npub>.fips does. See how-to/host-aliases.md for the full mechanics.

Join the test mesh

The fastest way to see FIPS in action is to connect your daemon to the public FIPS test mesh. The Join the Test Mesh tutorial walks through adding a single static peer entry, watching the link come up, and reaching both that peer and a second mesh node forwarded through it — a ten-minute exercise that demonstrates the central FIPS guarantee that one good peer connects you to the rest of the mesh.

Where to go next

Documentation is organised into four sections, each with a different job. Pick the one that matches what you want to do.

Tutorials

Step-by-step lessons that take you from zero to a working setup. Read these end-to-end. Start with Join the Test Mesh and follow with ipv6-adapter-walkthrough to understand what each piece does, then move on to persistent-identity and the three Nostr-discovery tutorials — resolve-peers-via-nostr, advertise-your-node, and open-discovery — to give your node a stable npub, look up peer endpoints, publish your own, and join the ambient discovery namespace. Then host-a-service for hosting a service on your node, and ground-up-mesh for the second deployment mode where two devices peer over Ethernet, WiFi, or Bluetooth with no IP between them.

How-To Guides

Task-oriented recipes for operators with a specific goal: enable a firewall, deploy the LAN gateway, set up Bluetooth peering, diagnose an MTU problem, configure persistent identity. Each guide takes the shortest correct path from "I want to do X" to "X is done".

Reference

Lookup material consulted on demand: wire formats, configuration keys, command-line flags, control-socket commands. Austere by design; no guidance on when to use a feature.

Design

Architectural and protocol-level explanations: the mesh layer, the session layer, the spanning tree, Bloom-filter discovery, the unified MTU model, the IPv6 adapter. Read these to understand why FIPS makes the choices it does.

The design section's fips-concepts.md is a good entry point if you want the mental model before touching any commands.

9.2 KiB Raw Blame History