Johnathan Corgan
6a564e26ac
Everything the release needs except the version number, which stays at 0.5.0-dev until the tag. The changelog entry covers only the work that is new on this line. The point release's forty-six entries arrived under their own heading with the forward merge and are left alone; the twenty that remained are regrouped by topic and eight more added for changes no entry covered. Three of those eight matter to someone upgrading. Five root modules and four re-exports left the public library surface and Node::connections narrowed, none of it recorded anywhere; the entry names what to use instead and distinguishes the removed connection-phase enum from the Noise type of the same name, which is a different type that still exists. Tracing targets moved, so an existing RUST_LOG filter stops matching rather than erroring. And the handshake resend interval key no longer governs the first resend, which is now a constant, though it still governs later ones. Seven more entries cover the work that landed after the first content pass was written: the experimental native datagram API, the fipsctl probe diagnostic, per-instance transport addressing, the app-owned UDP socket seam, and the connect, disconnect and path-MTU fixes. The four bug fixes among them all reach the deployed line, so the release notes no longer claim this release carries exactly one fix for a shipped bug; it carries four. There is no security section, because after the split every security entry belongs to the point release. The release notes say so plainly rather than leaving a reader upgrading across both releases to conclude this one carries no security work. The notes are organized by audience, since the release spans OpenWrt routers, embedders, FreeBSD, and the existing platforms, and a single list serves none of them. The native datagram API is given a section of its own rather than folded into the embedding seam: it is a client-facing API rather than a way to host a node, and its one rule with no Berkeley-socket counterpart, that the v1 wire carries no half-close, needs to be somewhere a client author will read it. FreeBSD is advertised as supported on x86_64 only, stated wherever the platform appears. Android is advertised as an embedding seam and not as a supported platform: a compile-gated library surface with no artifact and no host application guide. The configuration table rename is carried through every shipped file that taught the old spelling: nine documentation files, the OpenWrt sample config and a test generator, twenty-two sites in all. Guides written this same cycle were among them, which is how the omission was found. The documentation that arrived with the native API was checked for the same omission and was already clean. The compatibility tests keep the old spelling deliberately, since they exist to test the fold. The changelog section is the fold of master's [Unreleased], not a snapshot of it. An earlier version of this commit took a copy that then drifted, so each section ended up holding a bullet the other did not and re-folding them would have picked a winner silently. Both causes were fixed on master instead — the NixOS module had never been recorded there, and the pre-release batch of fixes was new — so [Unreleased] is a strict superset and this is a copy rather than a merge. [0.5.0] carries all forty-six bullets byte for byte, [Unreleased] is empty, and [0.4.2] is untouched, checked by hashing it against master's copy. The BLE work landed after the content pass and gets one summary entry in the changelog and one section in the release notes rather than nine bullets: the ble_available gate replacing target_os = "linux", packet-boundary recovery for stream-oriented backends, peer recognition by node identity instead of a rotating link address, the L2CAP PSM moving into the backend seam and onto the advertisement, the embedder-supplied Android radio, bounded probe retry, and inbound handshakes moved off the accept loop. The two release-notes copies no longer share their link paths. Relative links resolve from one directory only, so the seven written for docs/releases/ all 404ed from the root copy. The root copy now uses paths from the repository root and the versioned copy keeps the ../ form; both sets were resolved against the tree. The same two links are broken the same way in the v0.4.0 through v0.4.2 notes, left as shipped history. The contributor tallies are re-derived against maint..HEAD rather than adjusted: twenty commits from outside the project and 171 from me, with Arjen at fifteen and fr34aky at two. An earlier count of twelve and 138 was carried from a measurement taken three days before this content was written, and the BLE branch widened the gap after it. Arjen's NixOS flake module, the UDP sin6_scope_id fix and most of the BLE rework were uncredited, as was fr34aky's L2CAP PSM seam. They want one last re-derive at tag time if anything lands before the tag. A sweep of all 99 tracked markdown files against the tree corrected fifty-three of them. Four told the reader to run a build.sh that does not exist; the only harness builder is testing/scripts/build.sh. The BLE build prerequisites were described as optional on the strength of a probe that build.rs does not perform, and bluez was named a build prerequisite when libdbus-sys asks only for libdbus-1-dev and pkg-config and bluez is the runtime daemon. Link cost is the primary sort key in next-hop ranking, not reserved for future use; Ethernet runs on macOS as well as Linux; the BLE MTU is the L2CAP CoC MTU rather than a negotiated ATT_MTU; effective Ethernet MTU is 1497; the LAN discovery subsystem is src/mdns and eight citations still named a src/discovery that never existed here. The connectivity states in three tutorials were invented, and their jq filters matched nothing including healthy peers. One command filtered on a literal fd97: address prefix, which only the first byte of fixes, so it returned empty for all but one reader in 256 and every later step using the variable failed silently. transports.tor.advertise_on_nostr was undocumented despite being validated against node.rendezvous.nostr.enabled. The transport design document gains the BLE section it never had, written from the source: the backend cascade and its compile_error tripwire, the platform gate, the PSM advertisement wire layout and the byte budget that forces a 16-bit service-data key, and the probe and admission bounds. Three source files carried the same class of staleness and are corrected with the documentation: the OpenWrt ipk usage line and Makefile error text both named a packaging/openwrt that does not exist, and chaos.sh parsed --subnet without listing it. Folded in with the content commit, having been prepared alongside it: The three GitHub Action pins that had gone stale. Every third-party action is pinned to a commit SHA, nothing reports that a pin has aged, and re-resolving all ten against their tags found dorny/test-reporter@v2, taiki-e/install-action@v2 and vmactions/freebsd-vm@v1 had moved. The three install-action@nextest references stay unpinned, since that action reads the tool to install from the ref name. check-action-pins.sh passes at 75 references and all nine workflow files parse. The lockfile refresh, which is the mutating half of the dependency sweep. Thirty-six packages move to their latest semver-compatible versions and every one is transitive; nothing declared in Cargo.toml changes version. No advisory forces any of them. It was taken before the validation battery, because a gate run against a lockfile that later moves proves nothing about what ships. The sha2 0.10 to 0.11, hkdf 0.12 to 0.13 and bech32 0.11 to 0.12 majors, three of the four deferred at v0.4.0 for change surface rather than security. All three land with no source change. sha2 and hkdf must move together, since both depend on digest 0.11, and neither changes an algorithm. That matters because the chaining-key KDF in the Noise handshake is built on Hkdf::<Sha256>, where an output change would be a wire break rather than a compile error; no known-answer vectors exist for that path, so the wire-compatibility gate is what covers it. secp256k1 0.31 is deliberately absent, since nostr's own requirement would leave two copies of the ECC library in the tree. The README support matrix, rebuilt as one feature table broken out by Linux variety. A single Linux column hid that Debian, Ubuntu, Arch and NixOS are one glibc build differing in packaging, that OpenWrt is musl and drops BLE, and that Android is not a daemon platform. Transport rows sort by how many platforms carry them. A Native API row reads its platform set from the cfg gates. The installer row becomes a package format row naming the artifact, and only the .deb is exercised per release. Four changelog and release-note gaps the BLE re-walk found: a Bluetooth LE bullet stranded inside the released 0.4.2 section, a missing Fixed entry for the scan and probe loop counting a pool-refused connection as an established link, the unnamed embedder call that installs an application-owned radio, and the fact that stopping the transport now stops scanning as well as advertising. Three release-document gaps found walking the unsurveyed commits: the UDP reuse-flag fix stated in the direction opposite to the one it was made, with the silent second-daemon bind it prevents left unsaid; the corrected native-API socket paragraph carried into both release-note copies, which still named SOCK_SEQPACKET on FreeBSD and two kernels where three are handled; and the coordinate-cache hardening, which shipped with no text anywhere despite adding four operator-visible status fields. That last entry states plainly that the checks are mitigations and not a closure, since the coordinate is still not authenticated. Also folded in, the documentation pass that followed the content commit: A stage-pipeline diagram for the probe, embedded in the fipsctl reference under the five-stage list. It draws the five stages left to right with each stage's failure reasons below it, and the bypass that skips both lookup stages when the coordinates are cached or the target is a direct peer. Its branches come from the probe state machine rather than from the report, so the path stage is drawn as the one failure that does not stop the probe. A rewrite of the README's "What FIPS does" section. It now opens with what a machine running FIPS gets, rather than with the two deployment modes, and gives the self-organizing and permissionless property its own paragraph since it holds for both modes. A regrouping of the README's feature list into the mesh, getting traffic onto it, and running a node, with a bullet added for the native datagram API, which had none despite sitting in the support matrix. The Quick start now leads with the released packages rather than a source build. It also fixes a real defect: the package enables fips.service and fips-dns.service and starts neither on a fresh install, so .fips name resolution was silently dead until the next reboot and neither page said to start the service. A rewrite of the release notes. They opened with seven subsections of upgrade caveats and reached the first feature two hundred lines in; they now open with a summary of the release and elaborate below it in the same order. Android is stated as supported through an embedded crate rather than as a standalone daemon, consistently across all three documents. The OpenWrt pair is corrected: it is 802.11s between routers with FIPS supplying encryption, authentication and routing, plus a convention of an open !FIPS SSID a client joins over WiFi, not meshing over a router's own radios. The probe's path output is described as the least-common-ancestor walk, which is the worst-case fallback route rather than the route a packet takes. Detail that did not change what a reader does was cut from the notes and kept in the changelog.
13 KiB
Make Your Node's Identity Persistent
After completing join-the-test-mesh, your daemon is connected to the public test mesh — but its identity is ephemeral. Every restart generates a fresh Nostr keypair, so the npub the rest of the world would use to reach you changes every time. This tutorial walks through pinning your node to a stable keypair, locating it on disk, and protecting it.
The whole exercise should take about ten minutes.
What you'll build
┌─────────────────────────────────────────┐
│ /etc/fips/fips.yaml │
│ node: │
│ identity: │
│ persistent: true ← this flag │
└────────────────┬────────────────────────┘
│ daemon reads on start
▼
┌─────────────────────────────────────────┐
│ /etc/fips/fips.key 0600 root:root │
│ /etc/fips/fips.pub 0644 root:root │
└─────────────────────────────────────────┘
your stable nsec / npub
The diagram shows the Linux layout. On macOS the same three files
live under /usr/local/etc/fips/; read
Where these files live before running any
command below.
After this tutorial your node will have:
- A keypair on disk that the daemon reuses across restarts.
- An npub you can hand to other operators so they can add you to
their
peers:list once and have the entry keep working. - A clear understanding of which file holds the secret and how to keep it that way.
Where these files live
Every path in this tutorial is written in its Linux form. macOS and
FreeBSD install config and keys under /usr/local/etc/fips/ instead
of /etc/fips/, so on those platforms substitute as you go:
| Linux / other Unix | macOS / FreeBSD |
|---|---|
/etc/fips/fips.yaml |
/usr/local/etc/fips/fips.yaml |
/etc/fips/fips.key |
/usr/local/etc/fips/fips.key |
/etc/fips/fips.pub |
/usr/local/etc/fips/fips.pub |
fipsctl keygen writes to /usr/local/etc/fips/ by default on
macOS. The daemon still probes /etc/fips/fips.yaml as a fallback,
so an existing install is not broken by an upgrade, but the macOS
packaging only installs files under /usr/local/etc/fips/. If a
macOS host already carries key files at the old /etc/fips/ path,
the daemon uses the old key and warns rather than minting a new
identity; the migration recipe is in the
how-to guide.
Why a stable identity matters
In FIPS your Nostr keypair is your node's identity in the most literal sense. Several things derive from it:
- Your
fd97:...mesh address — derived from the public key. - Your
<npub>.fipsDNS name — the npub itself with.fipsappended. - Every authenticated connection — Noise IK at the mesh layer, XK at the session layer, both prove you hold the matching secret key.
A keypair, briefly. Nostr identities are secp256k1 keypairs. The private half is the
nsec(a bech32-encoded secret key); the public half is thenpub(a bech32-encoded public key). The daemon needs thensecto sign messages and complete handshakes; the rest of the world only sees thenpuband uses it as your address.
The daemon supports two ways of holding that keypair:
Ephemeral vs. persistent.
- Ephemeral (the default): the daemon mints a brand-new keypair every time it starts, kept only in memory. No long-term secret is ever written to disk; nothing on your machine ties one run to the next; the npub your daemon presents to the network is fresh on every restart. This is the safe-by-default posture — your node has no persistent identity unless you explicitly ask for one.
- Persistent: the daemon reads (or, on first start, generates and writes) a keypair stored at
/etc/fips/fips.key(/usr/local/etc/fips/fips.keyon macOS). The npub stays the same across restarts, reboots, and reinstalls as long as that file is preserved. You take on the cost of protecting an on-disk secret in exchange for being addressable by a stable name.
Persistent identity is a deliberate trade. You give up the ephemeral default's privacy posture — once your npub is stable, every connection your node makes is correlatable across time — and you take on a real secret-management responsibility. In return you get two things you can't get any other way:
- Other operators can reference you by npub. In
join-the-test-mesh you added
test-us01to yourpeers:list by its npub. That entry only works becausetest-us01's npub doesn't change. If anyone is going to reach you the same way, your npub has to be just as stable. - Services on your node get a fixed address. The
host-a-service tutorial walks through
running an HTTP server addressable as
<your-npub>.fips. Clients reach the service by that name; if your npub changes on every restart, every client's address book breaks.
Both of these are good reasons. Neither is automatic — if your node is purely a client, reaching out to others without hosting anything itself, you may legitimately want to stay on the ephemeral default. The rest of this tutorial assumes you've decided you want a stable identity.
Step 1: Note your current ephemeral npub
Before changing anything, capture the npub the daemon is using right now so you can compare against it after the switch.
sudo fipsctl show status | grep '"npub"'
You'll see one line like:
"npub": "npub1abc...xyz"
Make a note of it. We expect this to change.
Step 2: Enable persistent identity in the config
Open /etc/fips/fips.yaml (/usr/local/etc/fips/fips.yaml on
macOS) and find the node: block. The shipped default has the
relevant fragment commented out; make it look like this:
node:
identity:
persistent: true
Save the file. That is the only configuration change.
The daemon's behavior on the next restart:
- If
/etc/fips/fips.keyalready exists, load it and use that identity. - If it does not exist, generate a fresh keypair, write it to
/etc/fips/fips.{key,pub}with the correct file modes, and use that.
The daemon derives the key directory from whichever config file it
loaded, so on macOS both files land in /usr/local/etc/fips/.
Step 3: Restart the daemon
sudo systemctl restart fips
sudo systemctl status fips
Status should show active (running) within a couple of
seconds. Confirm the new identity is in use:
sudo fipsctl show status | grep '"npub"'
The npub should be different from the one in Step 1 — the daemon discarded the old in-memory ephemeral keypair and minted a new one which it has now persisted to disk. From here forward this is your npub.
Step 4: Locate the keypair on disk
The daemon wrote two files:
sudo ls -l /etc/fips/fips.key /etc/fips/fips.pub
On macOS, list /usr/local/etc/fips/fips.key and
/usr/local/etc/fips/fips.pub instead.
Expect:
-rw------- 1 root root ... fips.key
-rw-r--r-- 1 root root ... fips.pub
The public file is safe to share — it is your address:
sudo cat /etc/fips/fips.pub
This must match the npub reported by sudo fipsctl show status. Hand this string to anyone you want to be reachable
from; they paste it into their own peers: block as the npub:
field.
The private file is the secret. Do not cat or paste its
contents anywhere — there is no reason to see it, and any line
of shell history or screen capture that contains it has captured
the secret.
Step 5: Verify it survives a restart
Restart once more to confirm the daemon is reading fips.key
rather than re-generating it:
sudo systemctl restart fips
sudo fipsctl show status | grep '"npub"'
The npub should match Step 3 exactly. If it does not, the daemon
was unable to read fips.key (most likely a permission problem)
— see Troubleshooting.
Step 6: Protect the nsec
fips.key is the only thing standing between you and someone
else impersonating your node. The daemon ships it with the right
permissions; the operator's job is to keep them that way.
What that means in practice:
- Do not loosen the file mode.
0600(read/write for owner only — hereroot) is correct;chmod 0644to "fix" a permission error puts the secret on display to every account on the host. - Do not commit it to source control. If you maintain
configuration in a Git repo, exclude
fips.key; if you use ansible-vault or a similar mechanism, encrypt it.fips.pubmay be checked in freely. - Do not paste it into chat or email. Operators sometimes
share config snippets to demonstrate a setup; redact the
contents of
fips.keyto a placeholder before doing so. - Back it up the way you back up an SSH host key. Treat the
file (or its contents) the same way you would treat
/etc/ssh/ssh_host_ed25519_key: encrypted, offline, available to recover the same identity if the host disappears.
There is no in-protocol "key change" message in FIPS. If
fips.key is lost, the npub is lost — your node will come back
up with a new identity and every downstream reference to the
old one will be stale.
What you've learned
- Identity = keypair. Every FIPS node is a Nostr keypair; the npub is its address, the nsec is its credential.
- The flag.
node.identity.persistent: truein/etc/fips/fips.yamlis the difference between ephemeral and persistent identity. - Where it lives.
/etc/fips/fips.keyand/etc/fips/fips.pub, mode0600and0644, ownedroot:root; under/usr/local/etc/fips/on macOS. - What to share.
fips.pubis public;fips.keyis not. - What it buys you. A npub other operators can add to their
peers:list once, and that addresses the services your node will eventually run.
Troubleshooting
If the post-restart npub does not match fips.pub:
- Check file permissions.
sudo ls -l /etc/fips/fips.key, orsudo ls -l /usr/local/etc/fips/fips.keyon macOS. If the mode is not0600or the owner is notroot:root, the daemon may have refused to read it. Restore withsudo chmod 0600 /etc/fips/fips.key && sudo chown root:root /etc/fips/fips.key, substituting the macOS path where it applies. - Check the journal.
sudo journalctl -u fips -n 100after the restart will show one of:Loaded persistent identity from key file path=...— good.Generated persistent identity, saved to key file ...— also good, but only expected on the first start after the flag flip.Using ephemeral identity (new keypair each start)— the config flag was not picked up; re-check the indentation of thepersistent: trueline.
If you see Generated persistent identity... on every start,
the file is being written but not read on subsequent starts;
this is almost always the same permission/path issue.
What's next
-
Resolve peer addresses via Nostr. resolve-peers-via-nostr walks through the smallest useful step toward Nostr-mediated discovery: keep your peer entry, drop its hard-coded address, and let the daemon look up the current endpoint from public Nostr relays. The first of three tutorials covering Nostr discovery; advertising your own node and open ambient discovery come next.
-
Reach services on other mesh nodes. reach-mesh-services drives
nc,traceroute6,curl, andsshat peers by.fipsname and shows that the FIPS data plane is just IPv6 from an application's point of view. -
Host a service of your own. host-a-service walks through bringing up an HTTP server addressable as
<your-npub>.fips, bound tofips0so the exposure is mesh-only, behind the mesh firewall.
For the alternative provisioning paths — minting a keypair with
fipsctl keygen before the daemon ever starts, or importing an
existing Nostr nsec — and the key-rotation procedure, see the
operator-style recipe at
../how-to/persistent-identity.md.
For the full identity model:
- ../design/fips-architecture.md
— how npubs become
NodeAddrs and IPv6 ULAs.