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/1provider 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.
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
externalto 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.