fips/docs/tutorials/persistent-identity.md

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. The macOS package (.pkg) installs config and keys under /usr/local/etc/fips/ instead of /etc/fips/, so on macOS substitute as you go:

Linux / other Unix	macOS
/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>.fips DNS name — the npub itself with .fips appended.
• 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 the npub (a bech32-encoded public key). The daemon needs the nsec to sign messages and complete handshakes; the rest of the world only sees the npub and 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.key on 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:

1. Other operators can reference you by npub. In join-the-test-mesh you added test-us01 to your peers: list by its npub. That entry only works because test-us01's npub doesn't change. If anyone is going to reach you the same way, your npub has to be just as stable.
2. 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.key already 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 — here root) is correct; chmod 0644 to "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.pub may 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.key to 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: true in /etc/fips/fips.yaml is the difference between ephemeral and persistent identity.
• Where it lives. /etc/fips/fips.key and /etc/fips/fips.pub, mode 0600 and 0644, owned root:root; under /usr/local/etc/fips/ on macOS.
• What to share. fips.pub is public; fips.key is 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, or sudo ls -l /usr/local/etc/fips/fips.key on macOS. If the mode is not 0600 or the owner is not root:root, the daemon may have refused to read it. Restore with sudo 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 100 after 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 the persistent: true line.

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, and ssh at peers by .fips name 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 to fips0 so 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.