laantungir/fips
1
0
Fork 0
mirror of https://github.com/jmcorgan/fips.git synced 2026-10-05 11:08:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
9d5af2bf0656fdcf92f9ad43493976d182bffa40
fips/docs/getting-started.md
T
Johnathan Corgan f0ee81ec7c Prepare the v0.5.1 release content 
Move the staged changelog entries under a 0.5.1 heading dated 2026-09-06,
and add an entry for the deb-install hang: the suite started a oneshot unit
that requires the daemon, so a daemon that could not execute left the start
job undispatched and the suite reported nothing at all. That is the whole
class of fault the suite exists to find, and it protects the run that gates
artifact publication, so it is owed an entry.

Add the release notes and mirror them to the root file. The notes lead with
who should upgrade and who is unaffected, because for most users this
release changes nothing and for Debian 12 and Ubuntu 22.04 users the daemon
has never run at all. They state what was measured and what was not, and
give an objdump line that reads the floor of a binary already installed:
2.34 from this release, 2.39 from any earlier one.

The root mirror is not byte-identical to the versioned copy and cannot be.
The two files sit at different depths, so a link that resolves in one breaks
in the other; the mirror is content-identical with the relative link paths
rewritten, and the check is a diff whose every hunk is a link path. Here
that is two hunks, both confirmed to resolve.

The currency audit found five stale version sites and two claims that do
not match the tree, all corrected here. The status badge, the release-notes
link and the status sentence in the README follow the release, as they did
at v0.4.2. The FreeBSD install line gave a filename that does not exist,
since the tree is 0.5.1-dev; it now takes a version placeholder so it stops
going stale at every bump, and the example above it keeps a concrete name.

The design document recorded the first lookup fix and not the second: it
still said a returning copy is dropped as a duplicate, which the next commit
in this release exists to stop doing. It now names the counter that actually
receives the drop.

The README claimed the .deb is exercised per release. The install suite is
real and covers the five distributions it names, but it runs on push and
pull request, not at a tag, and no workflow installs the published artifact.
The sentence now says that, so the released package being checked by hand is
written down rather than assumed.

Getting-started gains the statement this release should have produced:
which distributions are supported and why the binaries run on all of them.
Until now the policy and the floor lived only in the build environment file,
so an operator had nowhere to read either.
2026-09-06 19:10:43 +00:00

326 lines
13 KiB
Markdown
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, FreeBSD, or Windows host. Linux is the most
exercised platform; macOS, FreeBSD, and Windows installers are
available. The FreeBSD package is built for **x86_64 only**.
- The pre-built installer for your platform (see the project
README's [Quick start](../README.md#quick-start) section for
download links), **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](../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 / rc.d /
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` and `.apk` packages
- macOS: `.pkg` installer
- FreeBSD: native `.pkg` (x86_64 only)
- Windows: `.zip` with service-install scripts
- Generic systemd Linux: `.tar.gz` with an `install.sh` script
FIPS supports every version of a supported distribution that its vendor
still supports for free: currently Ubuntu 22.04, Debian 12, Ubuntu 24.04,
Debian 13 and Ubuntu 26.04. The Linux binaries are built in a container
pinned to the oldest of those, so they run on all of them. The glibc floor
that follows is declared in `packaging/build-floor.env` and is enforced on
every artifact by `testing/check-glibc-floor.sh`.
See the [project README's Quick start section](../README.md#quick-start)
for download links and per-platform invocations.
### FreeBSD
FreeBSD gets a native package built from `packaging/freebsd/`. It
ships `fips`, `fipsctl`, `fipstop`, the `fips` and `fips_dns` rc.d
services, and `.fips` DNS integration. `fips-gateway` is **not**
included: its NAT backend is nftables, which is Linux-only. The
Ethernet and BLE transports are unavailable on FreeBSD; UDP, TCP,
Tor, and Nym are.
**One architecture.** The published artifact is
`fips-<version>-freebsd-amd64.pkg`. There is no aarch64 FreeBSD
build, so on any other architecture use the from-source path below.
```sh
pkg add ./fips-<version>-freebsd-amd64.pkg
cp /usr/local/etc/fips/fips.yaml.sample /usr/local/etc/fips/fips.yaml
sysrc fips_enable=YES fips_dns_enable=YES
service fips start
service fips_dns start
fipsctl show status
```
FreeBSD differs from the Linux layout in three places worth knowing
before you go looking for files:
- Config lives at `/usr/local/etc/fips/fips.yaml`, not `/etc/fips/`.
It installs with sample semantics and mode `0600`, so an edited
file survives `pkg upgrade` and `pkg delete`, and a `nsec:` in it
is not world-readable.
- The daemon runs under `daemon(8)` with pidfile
`/var/run/fips/fips.pid` and logs to `/var/log/fips.log`. The
rc.conf knobs are `fips_config`, `fips_flags`, and
`fips_logfile`.
- The control socket resolves to `/var/run/fips/control.sock`. As on
Linux, a `fips` group is created and its members can run `fipsctl`
and `fipstop` without root (`pw groupmod fips -m <user>`, then
re-login).
Making the local resolver the *system* resolver is a one-time
operator step the package deliberately does not take, and there are
field-tested caveats around unbound upstreams and `/etc/resolv.conf`.
Both are covered in the FreeBSD section of
[packaging/README.md](../packaging/README.md) and in
`packaging/freebsd/README.md`.
### 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.
```sh
git clone https://github.com/jmcorgan/fips.git
cd fips/packaging
make deb # or: tarball, ipk, apk, aur, pkg, freebsd, 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](../packaging/README.md) for per-format
build details, cross-target options, and the full `make` target
list.
### With Nix (flake)
On Nix/NixOS, a [flake](../flake.nix) at the project root builds the
binaries from source with the pinned toolchain and no manual
prerequisite install:
```sh
nix build .#fips # all four binaries, into ./result/bin
nix develop # dev shell with the toolchain + build deps
```
This path produces binaries only — it does not run the installer, so
there are no systemd units, no `fips` group, and no default `fips.yaml`.
On NixOS, wire the daemon in through your system configuration using the
flake's `nixosModules.default` output instead: import it and set
`services.fips.enable = true`. See
[packaging/nixos/README.md](../packaging/nixos/README.md) and the Nix /
NixOS section of [packaging/README.md](../packaging/README.md).
## 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` (Linux only)
**Files placed on disk:**
- `/etc/fips/fips.yaml` — default daemon config (preserved on
upgrade). On macOS and FreeBSD this is
`/usr/local/etc/fips/fips.yaml`.
- `/etc/fips/fips.nft` — mesh-interface nftables baseline (used
only when the firewall service is enabled). Linux only.
- `/etc/fips/fips.d/` — empty drop-in directory for operator
nftables additions. Linux only.
- Systemd, launchd, rc.d, or Windows-service unit files for the
fips services. FreeBSD installs `fips` and `fips_dns` only, since
`fips-gateway` and the nftables firewall service are Linux-only.
**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 at install, and started on the next 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).
The Debian package enables both and starts neither, so a fresh install
leaves them stopped. Start them yourself rather than waiting for a
reboot:
```bash
sudo systemctl start fips fips-dns
```
**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](how-to/enable-mesh-firewall.md).
**What's working once both services are running:**
- 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](tutorials/persistent-identity.md)
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](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](tutorials/join-the-test-mesh.md) 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](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](tutorials/join-the-test-mesh.md) and follow
with
[ipv6-adapter-walkthrough](tutorials/ipv6-adapter-walkthrough.md)
to understand what each piece does, then move on to
[persistent-identity](tutorials/persistent-identity.md) and
the three Nostr-discovery tutorials —
[resolve-peers-via-nostr](tutorials/resolve-peers-via-nostr.md),
[advertise-your-node](tutorials/advertise-your-node.md), and
[open-discovery](tutorials/open-discovery.md) — to give your
node a stable npub, look up peer endpoints, publish your
own, and join the ambient discovery namespace. Then [host-a-service](tutorials/host-a-service.md) for hosting
a service on your node, and [ground-up-mesh](tutorials/ground-up-mesh.md)
for the second deployment mode where two devices peer over
Ethernet, WiFi, or Bluetooth with no IP between them.
### [How-To Guides](how-to/)
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](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](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](design/fips-concepts.md) is a good entry point if
you want the mental model before touching any commands.
Reference in New Issue View Git Blame Copy Permalink