fips/docs/tutorials/advertise-your-node.md

Advertise Your Node on Nostr

After resolve-peers-via-nostr your daemon can look up a peer's current endpoint by npub. This tutorial flips it around: you publish a signed advert listing your own endpoint(s), so any other operator who knows your npub can dial you the same way you dialed test-us01.

The whole exercise should take about ten minutes if you have a public IP or a UDP listener that's reachable from outside. A short final section covers udp:nat best-effort hole-punching for the cases where direct UDP advertising isn't an option.

What you'll build

   ┌───────────────────────┐
   │   your fips daemon    │
   │   persistent npub     │
   └──────────┬────────────┘
              │ signed advert (Kind 37195)
              │   { udp:<your-public-ip>:2121, ... }
              │ refreshes every 30 min
              ▼
   ┌──────────────────────────────────────────┐
   │ Nostr relays                             │
   │   relay.damus.io / nos.lol / offchain.pub│
   └──────────────────────┬───────────────────┘
                          │
                          │ "what's <your-npub>'s endpoint?"
                          │
              ┌───────────┴───────────┐
              │  another fips daemon  │
              │  knows your npub,     │
              │  via_nostr: true      │
              └───────────────────────┘

You will change two things in /etc/fips/fips.yaml:

• Flip discovery.nostr.advertise from false to true.
• Add advertise_on_nostr: true and public: true under transports.udp.

After restart, your daemon publishes a Kind 37195 event tied to your npub, listing the UDP endpoint other peers should dial.

How advertising works

Adverts are signed Nostr events. Every advert is a Kind 37195 event signed by your daemon's secret key. Anyone reading it can verify the advert really came from the npub claiming the endpoint. The advert is the (npub → current endpoints) mapping, signed and published.

The advert lists transports the daemon is willing to expose, and only those:

Endpoints are opt-in per transport. Only transports with advertise_on_nostr: true are listed in your advert. Transports without that flag stay private — they still work for peers who reach you via static config, but they won't appear in your published advert.

For UDP specifically, the daemon needs to know what IP and port to put in the advert:

Determining the advertised endpoint (wildcard-bound UDP). With UDP bound to a wildcard like 0.0.0.0:2121, the daemon doesn't know its own public IP at startup. You have two ways to tell it what to put in the advert:

• public: true — daemon does a one-shot STUN observation against the configured STUN servers and uses the reflexive IPv4 it learns. Right when your public IP is dynamic or you'd rather not pin it in config. Note: STUN observes the reflexive IP from an ephemeral socket, then pairs it with the listener's bind port for the advert — the advert is only useful if your listener really is reachable at that public IP/port, which the daemon can't tell from STUN alone. A manual probe from a second host is the only sure check.
• external_addr: "<ip>[:<port>]" — explicit override. Right when you already know your public IP — a static residential IP, an Elastic IP behind 1:1 NAT, a cloud instance whose advertised port differs from the bind port — and you don't want to depend on STUN reachability. Required for TCP on cloud setups where binding directly to the public IP returns EADDRNOTAVAIL.

If you bind UDP to a specific public IP rather than 0.0.0.0, neither STUN nor external_addr is needed — but advertise_on_nostr: true and public: true are still both required for the daemon to publish the endpoint.

Adverts don't sit on the relays forever:

TTL and refresh. Adverts have a 1-hour expiration (NIP-40 expiration tag) and the daemon re-publishes every 30 minutes. If your daemon goes offline, your advert decays from caches in roughly an hour and consumers stop trying.

Step 1: Confirm your starting state

You should be coming out of resolve-peers-via-nostr with:

• A persistent npub (fipsctl show status | grep '"npub"').
• Nostr discovery in consume-only mode (discovery.nostr.enabled: true, discovery.nostr.advertise: false).
• A peer entry for test-us01 with via_nostr: true and no static address. fipsctl show peers shows the link established.

If any of those isn't true, finish the previous tutorials first.

Capture your npub now — you'll need it for the verification step:

sudo fipsctl show status | grep '"npub"'

Copy the value.

Step 2: Enable advertising in the config

Open /etc/fips/fips.yaml and change two things.

Change 1: flip advertise to true. Find the discovery.nostr block under node: and set:

node:
  identity:
    persistent: true
  discovery:
    nostr:
      enabled: true
      advertise: true

(The previous tutorial set advertise: false; you're flipping that bit now.)

Change 2: add the UDP advert flags. Find the udp: block under transports:. The wildcard-bind default (0.0.0.0:2121) means the daemon needs help knowing what to advertise — pick one of the two approaches from the callout above.

If you want STUN auto-discovery (works for full-cone NATs and nodes with a directly-bound public IP):

transports:
  udp:
    bind_addr: "0.0.0.0:2121"
    advertise_on_nostr: true
    public: true

If you already know your public IP (e.g., a static residential IP or a cloud Elastic IP behind 1:1 NAT) and want to skip the STUN dependency:

transports:
  udp:
    bind_addr: "0.0.0.0:2121"
    advertise_on_nostr: true
    public: true
    external_addr: "203.0.113.45:2121"

Replace 203.0.113.45:2121 with your actual public IP and port. The bare-IP form external_addr: "203.0.113.45" is also accepted; the daemon combines it with the bind port. public: true is still required as the master switch that gates UDP advertisement; setting external_addr alongside it wins, and STUN auto-discovery is skipped entirely (no logging cross-check).

advertise_on_nostr: true is the bit that says "include this transport in my published advert" — common to both paths.

Save the file.

Step 3: Restart the daemon

sudo systemctl restart fips
sudo systemctl status fips

Status should show active (running). Within a few seconds the daemon will:

1. Determine the address to advertise. If you set external_addr, the daemon uses it directly and skips STUN. If you set only public: true, the daemon runs a one-shot STUN observation against the default STUN servers and uses the reflexive IPv4 it learns.
2. Build a Kind 37195 advert listing udp:<public-ip>:2121 (and any other transports you have advertise_on_nostr: true on).
3. Sign the advert with the daemon's nsec.
4. Publish it to the three default advert relays.
5. Schedule a refresh every 30 minutes.

If you took the public: true path and STUN fails (for example, the network blocks outbound UDP/3478), the daemon emits a WARN line in the journal and suppresses the UDP entry from the advert rather than publishing a wrong address. The link to test-us01 from the previous tutorial keeps working regardless — only the publish side is gated on STUN, and only on the STUN path. The external_addr path doesn't depend on STUN reachability at all.

Quick sanity check on the journal:

sudo journalctl -u fips -n 200 | grep -iE 'STUN|advert|warn' | head -20

If you see WARN lines mentioning STUN or wildcard-bind fallthrough, jump to Troubleshooting; the rest of the tutorial assumes the publish succeeded.

Step 4: Verify your advert is on the network

The advert is a public Nostr event — anyone, including you, can fetch it. With the nak Nostr CLI installed, query the relays for adverts published by your npub:

nak req -k 37195 -d "fips-overlay-v1" \
    -a $(nak decode <your-npub> | jq -r .pubkey) \
    --limit 1 wss://relay.damus.io

Replace <your-npub> with the npub you copied in Step 1. The inner nak decode converts your bech32 npub to the hex pubkey the relay filter expects.

Expect one event back. The interesting fields:

• pubkey — your npub in hex form.

• tags — includes ["d","fips-overlay-v1"] (the namespace), ["protocol","fips-overlay-v1"], and an ["expiration", …] tag set ~1 hour in the future.

• content — JSON listing the endpoints array. You should see one entry like:

  {"transport":"udp","addr":"<your-public-ip>:2121"}
  

That <your-public-ip> is what STUN learned. Confirm it matches what you'd expect for your network — for a home node, it should be your residential IP, not a 192.168.x.x LAN address.

Step 5: Watch for inbound connections

Your advert is now consumable by any FIPS daemon running open discovery on the same fips-overlay-v1 namespace. The public test mesh nodes do exactly this — they subscribe to all adverts in the namespace and try to dial new publishers.

Within a minute or two of restart, run:

sudo fipsctl show peers

In addition to your configured test-us01 peer, you may see an entry for test-us03 (the open-discovery test mesh node). It will have connectivity active and its own transport_addr. This peering appeared without you configuring anything — the test-mesh open-discovery node saw your advert, dialed the endpoint, and Noise IK established the link.

If no inbound peers appear, that's not necessarily a failure of advertising — it just means no one has consumed your advert and dialed back yet. The advert is on the relays regardless, verifiable in Step 4.

What you've learned

• Adverts are publish + sign. Every running FIPS daemon with advertise: true publishes a signed advert; reading it is one Nostr event lookup.
• Endpoint inclusion is per-transport. Only the transports you set advertise_on_nostr: true on appear in the advert.
• public: true invokes STUN. Wildcard-bound UDP with public: true runs a one-shot STUN observation to learn its public IP.
• Refresh is automatic. Adverts re-publish every 30 minutes; consumers cache them with a 1-hour staleness bound.
• The publish side stands alone. Once your advert is on the relays, peers can dial you whether you're advertising to them specifically or not. The test mesh's open-discovery nodes will pick you up automatically.

If your direct UDP advert isn't reachable

public: true advertises the IP STUN observes paired with your listener's bind port. That advert is only useful if your listener really is reachable at that public IP/port — STUN can confirm the public IP but not that an unsolicited inbound packet to the bind port will make it through. The most common cause of the listener being unreachable is symmetric NAT (where the public port a peer sees varies per remote endpoint), but other configurations can have the same effect.

When direct UDP advertising can't be relied on, the alternative is udp:nat mode, which advertises a placeholder udp:nat endpoint along with the daemon's signaling-relay and STUN-server lists, and performs UDP hole-punching at dial time. Hole-punching is best-effort — it works reliably when both sides are full-cone or port-restricted, and symmetric NAT on either side typically defeats it. Both sides need matching configs.

The minimal config switch:

transports:
  udp:
    bind_addr: "0.0.0.0:2121"
    advertise_on_nostr: true
    public: false                 # ← was true; change to false

And add the signaling/STUN block under discovery.nostr:

discovery:
  nostr:
    enabled: true
    advertise: true
    dm_relays:
      - "wss://relay.damus.io"
      - "wss://nos.lol"
    stun_servers:
      - "stun:stun.l.google.com:19302"
      - "stun:stun.cloudflare.com:3478"

For the full setup including peer-side config and the punch- duration knob, see ../how-to/enable-nostr-discovery.md § When the node is behind NAT.

Separately from NAT considerations, FIPS supports running a node behind a Tor onion service as a deployment shape in its own right — chosen for the privacy, anonymity, and censorship-resistance properties it brings, not as a fallback when UDP or TCP fail. If those properties are an independent goal for your node, see ../how-to/enable-nostr-discovery.md § Tor onion node and ../how-to/deploy-tor-onion.md.

Troubleshooting

If your advert doesn't appear on the relays:

• STUN failed. Check the journal for WARN lines mentioning STUN or wildcard-bind. The most common causes are outbound UDP/3478 blocked or DNS for stun.l.google.com failing. Try: dig stun.l.google.com and nc -uvz stun.l.google.com 19302 to verify reachability.

• Wrong public IP advertised. If nak shows your advert with a non-public address (e.g., 10.x.x.x or 192.168.x.x), STUN didn't see your real public IP — likely you're behind a CGNAT that NATs your STUN traffic too, or a corporate firewall that proxies it. Two correct fixes: (a) keep public: true and add external_addr: <your-IP> (the explicit override wins and skips STUN); or (b) bind directly to your public interface (bind_addr: <pub-ip>:2121) and keep advertise_on_nostr: true and public: true. Don't drop those flags.

• Relay reachability. nak req against a relay you can reach but no events return — possibly the publish failed silently because the daemon couldn't connect to that specific relay. Try the other two:

  nak req ... wss://nos.lol
  nak req ... wss://offchain.pub
  

• advertise_on_nostr typo. YAML is case-sensitive. The config parser rejects unknown keys via serde(deny_unknown_fields) on the per-section structs, so a misspelled field will refuse the daemon's start with a parse-error line in the journal naming the unknown field. If the daemon is running but nak returns no advert, the field was accepted but something else is wrong; double-check the spelling on the UDP block and that discovery.nostr.advertise: true is also set.

What's next

• Open discovery. open-discovery flips the consume side symmetric — switch your daemon to policy: open and watch your peer list populate from the ambient fips-overlay-v1 namespace, the same mechanism test-us03 is using right now to find you.

• Host a service of your own. host-a-service walks through bringing up an HTTP server addressable as <your-npub>.fips, the same way the connecting node now reaches test-us01. The natural follow-on now that other operators can dial you by npub.

For the operator-style scenario reference covering all five shapes of Nostr discovery side-by-side (consume-only, publish-direct, publish-Tor, NAT traversal, open):

• ../how-to/enable-nostr-discovery.md

For the wire-format and discovery design:

• ../reference/nostr-events.md — Kind 37195 advert format, Kind 21059 traversal signaling.
• ../design/fips-nostr-discovery.md — discovery runtime design, security and threat model.