Run a relay

Run a Weirdnet relay

weirdnet-relay is a relay and bootstrap node for the Weirdnet network: it carries traffic for devices behind NAT, serves the DHT, and tells people and apps how to reach it.

weirdnet-relay is new and being finished. Commands and settings below are those of version 0.1.

What a relay does

  • Circuit relay v2: nodes behind NAT reserve a slot and are reachable through …/p2p/RELAY/p2p-circuit/p2p/NODE. Circuits have no time or data cap unless you set one.
  • Hole punching: peers that meet through the relay try DCUtR for a direct connection; the circuit is the fallback.
  • Bootstrap and DHT: Kademlia in server mode, and the /weirdnet/relay/1 provider record so nodes find it.
  • AutoNAT: answers the probes nodes use to learn whether they are reachable.
  • Info page: HTML and JSON with its name, peer id and addresses.
Phonecarrier NAT, dial-out onlyHome relayweirdnet-relayDesktopanywhere1 · reservation2 · dial …/p2p-circuit/p2p/PHONE3 · DCUtR hole punch: a direct connection when NAT allowsIf punching fails the circuit stays: relays are the fallback that always works.
Relays and hole punching: reserve a slot, get dialed through the circuit, upgrade to a direct path when possible.

Build and install

git clone https://github.com/WeirdBrains/weirdnet-relay
          cd weirdnet-relay
          cargo build --release
          sudo install -m 0755 target/release/weirdnet-relay /usr/bin/
          sudo install -d /etc/weirdnet-relay
          sudo install -m 0644 examples/relay.toml /etc/weirdnet-relay/relay.toml
          sudo install -m 0644 packaging/systemd/weirdnet-relay.service /etc/systemd/system/

Rust 1.99 or newer. SQLCipher is bundled; no system libraries are needed.

The database key

The relay keeps its node key and its state in one SQLCipher database, relay.db, encrypted with a 32-byte key you supply. It never stores that key. Make one and hand it to systemd as a credential, so it never sits in the config or the environment:

weirdnet-relay gen-key | sudo systemd-creds encrypt --name=db-key - /etc/weirdnet-relay/db-key.cred

The unit loads it with LoadCredentialEncrypted=db-key:/etc/weirdnet-relay/db-key.cred, and the relay reads $CREDENTIALS_DIRECTORY/db-key. Outside systemd, pass --db-key-file (64 hex characters or 32 raw bytes, readable only by the relay). Keep a backup of the key: without it the relay gets a new identity.

Configure

name = "My relay"
          operator = "Me"
          contact = "abuse@example.com"
          
          [network]
          port = 4747
          external = ["/dns4/relay.example.com/tcp/4747", "/dns4/relay.example.com/udp/4747/quic-v1"]
          bootstrap = []
          
          [limits]            # no caps unless you set them
          # max_circuit_duration_secs = 3600
          # max_circuit_bytes = 0
          
          [http]
          listen = "127.0.0.1:4780"

Every setting also has a flag and a WEIRDNET_RELAY_* environment variable; flags win over the environment, which wins over the file. weirdnet-relay check-config validates a file and weirdnet-relay id prints the peer id.

Run it with systemd

sudo systemctl daemon-reload
          sudo systemctl enable --now weirdnet-relay
          journalctl -u weirdnet-relay -f

The unit runs as a dynamic user with StateDirectory=weirdnet-relay, a read-only system (ProtectSystem=strict), no home, private /tmp and devices, no new privileges, a system-call filter and no capabilities.

Ports and DNS

  • Open TCP and UDP 4747 (TCP and QUIC).
  • Set external to the addresses people reach you at; a relay only announces routable ones.
  • Self-hosted relays need a domain that follows the machine: tie one to it with Grindvakt dynamic DNS.
  • The info page listens on localhost; put it behind your web server with TLS to publish it.

The info page

GET / is a page for people. GET /.well-known/weirdnet-relay.json is for apps:

{
            "v": 1,
            "name": "My relay",
            "contact": "abuse@example.com",
            "software": "weirdnet-relay/0.1.0",
            "peer_id": "12D3KooW…",
            "addrs": ["/dns4/relay.example.com/tcp/4747/p2p/12D3KooW…",
                      "/dns4/relay.example.com/udp/4747/quic-v1/p2p/12D3KooW…"],
            "transports": ["tcp", "quic-v1"],
            "protocols": ["/libp2p/circuit/relay/0.2.0/hop", "/libp2p/dcutr", "/weirdnet/kad/1", "/weirdnet/id/1", "…"],
            "roles": ["relay", "bootstrap", "kad-server", "autonat"],
            "limits": { "max_circuit_duration_secs": null, "max_circuit_bytes": null }
          }

Adding a relay to an app

Give the full address, with /p2p/<peer id>, to the node’s relays and bootstrap settings. Morph and other Weirdnet apps can read the JSON above to fill them in; nodes behind NAT also find relays by themselves through the DHT.