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 full-cone home NAT. A short final section covers the alternative path for symmetric-NAT networks.

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. Works for nodes with a directly-bound public IP and for nodes behind full-cone NAT (most home routers).
• 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 flag is needed — the daemon advertises whatever it's bound to.

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
    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. You may set both public: true and external_addr together — the explicit override wins, with STUN as a 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. Run a one-shot STUN observation against the default STUN servers to learn its public IP.
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 STUN fails (for example, if 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.

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 you're behind symmetric NAT

public: true + STUN works on most home and office NATs (the full-cone variety) and on nodes with a directly-bound public IP. It does not work on symmetric NAT, where the NAT mapping is keyed on (source-port, destination-host) so the IP/port your STUN server saw isn't the IP/port a different peer would see.

For symmetric-NAT networks 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. Both sides need to be running matching configs and at least one side needs a non-symmetric NAT for the punch to succeed; symmetric on both sides is not reliably traversable and will time out.

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 § Capability 2c.

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 § Sub-scenario 2b 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. Switch to the external_addr form from Step 2 with your actual public IP, or replace public: true with the bound interface IP directly under bind_addr.

• 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 and silently ignores unknown keys. If nak returns no advert at all, 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.