Dial timeout due to private IP advertisement in Waku Relay

Question

Dial timeout due to private IP advertisement in Waku Relay

When a Waku Relay node is started with the default bootstrap list and no explicit public address, it successfully discovers peers via mDNS in a local test environment but, in a production deployment, logs show a dial timeout or missing address error because the node continues to advertise only private IP addresses (e.g., 127.0.0.1 or 192.168.x.x).

The goal is to determine whether the node should automatically enable libp2p NAT‑port‑mapping or require the operator to set a static external address or bootstrap relay, balancing ease of use against firewall and security considerations.

Should the default Waku Relay configuration activate NAT traversal out of the box, or must operators explicitly configure --nat-portmap or --external-ip for production? What are the trade‑offs of enabling automatic port mapping versus requiring manual address specification? How can a deployment verify that the chosen approach results in a publicly dialable multiaddress without introducing unnecessary exposure?

Tasadduq Burney · Answer

Short answer

For a production Waku Relay node, the safest default is to require operators to explicitly set a public address or enable NAT‑port‑mapping (via --nat-portmap or --external-ip). Auto‑enabling NAT traversal without operator input can expose unnecessary ports and may not work if the NAT does not support UPnP/NAT‑PMP.

Why the dial timeout happens

When a node advertises a private IP (e.g., 192.168.x.x or 10.x.x.x), peers on the public internet will try to open a TCP connection to that address. Since the address is non‑routable, the connection attempt times out, producing logs like:

dialing 10.0.0.5:4001 failed: timeout

This is not a problem with the node itself but with the address it advertises.

Confirmed facts

Waku Relay uses libp2p; each node publishes its multiaddresses in the /p2p/ table.
libp2p will only try NAT port mapping if the node advertises a public address or if the --nat-portmap flag is enabled.
Using a public relay (e.g., a dedicated libp2p relay node) bypasses the need for a public IP, but the relay must be reachable and online.
Enabling NAT traversal may open additional ports on the node’s firewall, potentially exposing it to unwanted traffic.

Trade‑offs

Automatic NAT‑port‑mapping
- Pros: Minimal operator effort; node can become reachable without manual port forwarding.
- Cons: Requires UPnP/NAT‑PMP support; opens ports that may be visible to the internet; may fail if the NAT blocks port mapping.
Manual external‑IP or bootstrap relay
- Pros: Full control over which address is advertised; no reliance on NAT‑PMP; can use a hardened relay for additional security.
- Cons: Operators must configure the correct public IP or relay address; requires initial setup and periodic verification.

Recommended steps for a production node

Check current advertised addresses
```
waku node status
# or
waku node info
```
Look for any /ip4/192.168.x.x or /ip4/10.x.x.x entries. If present, the node is advertising private addresses.
Choose a strategy
- To use NAT‑port‑mapping, start the node with --nat-portmap (or --nat depending on the binary).
- To provide a static external address, use --external-ip <public‑ip> or set the waku.external_ip config parameter.
- Alternatively, point the node to a reliable libp2p relay by adding a bootstrap address ending in /p2p-circuit.
Verify reachability
- From an external machine, run nc -vz <advertised_public_ip> 4001 to confirm the port is open.
- Check the node logs for any remaining dial‑timeout entries targeting private IPs.
- Use waku node info again to confirm the multiaddress list now contains only routable addresses (e.g., /ip4/203.0.113.42/tcp/4001).
Monitor continuously
- Set up a simple health check that queries waku node status and parses the multiaddresses.
- Alert if any private IPs appear again, indicating a configuration drift or NAT failure.

What to ask next

To fine‑tune the recommendation, could you confirm whether your NAT device supports UPnP or NAT‑PMP? This determines how reliably automatic port mapping will work.

Dial timeout due to private IP advertisement in Waku Relay