34e00b9f6e
Optional peer discovery and NAT hole-punching path gated behind a new
`nostr-discovery` cargo feature. Nodes publish signed overlay endpoint
adverts to public Nostr relays, consume peer adverts to populate
fallback dial addresses, and use STUN-assisted UDP hole punching with
NIP-59 gift-wrap offer/answer signaling to establish direct UDP paths
between NATed peers. Once a punched socket is up, it is handed into
the existing FIPS UDP transport and the standard Noise/FMP session
stack takes over unchanged.
The cargo feature is in the default feature set
(`default = ["nostr-discovery"]`) so stock builds include it; a
build that explicitly disables default features (or selects a
feature set without `nostr-discovery`) does not link the nostr /
nostr-sdk crates and does not emit a no-op poll in the tick loop.
Runtime behavior is independently gated by
`node.discovery.nostr.enabled`, which defaults to false; if the
config enables Nostr on a non-feature build, startup logs a
warning and continues without it.
== Cargo feature and dependencies
- New cargo feature `nostr-discovery = ["dep:nostr", "dep:nostr-sdk"]`.
Not in the default feature set.
- New optional Linux-only dependencies: `nostr 0.44` (features: std,
nip59) and `nostr-sdk 0.44`. Gift-wrap unwrap is hand-rolled in
`src/discovery/nostr/signal.rs` rather than relying on the SDK's
rumor-author check, which FIPS sidesteps by trusting `seal.pubkey`
exclusively.
== Wire format
Overlay advert event: `kind 37195`, parameterized replaceable
(NIP-01 application-defined replaceable range 30000-39999), with
`d = "fips-overlay-v1"`. The digits visually spell FIPS (7=F, 1=I,
9=P, 5=S); a relay survey confirmed the kind is unused.
Advert content carries the version tag, endpoint list
(`udp|tcp|tor` + addr), optional signal-relay and stun-server
metadata, and `issuedAt` / `expiresAt` timestamps. Endpoint
`addr: "nat"` is the sentinel that triggers traversal on the peer
side. NIP-40 `expiration` tag bounds staleness on permanent
shutdown. Lifecycle relies on parameterized-replaceable
supersession; the daemon does not emit NIP-09 kind-5 deletes —
strict relays (Damus, Primal) race delete-against-replace and can
silently drop the replacement.
Gift-wrapped signal event: `kind 21059`. Punch packets carry magic
values `PUNCH_MAGIC` / `PUNCH_ACK_MAGIC`, a sequence number, and a
16-byte session hash.
== Discovery surface
- `src/discovery.rs` (always compiled)
- `EstablishedTraversal`: bound UDP socket + selected remote +
peer npub + optional transport name/config tuning overrides.
- `BootstrapHandoffResult`: returned on successful handoff —
allocated transport id, local/remote addrs, peer NodeAddr,
session id.
- `src/discovery/nostr/` (`#![cfg(feature = "nostr-discovery")]`)
- `types.rs`: wire and control types described above. `ADVERT_KIND`
constant. `BootstrapError` enumerates failure modes (disabled,
missing advert, missing NAT endpoint, no usable relays, invalid
advert, invalid npub, signal timeout, punch timeout, replay,
STUN failure, protocol, nostr, io, serde, event-parse).
- `runtime.rs`: `NostrDiscovery` coordinator. Owns the shared
nostr-sdk `Client`, subscribes to advert + signal event kinds,
maintains a bounded advert cache and a bounded seen-sessions
replay set, drains `BootstrapEvent::{Established, Failed}` for
the node to consume, exposes `update_local_advert`,
`request_connect`, `advert_endpoints_for_peer`,
`cached_open_discovery_candidates`, and `shutdown`.
- `signal.rs`: NIP-59 gift-wrap encode/decode. Outbound wraps are
built against per-attempt ephemeral keys; inbound events are
unwrapped against the node identity.
- `stun.rs`: RFC 5389/8489 Binding Request client with
XOR-MAPPED-ADDRESS parsing for both IPv4 and IPv6; used only to
observe the initiator's own reflexive address against its
locally configured STUN list (peer-advertised STUN is
informational, never an egress target).
- `traversal.rs`: per-attempt candidate-pair punch planner.
Allocates a fresh `0.0.0.0:0` UDP socket per attempt, enumerates
LAN-private and ULA interface addresses alongside the STUN
reflexive address, schedules probe/ack exchanges at the
configured interval for the configured duration, and picks the
first candidate pair that authenticates end-to-end.
Strategy ordering is Reflexive↔Reflexive first, then LAN, then
Mixed. The STUN-observed pair is the only candidate that's reliable
across arbitrary network topologies; trying it first prevents the
planner from latching onto a misleading host-candidate path before
the reflexive path gets a chance. There is no catch-all
Local↔Local strategy: a previous design that paired every local
host candidate from one side with every local host candidate from
the other could declare success on a one-way reachable asymmetric
L3 path (corporate VPN, Tailscale subnet route, overlapping private
address space), only for the FMP handshake to stall because the
return path didn't match. The legitimate `Lan` strategy still pairs
candidates that share a subnet.
== Configuration surface
`node.discovery.nostr.*` (`NostrDiscoveryConfig`), all `serde(default)`
with `deny_unknown_fields`:
- `enabled` (default false), `advertise` (default true)
- `advert_relays`, `dm_relays`, `stun_servers`: defaults are
`wss://relay.damus.io`, `wss://nos.lol`, `wss://offchain.pub`
for both relay lists, and Google / Cloudflare / Twilio for STUN.
Operators are expected to override for production. Other
verified-working public relays for reference:
`nostr.bitcoiner.social`, `nostr-pub.wellorder.net`,
`nostr.oxtr.dev`, `nostr.mom`.
- `app` (default `"fips-overlay-v1"`), `signal_ttl_secs` (120)
- `policy`: `NostrDiscoveryPolicy::{Disabled, ConfiguredOnly (default),
Open}` — controls whether advert-derived endpoints are consumed
only for peers carrying `via_nostr = true`, or also for
non-configured peers within a budget cap.
- `share_local_candidates` (default false) — when false, the offer's
`local_addresses` list is empty and peers see only the reflexive
address. Enable per-node only for genuinely same-LAN deployments;
off-by-default eliminates the misleading-path failure mode for
the common case where peers are not on the same broadcast domain.
- `open_discovery_max_pending` (64) — caps queued open-discovery
retries; bounded by available outbound slots.
- `max_concurrent_incoming_offers` (16) — semaphore against offer
spam; excess offers are debug-logged and dropped.
- `advert_cache_max_entries` (2048) and `seen_sessions_max_entries`
(2048) — bound memory under ambient relay volume; overflow
evictions are debug-logged.
- `attempt_timeout_secs` (10), `replay_window_secs` (300)
- `punch_start_delay_ms` (2000), `punch_interval_ms` (200),
`punch_duration_ms` (10000)
- `advert_ttl_secs` (3600), `advert_refresh_secs` (1800)
Per-peer and per-transport flags:
- `PeerConfig.via_nostr: bool` — when true (and Nostr is enabled),
advert-derived addresses are appended as fallback dial candidates
after static addresses for that peer.
- `PeerConfig.addresses` is now `serde(default)` and may be empty
when `via_nostr: true`; validation requires at least one of the
two to be present per peer, and the error message names the
peer's npub.
- `UdpConfig.advertise_on_nostr: Option<bool>` and
`UdpConfig.public: Option<bool>` — UDP transports can be
advertised either as direct `host:port` (public = true) or as the
`addr: "nat"` sentinel that triggers rendezvous on the peer side.
- `TcpConfig.advertise_on_nostr` and `TorConfig.advertise_on_nostr`
— TCP and Tor onion endpoints can be advertised as directly
reachable.
- A reserved peer address `transport: udp, addr: "nat"` parses without
special-casing in YAML and routes through the bootstrap runtime.
Cross-field validation (`Config::validate`, called from `Node::new`
and `Node::with_identity`):
- Any transport with `advertise_on_nostr = true` requires
`node.discovery.nostr.enabled = true`.
- Any peer with `via_nostr = true` requires
`node.discovery.nostr.enabled = true`.
- A non-public UDP advert (`advertise_on_nostr = true`,
`public = false` — i.e. `udp:nat`) additionally requires at least
one `dm_relay` and at least one `stun_server`.
Surfaced as `ConfigError::Validation`.
== Node integration
`src/node/lifecycle.rs` is the main integration point.
- At node start (after transports are up, before TUN), if Nostr is
enabled and the feature is compiled in, `NostrDiscovery::start` is
invoked, the initial local overlay advert is built from the live
transport set and published, and the runtime handle is stored.
- The rx tick loop calls `poll_nostr_discovery` (feature-gated both
at method definition and call site), which refreshes the local
advert, drains bootstrap events, adopts established traversals,
schedules retries for failed traversals, and — under `policy:
open` — enqueues outbound retries for non-configured peers
visible in the advert cache, bounded by
`open_discovery_max_pending` and the remaining outbound slots.
- Outbound peer dialing is refactored to `try_peer_addresses`, which
first exhausts the static address list in priority order and only
then appends advert-derived fallback addresses; both lists run
through the same `attempt_peer_address_list` code path. The
`udp:nat` sentinel address triggers `NostrDiscovery::request_connect`
for the peer instead of a direct dial and returns `Ok(())`.
- `build_overlay_advert` walks operational transports, consults
per-instance `UdpConfig` / `TcpConfig` / `TorConfig` (matching by
optional transport instance name), and emits an `OverlayAdvert`
including `signalRelays` and `stunServers` when any UDP endpoint
is advertised as NAT.
- `adopt_established_traversal` is the bootstrap handoff API:
allocates a new `TransportId`, constructs a `UdpTransport` with
the user-supplied (or default) `UdpConfig`, calls the new
`adopt_socket_async` to reuse the punched socket verbatim,
registers the transport in the normal transport map, records it
in `bootstrap_transports`, and calls `initiate_connection` so the
normal handshake path runs. On failure, the transport is stopped
and removed cleanly and the set membership is rolled back.
- On clean shutdown, `NostrDiscovery::shutdown` is awaited so
background tasks stop before transports are torn down. (The
advert is not explicitly retracted; NIP-40 expiration plus the
next refresh from any live publisher supersedes it.)
New `Node` fields:
- `nostr_discovery: Option<Arc<NostrDiscovery>>` (feature-gated).
- `bootstrap_transports: HashSet<TransportId>` — per-peer UDP
transports adopted from NAT traversal, cleaned up via
`cleanup_bootstrap_transport_if_unused` whenever the link,
connection, peer, or pending-connect referencing them is removed.
Retry and error surface:
- `RetryState.expires_at_ms: Option<u64>` — optional absolute expiry
for a retry entry. `pump_retries` drops expired entries with an
info log. Used for open-discovery retries, which expire at two
times the advert TTL.
- New `NodeError::BootstrapHandoff(String)` returned from
`adopt_established_traversal` when the underlying transport
adoption fails or local address discovery fails.
- New `ConfigError::Validation(String)`.
- A small refactor extracts `Node::now_ms()` and reuses it across
lifecycle, rx-loop tick, and timeout bookkeeping.
== UDP transport
`src/transport/udp/`:
- `UdpRawSocket::adopt(std::net::UdpSocket, recv_buf, send_buf)`:
adopts an externally bound socket, makes it non-blocking, applies
the configured buffer sizes (warning if the kernel clamps), and
reports the resulting local address. Preserves the NAT mapping —
no rebind.
- `UdpTransport::adopt_socket_async(std::net::UdpSocket)`: the
`start_async` analogue for an already-bound socket, wiring the
async socket and recv task exactly as the fresh-bind path would.
- `Drop` impl for `UdpTransport`: if a transport is dropped while
still holding a recv task or socket (for example on error
teardown), aborts the task, clears the socket, and emits a debug
log so the cleanup is visible in tracing rather than silent.
== Logging and observability
Default `EnvFilter` demotes third-party relay-pool DEBUG output to
TRACE-only: `nostr_relay_pool`, `nostr_sdk`, and `nostr` are pinned
at INFO when our level is anything below TRACE, and at TRACE when
our level is TRACE — so the raw frames are still reachable when
explicitly asked for. RUST_LOG continues to override completely.
Concise one-line DEBUG events are emitted at the meaningful points
in the discovery / hole-punch sequence:
- `advert: published` (event id, relay count, endpoints, ttl)
- `advert: peer cached` (notify-loop ingress for non-self)
- `advert: resolved` (cache hit / relay fetch outcome)
- `traversal: initiator starting`
- `traversal: initiator STUN observed` (reflexive, local count)
- `traversal: offer sent` (session id, relay count, event id)
- `traversal: answer received` (accepted, reflexive, local)
- `traversal: initiator punch succeeded` (remote addr)
- `traversal: offer received` (responder side)
- `traversal: responder STUN observed`
- `traversal: answer sent`
- `traversal: responder punch succeeded`
Npubs are shortened to `npub1<4>..<4>` and event/session ids to
their first 8 hex characters.
Other operator-facing logs:
- `UdpTransport` adoption and drop paths log at info / debug.
- `adopt_established_traversal` logs at debug on entry and info on
successful return, tagged with peer npub, session id, transport
id, and both socket endpoints, so the bootstrap handoff is
traceable end-to-end alongside the `UdpTransport::drop` log.
- `cleanup_bootstrap_transport_if_unused` logs at debug when the
reference-count check drops an adopted transport.
- `connect_peer` tags its entry `debug!` with `peer_npub` so
downstream STUN, punch, and handshake logs for the same peer
correlate for operators.
- Advert-cache and seen-sessions overflow evictions log at debug so
mis-sized caps are visible under ambient relay volume.
- Gift-wrap unwrap failures on `SIGNAL_KIND` events log at trace
(hot path: fires for every unrelated signal event on the same
relay).
- Traversal-offer handler failures log at debug. Expected conditions
such as punch timeout on symmetric NAT are covered there; real
problems are reported upstream via `BootstrapEvent::Failed`.
- Inbound-offer rate-limit messages name the governing config field
(`max_concurrent_incoming_offers`) and state that the offer was
rate-limited rather than failing.
== Tests
- 18 new unit tests in `src/discovery/nostr/tests.rs` covering advert
encoding, signal envelope round-trip, STUN parsing, punch-packet
codec, and replay-window enforcement. Run under the
`nostr-discovery` feature.
- Config-validation tests in `src/config/mod.rs` covering the three
cross-field invariants and YAML parsing of the full
`node.discovery.nostr` block plus `peers[].via_nostr`, empty
`addresses` with `via_nostr: true`, and a `udp: nat` address.
- `src/node/tests/bootstrap.rs` integration tests that drive a
synthetic traversal (bound UDP socket pair + synthetic peer
identity) through `adopt_established_traversal` and assert the
Noise handshake completes over the adopted socket.
- Punch-planner tests assert reflexive-before-LAN ordering and that
same-LAN scenarios still include the LAN target in the plan.
- `testing/nat/` Docker NAT lab harness:
- Local `strfry` relay, local STUN responder, and one or two
router containers performing `iptables` NAT.
- Node LAN interfaces are provisioned with explicit `veth` pairs
injected into the node and router namespaces so every packet
traverses the router namespace (plain Docker bridges are not
used for the LAN).
- `cone` scenario: both peers behind full-cone-emulation NAT
(SNAT with source-port preservation, inbound DNAT back to the
single LAN host regardless of remote source); asserts UDP
traversal succeeds and link remote addresses are on the router
WAN subnet.
- `symmetric` scenario: `MASQUERADE --random-fully`; asserts UDP
traversal fails and TCP fallback converges over router-
published WAN addresses.
- `lan` scenario: both peers share a LAN subnet; asserts LAN
addresses are preferred over reflexive ones.
- Cleanup tears down all profile-gated services
(`--profile cone --profile symmetric --profile lan`) so no
orphan containers survive a run.
- `testing/scripts/build.sh` builds the Docker test image with
`--features "tui nostr-discovery"` by default so NAT-harness
binaries include bootstrap support.
== CI
- Linux release build and nextest unit-test job both use
`--features "gateway nostr-discovery"` so the feature-gated code
and its unit tests compile and run in CI.
- Three new integration matrix entries (`nat-cone`, `nat-symmetric`,
`nat-lan`) invoke `testing/nat/scripts/nat-test.sh`, collect
`docker compose logs` on failure, and always stop containers.
== Packaging and operations
- `packaging/common/fips.yaml` ships a fully commented
`node.discovery.nostr.*` block, plus documented
`advertise_on_nostr` / `public` examples under the UDP transport,
an `advertise_on_nostr` example under TCP, and a `via_nostr: true`
example under the static peer section with both a direct
`host:port` UDP address and a `udp: nat` fallback.
- `.github/workflows/package-openwrt.yml`: NIP-94 release event
publishes target the new default relay set.
== Documentation
- `README.md`: overlay discovery + NAT traversal moved from
"Near-term priorities" into "What works today".
- `docs/design/fips-intro.md`: rewrites the paragraphs that
previously described Nostr discovery and NAT traversal as future
work; describes the shipped mechanism and the feature gate.
- `docs/design/fips-transport-layer.md`: drops the "(future
direction)" qualifier from the Nostr Relay Discovery section,
expands with the `udp:nat` advertisement and bootstrap handoff
description, and updates the Current State callout.
- `docs/design/fips-mesh-layer.md`: notes that mid-session NAT
rebinding (roaming) and initial NAT traversal (Nostr path) are
distinct mechanisms.
- `docs/design/fips-configuration.md`: documents the full
`node.discovery.nostr.*` surface, including the three resource
caps and `share_local_candidates`.
- `docs/design/fips-nostr-discovery.md`: design and configuration
reference for the shipped mechanism, including the empty-
`addresses`-with-`via_nostr` shorthand.
- `docs/proposals/nostr-udp-hole-punch-protocol.md`: adds an
Implemented status callout, clarifies that the punch socket is
per-peer and per-attempt rather than shared with the application
listener, aligns field names with the shipped JSON
(`sessionId`, `issuedAt` / `expiresAt`, `reflexiveAddress`,
`localAddresses`, `stunServer`), sets the `d`-tag to
`fips-overlay-v1`, names the kind as 37195, and notes that
advertised STUN entries are informational.
- `docs/proposals/README.md`: adds a Status column and marks the
hole-punching proposal Implemented.
- `CHANGELOG.md`: Unreleased > Added entry covering the discovery
path, STUN/punch path, configuration surface, and Docker NAT lab.
Co-authored-by: Johnathan Corgan <johnathan@corganlabs.com>
40 KiB
FIPS Configuration
FIPS uses YAML-based configuration with a cascading multi-file priority system. All parameters have sensible defaults; a node can run with no configuration file at all (it will generate an ephemeral identity and listen on default addresses).
Configuration Loading
Search Paths
When started without the -c flag, FIPS searches for fips.yaml in these
locations, lowest to highest priority:
| Priority | Path | Purpose |
|---|---|---|
| 1 (lowest) | /etc/fips/fips.yaml |
System-wide defaults |
| 2 | ~/.config/fips/fips.yaml |
User preferences |
| 3 | ~/.fips.yaml |
Legacy user config |
| 4 (highest) | ./fips.yaml |
Deployment-specific overrides |
All found files are loaded and merged in priority order. Values from higher
priority files override those from lower priority files. This allows a system
administrator to set site-wide defaults in /etc/fips/fips.yaml while
individual deployments override specific values in ./fips.yaml.
CLI Option
fips -c /path/to/config.yaml
When -c is specified, only that file is loaded (search paths are skipped).
Partial Configuration
Every field has a built-in default. A configuration file only needs to specify values that differ from defaults. For example, a minimal config might contain only the identity and peer list, inheriting all other defaults.
YAML Structure
The configuration is organized into five top-level sections:
node: # Node behavior, protocol parameters, and tuning
tun: # TUN virtual interface
dns: # DNS responder for .fips domain
transports: # Network transports (UDP, Ethernet, Bluetooth, Tor, ...)
peers: # Static peer list
Control Socket (node.control.*)
| Parameter | Type | Default | Description |
|---|---|---|---|
node.control.enabled |
bool | true |
Enable the control socket |
node.control.socket_path |
string | (auto) | Linux: Socket file path. Default: $XDG_RUNTIME_DIR/fips/control.sock, then /run/fips/control.sock (if root), then /tmp/fips-control.sock. Windows: TCP port number (default: 21210); the control socket listens on localhost at this port. |
The control socket provides access to node state and runtime management
via the fipsctl command-line tool. In addition to read-only status
queries, fipsctl connect and fipsctl disconnect enable runtime peer
management. See the project README for the
command list.
On Linux, the control socket is a Unix domain socket with filesystem
permissions (mode 0770, group fips). On Windows, it is a TCP listener
on localhost. TCP does not provide filesystem-level ACLs, so any local
user can connect to the control port.
Security note (Windows): The TCP control socket on Windows is a known limitation. Any process running on the local machine can connect to the control port and issue commands, including
disconnect,connect, andinject-config. This is acceptable for single-user workstations but may be inappropriate for shared machines. Future improvements may include named pipe support (with Windows ACLs) or an authentication token mechanism. On shared Windows systems, consider using firewall rules to restrict access to the control port.
All tunable protocol parameters live under node.*, organized as sysctl-style
dotted paths. The top-level sections (tun, dns, transports, peers)
handle infrastructure concerns only.
Node Parameters (node.*)
Identity (node.identity.*)
| Parameter | Type | Default | Description |
|---|---|---|---|
node.identity.nsec |
string | (none) | Secret key in nsec (bech32) or hex format. If omitted, behavior depends on persistent. |
node.identity.persistent |
bool | false |
Persist identity across restarts via key file. |
Identity resolution follows a three-tier priority:
- Explicit
nsecin config — always used when present, regardless ofpersistent - Persistent key file — when
persistent: trueand nonsec, loads fromfips.keyadjacent to the config file; if no key file exists, generates a new keypair and saves it - Ephemeral — when
persistent: false(default) and nonsec, generates a fresh keypair on each start
Key files (fips.key with mode 0600, fips.pub with mode 0644) are written adjacent
to the highest-priority config file for operator visibility, even in ephemeral mode.
General
| Parameter | Type | Default | Description |
|---|---|---|---|
node.leaf_only |
bool | false |
Leaf-only mode: node does not forward traffic or participate in routing |
node.tick_interval_secs |
u64 | 1 |
Periodic maintenance tick interval (retry checks, timeout cleanup, tree refresh) |
node.base_rtt_ms |
u64 | 100 |
Initial RTT estimate for new links before measurements converge |
node.heartbeat_interval_secs |
u64 | 10 |
Heartbeat send interval per peer for liveness detection |
node.link_dead_timeout_secs |
u64 | 30 |
No-traffic timeout before a peer is declared dead and removed |
Resource Limits (node.limits.*)
Controls capacity for connections, peers, and links.
| Parameter | Type | Default | Description |
|---|---|---|---|
node.limits.max_connections |
usize | 256 |
Max handshake-phase connections |
node.limits.max_peers |
usize | 128 |
Max authenticated peers |
node.limits.max_links |
usize | 256 |
Max active links |
node.limits.max_pending_inbound |
usize | 1000 |
Max pending inbound handshakes |
Rate Limiting (node.rate_limit.*)
Handshake rate limiting protects against DoS on the Noise IK handshake path.
| Parameter | Type | Default | Description |
|---|---|---|---|
node.rate_limit.handshake_burst |
u32 | 100 |
Token bucket burst capacity |
node.rate_limit.handshake_rate |
f64 | 10.0 |
Tokens per second refill rate |
node.rate_limit.handshake_timeout_secs |
u64 | 30 |
Stale handshake cleanup timeout |
node.rate_limit.handshake_resend_interval_ms |
u64 | 1000 |
Initial handshake message resend interval |
node.rate_limit.handshake_resend_backoff |
f64 | 2.0 |
Resend backoff multiplier (1s, 2s, 4s, 8s, 16s with defaults) |
node.rate_limit.handshake_max_resends |
u32 | 5 |
Max resends per handshake attempt |
Retry / Backoff (node.retry.*)
Connection retry with exponential backoff.
| Parameter | Type | Default | Description |
|---|---|---|---|
node.retry.max_retries |
u32 | 5 |
Max connection retry attempts |
node.retry.base_interval_secs |
u64 | 5 |
Base backoff interval |
node.retry.max_backoff_secs |
u64 | 300 |
Cap on exponential backoff (5 minutes) |
Auto-reconnect (triggered by MMP link-dead removal) uses the same backoff
parameters but bypasses max_retries, retrying indefinitely. See
peers[].auto_reconnect below.
Cache Parameters (node.cache.*)
Controls caching of tree coordinates and identity mappings.
| Parameter | Type | Default | Description |
|---|---|---|---|
node.cache.coord_size |
usize | 50000 |
Max entries in coordinate cache |
node.cache.coord_ttl_secs |
u64 | 300 |
Coordinate cache entry TTL (5 minutes) |
node.cache.identity_size |
usize | 10000 |
Max entries in identity cache (LRU, no TTL) |
Discovery Protocol (node.discovery.*)
Controls bloom-guided node discovery (LookupRequest/LookupResponse).
| Parameter | Type | Default | Description |
|---|---|---|---|
node.discovery.ttl |
u8 | 64 |
Hop limit for LookupRequest forwarding |
node.discovery.attempt_timeouts_secs |
array<u64> | [1, 2, 4, 8] |
Per-attempt timeouts. Each entry is the deadline for one LookupRequest before sending the next attempt with a fresh request_id. Length determines total attempt count; default gives 4 attempts and a 15s total budget |
node.discovery.recent_expiry_secs |
u64 | 10 |
Dedup cache expiry for recent request IDs |
node.discovery.backoff_base_secs |
u64 | 0 |
Optional post-failure suppression base in seconds; doubles per consecutive failure. 0 disables (default) — the per-attempt sequence is the only retry pacing |
node.discovery.backoff_max_secs |
u64 | 0 |
Cap on optional post-failure backoff |
node.discovery.forward_min_interval_secs |
u64 | 2 |
Transit-side rate limiting: minimum interval between forwarded lookups for the same target |
Nostr Overlay Discovery (node.discovery.nostr.*)
Optional Nostr-mediated overlay discovery. This layer publishes replaceable
endpoint adverts (fips-overlay-v1), consumes advert-derived endpoint
fallbacks for configured peers, and can optionally discover non-configured
peers (policy: open). udp:nat remains the trigger for NAT traversal
offer/answer + punch-through, after which the established UDP socket is handed
into the normal FIPS transport/session stack.
Inbox-relay discovery falls back to the local DM relay list if remote relay
metadata cannot be fetched.
This support is compiled behind the crate feature nostr-discovery; builds
without that feature ignore udp:nat bootstrap configuration.
| Parameter | Type | Default | Description |
|---|---|---|---|
node.discovery.nostr.enabled |
bool | false |
Enable Nostr-mediated overlay discovery |
node.discovery.nostr.policy |
string | "configured_only" |
Advert discovery policy: disabled, configured_only, open |
node.discovery.nostr.open_discovery_max_pending |
usize | 64 |
Max open-discovery peers queued in outbound retry/connection state at once |
node.discovery.nostr.max_concurrent_incoming_offers |
usize | 16 |
Max concurrent inbound traversal offers processed at once (rate limit against offer spam) |
node.discovery.nostr.advert_cache_max_entries |
usize | 2048 |
Max cached overlay adverts retained from relay traffic |
node.discovery.nostr.seen_sessions_max_entries |
usize | 2048 |
Max seen-session IDs retained for replay detection |
node.discovery.nostr.advertise |
bool | true |
Publish local endpoint adverts |
node.discovery.nostr.advert_relays |
list[string] | ["wss://relay.damus.io", "wss://nos.lol", "wss://offchain.pub"] |
Relays used for service adverts |
node.discovery.nostr.dm_relays |
list[string] | ["wss://relay.damus.io", "wss://nos.lol", "wss://offchain.pub"] |
Relays used for encrypted signaling events |
node.discovery.nostr.stun_servers |
list[string] | ["stun:stun.l.google.com:19302", "stun:stun.cloudflare.com:3478", "stun:global.stun.twilio.com:3478"] |
STUN servers used for local reflexive address discovery |
node.discovery.nostr.app |
string | "fips-overlay-v1" |
Traversal application namespace and advert identifier suffix |
node.discovery.nostr.signal_ttl_secs |
u64 | 120 |
Signaling TTL in seconds |
node.discovery.nostr.attempt_timeout_secs |
u64 | 10 |
Overall traversal attempt timeout in seconds |
node.discovery.nostr.replay_window_secs |
u64 | 300 |
Replay tracking retention window in seconds |
node.discovery.nostr.punch_start_delay_ms |
u64 | 2000 |
Delay before punch traffic starts |
node.discovery.nostr.punch_interval_ms |
u64 | 200 |
Interval between punch packets |
node.discovery.nostr.punch_duration_ms |
u64 | 10000 |
How long to keep punching before failure |
node.discovery.nostr.advert_ttl_secs |
u64 | 3600 |
Advert TTL in seconds |
node.discovery.nostr.advert_refresh_secs |
u64 | 1800 |
How often adverts are refreshed in seconds |
If stun_servers is omitted, the built-in default list above is used. If it is
specified in YAML, the configured list fully overrides the defaults.
Initiators use only this local list for outbound STUN queries; peer-advertised
STUN values are published for diagnostics/interoperability but are not used as
arbitrary egress targets.
The built-in advert and DM relay defaults point at widely-operated public
relays (Damus, nos.lol, Primal) as best-effort endpoints; operators are
encouraged to override them with their own relay preferences for production
deployments.
Advert freshness is enforced semantically: events with expired NIP-40
expiration tags are dropped, and adverts are also bounded by a created-at
staleness window derived from advert_ttl_secs (with a grace multiplier).
The current in-tree STUN parser handles IPv4 and IPv6 mapped-address
attributes. Local traversal candidates include active non-loopback private
interface addresses (RFC1918 IPv4 and IPv6 ULA) plus probed local egress
addresses for the punch socket port.
During punching, compatible private-subnet candidates and reflexive candidates
are attempted in parallel; the first successful path wins.
Spanning Tree (node.tree.*)
Controls tree construction and parent selection.
| Parameter | Type | Default | Description |
|---|---|---|---|
node.tree.announce_min_interval_ms |
u64 | 500 |
Per-peer TreeAnnounce rate limit |
node.tree.parent_hysteresis |
f64 | 0.2 |
Cost improvement fraction required for same-root parent switch (0.0–1.0) |
node.tree.hold_down_secs |
u64 | 30 |
Suppress non-mandatory re-evaluation after parent switch |
node.tree.reeval_interval_secs |
u64 | 60 |
Periodic cost-based parent re-evaluation interval (0 = disabled) |
node.tree.flap_threshold |
u32 | 4 |
Parent switches in window before dampening engages |
node.tree.flap_window_secs |
u64 | 60 |
Sliding window for counting parent switches |
node.tree.flap_dampening_secs |
u64 | 120 |
Extended hold-down duration when flap threshold exceeded |
Bloom Filter (node.bloom.*)
| Parameter | Type | Default | Description |
|---|---|---|---|
node.bloom.update_debounce_ms |
u64 | 500 |
Debounce interval for filter update propagation |
Bloom filter size (1 KB), hash count (5), and size classes are protocol constants and not configurable.
ECN Signaling (node.ecn.*)
Controls hop-by-hop ECN (Explicit Congestion Notification) signaling. When enabled, transit nodes detect congestion on outgoing links (via MMP loss/ETX metrics or kernel buffer drops) and set the CE flag on forwarded FMP frames. Destination nodes mark ECN-capable IPv6 packets with CE before TUN delivery per RFC 3168, enabling end-host TCP congestion control to react.
| Parameter | Type | Default | Description |
|---|---|---|---|
node.ecn.enabled |
bool | true |
Enable ECN congestion signaling (CE flag relay and local congestion detection) |
node.ecn.loss_threshold |
f64 | 0.05 |
MMP loss rate threshold for CE marking (0.0–1.0). When the outgoing link's loss rate meets or exceeds this value, forwarded packets are CE-marked. |
node.ecn.etx_threshold |
f64 | 3.0 |
MMP ETX threshold for CE marking (≥1.0). When the outgoing link's ETX meets or exceeds this value, forwarded packets are CE-marked. |
Congestion detection triggers on any of: outgoing link loss ≥ loss_threshold,
outgoing link ETX ≥ etx_threshold, or kernel receive buffer drops detected on
any local transport. CE is relayed hop-by-hop: once set on any hop, the flag
stays set for all subsequent hops to the destination.
Rekey (node.rekey.*)
Controls periodic Noise rekey for forward secrecy. When enabled, both FMP (link-layer IK) and FSP (session-layer XK) sessions perform fresh Diffie-Hellman key exchanges after a time or message count threshold, whichever comes first. A 10-second drain window keeps the old session active for decryption during cutover.
| Parameter | Type | Default | Description |
|---|---|---|---|
node.rekey.enabled |
bool | true |
Enable periodic Noise rekey on all links and sessions |
node.rekey.after_secs |
u64 | 120 |
Initiate rekey after this many seconds on a session |
node.rekey.after_messages |
u64 | 65536 |
Initiate rekey after this many messages sent on a session |
Session / Data Plane (node.session.*)
Controls end-to-end session behavior and packet queuing.
| Parameter | Type | Default | Description |
|---|---|---|---|
node.session.default_ttl |
u8 | 64 |
Default SessionDatagram TTL |
node.session.pending_packets_per_dest |
usize | 16 |
Queue depth per destination during session establishment |
node.session.pending_max_destinations |
usize | 256 |
Max destinations with pending packets |
node.session.idle_timeout_secs |
u64 | 90 |
Idle session timeout; established sessions with no application data for this duration are removed. MMP reports (SenderReport, ReceiverReport, PathMtuNotification) do not count as activity |
node.session.coords_warmup_packets |
u8 | 5 |
Number of initial data packets per session that include the CP flag for transit cache warmup; also the reset count on CoordsRequired/PathBroken receipt |
node.session.coords_response_interval_ms |
u64 | 2000 |
Minimum interval (ms) between standalone CoordsWarmup responses to CoordsRequired/PathBroken signals per destination |
The anti-replay window size (2048 packets) is a compile-time constant and not configurable.
Link-Layer MMP (node.mmp.*)
Metrics Measurement Protocol for per-peer link measurement. See fips-mesh-layer.md for behavioral details.
| Parameter | Type | Default | Description |
|---|---|---|---|
node.mmp.mode |
string | "full" |
Operating mode: full (sender + receiver reports), lightweight (receiver reports only), or minimal (spin bit + CE echo only, no reports) |
node.mmp.log_interval_secs |
u64 | 30 |
Periodic operator log interval for link metrics |
node.mmp.owd_window_size |
usize | 32 |
One-way delay trend ring buffer size |
Session-Layer MMP (node.session_mmp.*)
Metrics Measurement Protocol for end-to-end session measurement. Configured independently from link-layer MMP because session reports are routed through every transit link, consuming bandwidth proportional to path length.
| Parameter | Type | Default | Description |
|---|---|---|---|
node.session_mmp.mode |
string | "full" |
Operating mode: full, lightweight, or minimal |
node.session_mmp.log_interval_secs |
u64 | 30 |
Periodic operator log interval for session metrics |
node.session_mmp.owd_window_size |
usize | 32 |
One-way delay trend ring buffer size |
Internal Buffers (node.buffers.*)
Channel sizes affecting throughput and memory. Primarily useful for performance tuning under high load or on memory-constrained devices.
| Parameter | Type | Default | Description |
|---|---|---|---|
node.buffers.packet_channel |
usize | 1024 |
Transport to Node packet channel capacity |
node.buffers.tun_channel |
usize | 1024 |
TUN to Node outbound channel capacity |
node.buffers.dns_channel |
usize | 64 |
DNS to Node identity channel capacity |
TUN Interface (tun.*)
| Parameter | Type | Default | Description |
|---|---|---|---|
tun.enabled |
bool | false |
Enable TUN virtual interface |
tun.name |
string | "fips0" |
Interface name |
tun.mtu |
u16 | 1280 |
Interface MTU (IPv6 minimum) |
DNS Responder (dns.*)
Resolves <npub>.fips queries to FIPS IPv6 addresses. Resolution is pure
computation (npub to public key to address); resolved identities are registered
with the node for routing.
| Parameter | Type | Default | Description |
|---|---|---|---|
dns.enabled |
bool | true |
Enable DNS responder |
dns.bind_addr |
string | "127.0.0.1" |
Bind address |
dns.port |
u16 | 5354 |
Listen port |
dns.ttl |
u32 | 300 |
AAAA record TTL in seconds |
The dns.ttl value should not exceed node.cache.coord_ttl_secs to avoid
stale address mappings.
Host Mapping
The DNS resolver checks a host map before falling back to direct npub
resolution, enabling names like gateway.fips instead of npub1...fips.
The host map is populated from two sources:
- Peer aliases — the
aliasfield on configured peers inpeers:. - Hosts file —
/etc/fips/hosts, onehostname npub1...per line. Blank lines and#comments are allowed.
The hosts file is auto-reloaded on modification (mtime change) without restarting the daemon. Hostnames are case-insensitive.
Transports (transports.*)
UDP (transports.udp.*)
| Parameter | Type | Default | Description |
|---|---|---|---|
transports.udp.bind_addr |
string | "0.0.0.0:2121" |
UDP bind address and port |
transports.udp.mtu |
u16 | 1280 |
Transport MTU |
transports.udp.recv_buf_size |
usize | 2097152 |
UDP socket receive buffer size in bytes (2 MB). Linux kernel doubles the requested value internally. Host net.core.rmem_max must be >= this value. |
transports.udp.send_buf_size |
usize | 2097152 |
UDP socket send buffer size in bytes (2 MB). Host net.core.wmem_max must be >= this value. |
transports.udp.advertise_on_nostr |
bool | false |
Include this UDP transport in Nostr endpoint adverts |
transports.udp.public |
bool | false |
If advertised: true publishes direct host:port; false publishes udp:nat rendezvous |
Ethernet (transports.ethernet.*)
Ethernet transport sends raw frames via AF_PACKET SOCK_DGRAM sockets.
Requires CAP_NET_RAW or running as root. Linux only.
| Parameter | Type | Default | Description |
|---|---|---|---|
interface |
string | (required) | Network interface name (e.g., "eth0", "enp3s0") |
ethertype |
u16 | 0x2121 |
EtherType |
mtu |
u16 | (auto) | Override MTU. Default: interface MTU minus 3 (for frame type + length prefix) |
recv_buf_size |
usize | 2097152 |
Socket receive buffer size in bytes (2 MB) |
send_buf_size |
usize | 2097152 |
Socket send buffer size in bytes (2 MB) |
discovery |
bool | true |
Listen for discovery beacons from other nodes |
announce |
bool | false |
Broadcast announcement beacons on the LAN |
auto_connect |
bool | false |
Auto-connect to discovered peers |
accept_connections |
bool | false |
Accept incoming connection attempts from discovered peers |
beacon_interval_secs |
u64 | 30 |
Announcement beacon interval in seconds (minimum 10) |
Named instances. Multiple Ethernet interfaces can be configured by using named sub-keys instead of flat parameters:
transports:
ethernet:
lan:
interface: "eth0"
discovery: true
announce: true
backbone:
interface: "eth1"
announce: false
Each named instance operates independently with its own socket and
discovery state. The instance name is used in log messages and the
name() method on the Transport trait.
TCP (transports.tcp.*)
TCP transport enables firewall traversal on networks that block UDP but allow TCP (e.g., port 443). Uses FMP header-based framing with zero overhead.
| Parameter | Type | Default | Description |
|---|---|---|---|
transports.tcp.bind_addr |
string | (none) | Listen address (e.g., "0.0.0.0:8443"). If omitted, outbound-only mode. |
transports.tcp.mtu |
u16 | 1400 |
Default MTU. Per-connection MTU derived from TCP_MAXSEG when available. |
transports.tcp.connect_timeout_ms |
u64 | 5000 |
Outbound connect timeout in milliseconds |
transports.tcp.nodelay |
bool | true |
TCP_NODELAY (disable Nagle for low latency) |
transports.tcp.keepalive_secs |
u64 | 30 |
TCP keepalive interval in seconds (0 = disabled) |
transports.tcp.recv_buf_size |
usize | 2097152 |
Socket receive buffer size in bytes (2 MB) |
transports.tcp.send_buf_size |
usize | 2097152 |
Socket send buffer size in bytes (2 MB) |
transports.tcp.max_inbound_connections |
usize | 256 |
Maximum simultaneous inbound connections |
Named instances. Like other transports, multiple TCP instances can be configured with named sub-keys:
transports:
tcp:
public:
bind_addr: "0.0.0.0:443"
internal:
bind_addr: "10.0.0.1:8443"
max_inbound_connections: 64
Tor (transports.tor.*)
Tor transport routes FIPS traffic through the Tor network for anonymity.
Requires an external Tor daemon providing a SOCKS5 proxy. Three modes:
socks5 for outbound-only, control_port for outbound + monitoring,
directory for outbound + inbound via Tor-managed onion service.
| Parameter | Type | Default | Description |
|---|---|---|---|
transports.tor.mode |
string | "socks5" |
Tor access mode: socks5 (outbound only), control_port (outbound + monitoring), or directory (outbound + inbound onion service) |
transports.tor.socks5_addr |
string | "127.0.0.1:9050" |
SOCKS5 proxy address (host:port) |
transports.tor.connect_timeout_ms |
u64 | 120000 |
Connect timeout in milliseconds. Tor circuits take 10–60s. |
transports.tor.mtu |
u16 | 1400 |
Default MTU |
transports.tor.control_addr |
string | "/run/tor/control" |
Tor control port address: Unix socket path or host:port. Used in control_port mode; optional in directory mode for monitoring. |
transports.tor.control_auth |
string | "cookie" |
Control port authentication: "cookie", "cookie:/path/to/cookie", or "password:<secret>". |
transports.tor.cookie_path |
string | "/var/run/tor/control.authcookie" |
Path to Tor control cookie file. Used when control_auth is "cookie". |
transports.tor.max_inbound_connections |
usize | 64 |
Maximum inbound connections via onion service. |
transports.tor.directory_service.hostname_file |
string | "/var/lib/tor/fips_onion_service/hostname" |
Path to Tor-managed hostname file containing the .onion address. |
transports.tor.directory_service.bind_addr |
string | "127.0.0.1:8443" |
Local bind address for the listener that Tor forwards inbound connections to. Must match HiddenServicePort target in torrc. |
Named instances. Like other transports, multiple Tor instances can be configured with named sub-keys for different SOCKS5 proxy endpoints.
Directory mode (recommended for production). Tor manages the onion
service via HiddenServiceDir in torrc. FIPS reads the .onion
address from the hostname file and binds a local TCP listener. This
enables Tor's Sandbox 1 (seccomp-bpf). If control_addr is also
set, the transport connects to the control port for daemon monitoring
(non-fatal on failure).
Control port mode. Connects to the Tor daemon's control port for
monitoring only (bootstrap status, circuit health, traffic stats).
No inbound connections. Both control_addr and control_auth are
required.
UDP + Tor Bridge Example
A node bridging clearnet (UDP) and anonymous (Tor) portions of the mesh:
node:
identity:
persistent: true
tun:
enabled: true
transports:
udp:
bind_addr: "0.0.0.0:2121"
mtu: 1472
tor:
socks5_addr: "127.0.0.1:9050"
peers:
- npub: "npub1abc..."
alias: "clearnet-peer"
addresses:
- transport: udp
addr: "203.0.113.5:2121"
- npub: "npub1def..."
alias: "anonymous-peer"
addresses:
- transport: tor
addr: "abc123...xyz.onion:2121"
Tor Directory Mode Example
A node accepting inbound connections via Tor-managed onion service (recommended for production — enables Sandbox 1):
node:
identity:
persistent: true
tun:
enabled: true
transports:
tor:
mode: "directory"
socks5_addr: "127.0.0.1:9050"
control_addr: "/run/tor/control" # optional, for monitoring
control_auth: "cookie"
directory_service:
hostname_file: "/var/lib/tor/fips/hostname"
bind_addr: "127.0.0.1:8444"
peers:
- npub: "npub1abc..."
alias: "tor-peer"
addresses:
- transport: tor
addr: "abcdef...xyz.onion:8443"
Requires a corresponding torrc:
HiddenServiceDir /var/lib/tor/fips
HiddenServicePort 8443 127.0.0.1:8444
BLE (transports.ble.*)
Bluetooth Low Energy transport using L2CAP Connection-Oriented Channels.
Requires BlueZ and the ble Cargo feature flag (default-on). Linux only;
guarded by #[cfg(target_os = "linux")]. Communicates with BlueZ via D-Bus
using the bluer crate.
| Parameter | Type | Default | Description |
|---|---|---|---|
transports.ble.adapter |
string | "hci0" |
HCI adapter name |
transports.ble.psm |
u16 | 0x0085 (133) |
L2CAP Protocol/Service Multiplexer |
transports.ble.mtu |
u16 | 2048 |
Default MTU. Actual MTU is negotiated per-link during L2CAP connection setup. |
transports.ble.max_connections |
usize | 7 |
Maximum concurrent BLE connections |
transports.ble.connect_timeout_ms |
u64 | 10000 |
Outbound connect timeout in milliseconds |
transports.ble.advertise |
bool | true |
Broadcast BLE beacon advertisements for peer discovery |
transports.ble.scan |
bool | true |
Listen for BLE beacon advertisements from other nodes |
transports.ble.auto_connect |
bool | false |
Automatically connect to discovered peers |
transports.ble.accept_connections |
bool | true |
Accept incoming L2CAP connections |
transports.ble.probe_cooldown_secs |
u64 | 30 |
Cooldown before re-probing the same BLE address |
Address format. BLE peer addresses use the form
"adapter/device_address" — for example, "hci0/AA:BB:CC:DD:EE:FF".
Advertising and scanning. When advertise is enabled, the transport
advertises the FIPS service UUID continuously so that nearby nodes can
discover and connect via L2CAP. When scan is enabled, the transport
continuously scans for other FIPS nodes' advertisements. Discovered
peers are probed immediately (L2CAP connect + pubkey exchange) with a
cooldown (probe_cooldown_secs) to prevent rapid re-probing of the same
address. If two nodes probe each other at the same time (cross-probe),
a deterministic tie-breaker based on NodeAddr comparison ensures only
one connection is established.
Connection pool. The max_connections parameter limits the number of
concurrent BLE connections. When the pool is full, the least-recently-used
connection is evicted to make room for new connections.
BLE Example
A node using BLE for local mesh discovery alongside UDP for internet peers:
node:
identity:
persistent: true
tun:
enabled: true
transports:
udp:
bind_addr: "0.0.0.0:2121"
ble:
adapter: "hci0"
advertise: true
scan: true
auto_connect: true
accept_connections: true
peers:
- npub: "npub1abc..."
alias: "internet-peer"
addresses:
- transport: udp
addr: "203.0.113.5:2121"
connect_policy: auto_connect
BLE peers on the local radio range are discovered automatically via beacons — no static peer entries needed. Internet peers still require explicit configuration.
Peers (peers[])
Static peer list. Each entry defines a peer to connect to.
| Parameter | Type | Default | Description |
|---|---|---|---|
peers[].npub |
string | (required) | Peer's Nostr public key (npub-encoded) |
peers[].alias |
string | (none) | Human-readable name for logging |
peers[].addresses[].transport |
string | (required) | Transport type: udp, tcp, ethernet, tor, or ble |
peers[].addresses[].addr |
string | (required) | Transport address. UDP/TCP: "host:port" (IP or DNS hostname). Ethernet: "interface/mac" (e.g., "eth0/aa:bb:cc:dd:ee:ff"). BLE: "adapter/device_address" (e.g., "hci0/AA:BB:CC:DD:EE:FF"). Tor: ".onion:port" or "host:port" |
peers[].addresses[].priority |
u8 | 100 |
Address priority (lower = preferred) |
peers[].connect_policy |
string | "auto_connect" |
Connection policy: auto_connect, on_demand, or manual |
peers[].auto_reconnect |
bool | true |
Automatically reconnect after MMP link-dead removal (exponential backoff, unlimited retries) |
peers[].via_nostr |
bool | false |
Append Nostr advert-derived endpoints after static addresses for this peer |
Minimal Example
A typical node configuration enabling TUN, DNS, and a single peer:
node:
identity:
nsec: "0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20"
tun:
enabled: true
name: fips0
mtu: 1280
dns:
enabled: true
bind_addr: "127.0.0.1"
port: 53
transports:
udp:
bind_addr: "0.0.0.0:2121"
mtu: 1472
peers:
- npub: "npub1tdwa4vjrjl33pcjdpf2t4p027nl86xrx24g4d3avg4vwvayr3g8qhd84le"
alias: "node-b"
addresses:
- transport: udp
addr: "172.20.0.11:2121"
connect_policy: auto_connect
Mixed UDP + Ethernet Example
A node bridging internet peers (UDP) and a local Ethernet segment with beacon discovery:
node:
identity:
nsec: "0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20"
tun:
enabled: true
transports:
udp:
bind_addr: "0.0.0.0:2121"
mtu: 1472
ethernet:
interface: "eth0"
discovery: true
announce: true
auto_connect: true
accept_connections: true
peers:
- npub: "npub1tdwa4vjrjl33pcjdpf2t4p027nl86xrx24g4d3avg4vwvayr3g8qhd84le"
alias: "internet-peer"
addresses:
- transport: udp
addr: "203.0.113.5:2121"
connect_policy: auto_connect
Ethernet peers on the local segment are discovered automatically via beacons — no static peer entries needed. Internet peers still require explicit configuration.
All node.* parameters use their defaults. To override specific values, add
only the relevant sections:
node:
identity:
nsec: "..."
limits:
max_peers: 64
retry:
max_retries: 10
max_backoff_secs: 600
cache:
coord_size: 100000
Complete Reference
The full YAML structure with all defaults:
node:
identity:
nsec: null # secret key in nsec or hex (null = depends on persistent)
persistent: false # true = load/save fips.key; false = ephemeral each start
leaf_only: false
tick_interval_secs: 1
base_rtt_ms: 100
heartbeat_interval_secs: 10
link_dead_timeout_secs: 30
limits:
max_connections: 256
max_peers: 128
max_links: 256
max_pending_inbound: 1000
rate_limit:
handshake_burst: 100
handshake_rate: 10.0
handshake_timeout_secs: 30
handshake_resend_interval_ms: 1000
handshake_resend_backoff: 2.0
handshake_max_resends: 5
retry:
max_retries: 5
base_interval_secs: 5
max_backoff_secs: 300
cache:
coord_size: 50000
coord_ttl_secs: 300
identity_size: 10000
discovery:
ttl: 64
attempt_timeouts_secs: [1, 2, 4, 8]
recent_expiry_secs: 10
backoff_base_secs: 0
backoff_max_secs: 0
forward_min_interval_secs: 2
tree:
announce_min_interval_ms: 500
parent_hysteresis: 0.2 # cost improvement fraction for parent switch
hold_down_secs: 30 # suppress re-evaluation after switch
reeval_interval_secs: 60 # periodic cost-based re-evaluation (0 = disabled)
flap_threshold: 4 # parent switches before dampening
flap_window_secs: 60 # sliding window for flap detection
flap_dampening_secs: 120 # extended hold-down on flap
bloom:
update_debounce_ms: 500
session:
default_ttl: 64
pending_packets_per_dest: 16
pending_max_destinations: 256
idle_timeout_secs: 90
coords_warmup_packets: 5
coords_response_interval_ms: 2000
mmp:
mode: full # full | lightweight | minimal
log_interval_secs: 30
owd_window_size: 32
session_mmp:
mode: full # full | lightweight | minimal
log_interval_secs: 30
owd_window_size: 32
ecn:
enabled: true # ECN congestion signaling (CE flag relay)
loss_threshold: 0.05 # MMP loss rate threshold for CE marking (5%)
etx_threshold: 3.0 # MMP ETX threshold for CE marking
rekey:
enabled: true # periodic Noise rekey for forward secrecy
after_secs: 120 # rekey interval (seconds)
after_messages: 65536 # rekey after N messages sent
control:
enabled: true
socket_path: null # null = auto ($XDG_RUNTIME_DIR → /run/fips → /tmp fallback)
buffers:
packet_channel: 1024
tun_channel: 1024
dns_channel: 64
tun:
enabled: false
name: "fips0"
mtu: 1280
dns:
enabled: true
bind_addr: "127.0.0.1"
port: 5354
ttl: 300
transports:
udp:
bind_addr: "0.0.0.0:2121"
mtu: 1280
recv_buf_size: 2097152 # 2 MB (kernel doubles to 4 MB actual)
send_buf_size: 2097152 # 2 MB
# ethernet: # uncomment to enable (requires CAP_NET_RAW)
# interface: "eth0" # required: network interface name
# ethertype: 0x2121 # default EtherType
# mtu: null # null = interface MTU - 3 (typically 1497)
# recv_buf_size: 2097152 # 2 MB
# send_buf_size: 2097152 # 2 MB
# discovery: true # listen for beacons
# announce: false # broadcast beacons
# auto_connect: false # connect to discovered peers
# accept_connections: false # accept inbound handshakes
# beacon_interval_secs: 30 # beacon interval (min 10)
# tcp: # uncomment to enable TCP transport
# bind_addr: "0.0.0.0:8443" # listen address (omit for outbound-only)
# mtu: 1400 # default MTU
# connect_timeout_ms: 5000 # outbound connect timeout
# nodelay: true # TCP_NODELAY
# keepalive_secs: 30 # keepalive interval (0 = disabled)
# recv_buf_size: 2097152 # 2 MB
# send_buf_size: 2097152 # 2 MB
# max_inbound_connections: 256 # resource protection limit
# tor: # uncomment to enable Tor transport
# mode: "socks5" # "socks5", "control_port", or "directory"
# socks5_addr: "127.0.0.1:9050" # SOCKS5 proxy address
# connect_timeout_ms: 120000 # connect timeout (120s for Tor circuits)
# mtu: 1400 # default MTU
# # monitoring (control_port mode, or optional in directory mode):
# # control_addr: "/run/tor/control" # Unix socket or host:port
# # control_auth: "cookie" # "cookie" or "password:<secret>"
# # cookie_path: "/var/run/tor/control.authcookie"
# # directory mode (inbound via Tor-managed onion service):
# # directory_service:
# # hostname_file: "/var/lib/tor/fips/hostname"
# # bind_addr: "127.0.0.1:8444"
# # max_inbound_connections: 64
# ble: # uncomment to enable BLE transport (Linux only, requires BlueZ)
# adapter: "hci0" # HCI adapter name
# psm: 0x0085 # L2CAP PSM (133)
# mtu: 2048 # default MTU (negotiated per-link)
# max_connections: 7 # max concurrent BLE connections
# connect_timeout_ms: 10000 # outbound connect timeout
# advertise: true # broadcast BLE beacons
# scan: true # listen for BLE beacons
# auto_connect: false # connect to discovered peers
# accept_connections: true # accept incoming L2CAP connections
# probe_cooldown_secs: 30 # cooldown before re-probing same address
peers: # static peer list
# - npub: "npub1..."
# alias: "node-b"
# addresses:
# - transport: udp
# addr: "10.0.0.2:2121"
# priority: 100
# connect_policy: auto_connect
# auto_reconnect: true # reconnect after link-dead removal