fips/docs/tutorials/join-the-test-mesh.md

Join the FIPS Test Mesh

In this tutorial you will connect your FIPS daemon to a public test peer over UDP, watch the link come up, and reach the peer's mesh address from your machine. By the end you will have seen one complete end-to-end flow — config, handshake, live link, traffic — for a real peer somewhere out on the public internet.

The whole exercise should take about ten minutes. If you have already worked through getting-started.md and have the fips daemon running on your host, you have everything you need.

What you'll build

   ┌────────────────────┐         UDP/IPv4         ┌──────────────────────┐
   │   your fips node   │ ──────────────────────── │      test-us01       │
   │   ephemeral npub   │  test-us01.fips.network  │  npub1qmc3...zel98   │
   │   fips0  fd97:..:Y │           :2121          │   fips0  fd97:..:T   │
   └────────────────────┘                          └──────────────────────┘

Your daemon will peer with one of the public test nodes the project maintains. test-us01 has a stable DNS name, listens on UDP/2121, and is reachable from any network that permits arbitrary outbound UDP.

Peer vs. node. In FIPS terminology, a peer is a node you have a direct link to — same Noise XX handshake, same transport socket. A node is any participant on the mesh, whether you peer with it directly or reach it through one or more hops via your peer's connections. Peering is a local configuration choice; reachability is mesh-wide. One good peer connects you to everyone the rest of the mesh connects to.

After the link to test-us01 establishes, your daemon's fips0 adapter can reach test-us01 itself and — through test-us01's connections — any other node on the test mesh, exactly as if you had a direct connection to each of them.

About the test mesh. The project maintains a small roster of public test nodes (test-us01 through test-uk01) intended for new-user on-ramps and integration testing. They accept inbound peering from arbitrary npubs without prior coordination. A future reference doc will list the full roster; for this tutorial you only need test-us01 as your peer, and test-us02 later on as a second mesh destination to demonstrate forwarding.

Step 1: Confirm the daemon is running

sudo systemctl status fips

Expect active (running). If it is not running, the getting-started guide covers installation and service management. While you're checking, note your daemon's current npub:

sudo fipsctl show status

Look for the npub field. With the default ephemeral-identity config, this regenerates on every restart — that is fine for the tutorial. test-us01 admits any inbound npub.

Step 2: Add a static peer to the daemon config

Edit /etc/fips/fips.yaml. Find the line that reads peers: [] and replace it with:

peers:
  - npub: "npub1qmc3cvfz0yu2hx96nq3gp55zdan2qclealn7xshgr448d3nh6lks7zel98"
    alias: "test-us01"
    addresses:
      - transport: udp
        addr: "test-us01.fips.network:2121"
    connect_policy: auto_connect

What each field does:

• npub — the canonical Nostr public key of test-us01. This is who your daemon will mutually authenticate with over Noise XX.
• alias — a short name your daemon will use when referring to this peer in logs and fipsctl show peers output. Optional.
• addresses — one or more transport endpoints. UDP on the published hostname and port is the most direct path.
• connect_policy: auto_connect — your daemon initiates an outbound connection rather than waiting for the peer to reach in.

Step 3: Restart the daemon

sudo systemctl restart fips

Watch the daemon's journal as it comes back up and dials the peer:

sudo journalctl -u fips -f

Within a few seconds you should see lines mentioning:

• An outbound connection attempt to test-us01 or test-us01.fips.network:2121
• A handshake completion (a "Noise XX link handshake complete" style line, or "peer authenticated" with the test-us01 npub)
• An MMP / link metrics entry naming test-us01

If the handshake does not complete within roughly 30 seconds, jump to Troubleshooting below.

Step 4: Verify the link

sudo fipsctl show peers

Expect one entry whose display_name is test-us01. Useful fields:

• connectivity — should be connected.
• transport_addr — the resolved UDP endpoint your daemon is using to reach test-us01.
• transport_type — udp.
• mmp.srtt_ms — appears once the first MMP report has been exchanged. This is your round-trip time to test-us01.

The transport view confirms your UDP listener and the peer mapping:

sudo fipsctl show transports

Step 5: Ping your peer

test-us01's mesh address derives from its npub. Address it as <npub>.fips and your daemon's local DNS responder will translate that to its fd97:... mesh address.

First see the resolved address:

dig npub1qmc3cvfz0yu2hx96nq3gp55zdan2qclealn7xshgr448d3nh6lks7zel98.fips AAAA +short

You should see one fd97:... line.

Now ping it:

ping6 -c 4 npub1qmc3cvfz0yu2hx96nq3gp55zdan2qclealn7xshgr448d3nh6lks7zel98.fips

Expect four replies. The first packet may take noticeably longer than subsequent ones — that round trip includes destination discovery, FSP session establishment, and the proactive path-MTU probe. After that, the RTT settles to a steady value reflecting the path between your host and test-us01.

This confirms the direct link works. So far, though, you have only reached the peer you configured. The next step demonstrates the mesh-wide reach that peering buys you.

Step 6: Reach a different node through the mesh

test-us02 is another public test node. You did not add it to your peers: block — your daemon has no direct link to it. But because test-us01 participates in the same mesh and has its own connections to other nodes, your daemon can reach test-us02 through test-us01 without any additional configuration.

ping6 -c 4 npub10yffd020a4ag8zcy75f9pruq3rnghvvhd5hphl9s62zgp35s560qrksp9u.fips

Same form, different npub. Expect replies. The packets travel from your daemon to test-us01 over the direct UDP link, then onward through test-us01 (and possibly other test-mesh nodes) to reach test-us02's fips0 adapter. Replies retrace the path.

This is the central FIPS guarantee: peering is local, but reachability is mesh-wide. You only need one good peer to talk to everyone else they (transitively) talk to.

If the test-us02 ping fails while the test-us01 ping succeeded, the test mesh's routing between those two nodes is momentarily unhealthy — try again in a minute, or pick a different test node from the roster. The link to your peer is unaffected.

What you've learned

You now have a single FIPS node connected to one peer in the public test mesh, with reach to every node that mesh routes you to. You have seen:

• Identity. Your daemon's ephemeral keypair authenticated to test-us01 over Noise XX without either side trusting anyone in advance.
• Transports. A UDP socket on your host carries authenticated, encrypted mesh frames to your peer. No central server, no VPN concentrator.
• Peering vs. reachability. You configured one peer (test-us01) and got reach to a second node (test-us02) for free, through the mesh. The same shape extends to every other node test-us01 can reach.
• Naming. The local .fips resolver translated npub-form hostnames into their fd97:... mesh addresses with no external DNS traffic.
• End-to-end. ICMPv6 traffic over the FIPS data plane reached both destinations and came back, end-to-end encrypted along every link layer in the path.

By the way: shortnames. Those long npub1...fips destinations are the canonical addresses, but the installer ships an /etc/fips/hosts file with shortname entries for the public test mesh, so test-us01.fips and test-us02.fips resolve to the same addresses without typing 80 characters of bech32. You can add your own entries too. See ../how-to/host-aliases.md. The rest of the tutorials use shortnames where they're available.

Troubleshooting

If the handshake does not complete:

• Outbound UDP may be blocked. Some networks filter arbitrary outbound UDP or block return traffic. From a UDP-filtered network you cannot reach peers that only publish UDP endpoints — your reachable peers are limited to those that accept incoming TCP (outbound TCP is typically allowed even on networks that block UDP). The test-mesh nodes publish a TCP endpoint on port 443 for exactly this case; replace the udp entry in the peer's addresses: block with the TCP equivalent:

  addresses:
    - transport: tcp
      addr: "test-us01.fips.network:443"
  

  Restart the daemon and re-check fipsctl show peers. The link will be slower than UDP but is the supported transport for restrictive egress environments.

• Confirm the testnode is reachable at the IP layer. Run dig +short test-us01.fips.network to confirm DNS, then nc -uvz test-us01.fips.network 2121 to confirm UDP reachability.

• Confirm your config parsed. sudo journalctl -u fips -n 50 near the daemon-start time will show config-load lines and any parse errors.

• Time skew. A heavily skewed system clock can make signature validation fail. timedatectl status should show the system clock as synchronized.

What's next

These are the natural follow-on tutorials in the new-user progression. Some are still being written and will appear alongside this one in the tutorials/ directory.

• Make your node's identity persistent. persistent-identity walks through pinning the daemon to a stable Nostr keypair so your npub does not change across restarts — the prerequisite for other operators adding you to their peers: blocks.

• Resolve peers via Nostr. resolve-peers-via-nostr is the smallest useful step toward Nostr-mediated discovery: configure a peer by npub alone and let the daemon look up the current endpoint from public relays. The first of three tutorials covering Nostr discovery; the others — advertise-your-node and open-discovery — round out the publish and ambient-consume sides.

• Trace a connection end-to-end. ipv6-adapter-walkthrough walks the data path from a .fips DNS query through session setup to the far-side TUN adapter, using fipstop and fipsctl to observe each step.

• Reach services on other mesh nodes. reach-mesh-services generalizes the ping6 you just ran to any IPv6-capable tool — nc, traceroute6, curl, ssh — addressed by <npub>.fips. The point is that the FIPS data plane is just IPv6; applications don't need to know they're on a mesh.

• Host a service of your own. host-a-service walks through bringing up a small HTTP server bound to fips0 so mesh nodes can reach it, with a deliberate exposure decision (mesh-only vs every interface), the mesh firewall, and a brief signpost to the separate, unrelated peer ACL (which controls who may peer with your node, not what they can reach on your fips0).

• ground-up-mesh — Bring up two devices on a shared physical link — Ethernet, WiFi, or Bluetooth — with no pre-existing IP infrastructure. The second deployment mode of FIPS, coexisting on the same daemon as the overlay peer to test-us01 you just configured.

For "what just happened, in detail":

• ../design/fips-architecture.md — the protocol stack and the two-layer encryption model.
• ../design/fips-mesh-layer.md — Noise XX link encryption, hop-by-hop forwarding.
• ../design/fips-session-layer.md — end-to-end Noise XX, session lifecycle.
• ../design/fips-ipv6-adapter.md — the TUN, the local DNS responder, MTU enforcement.