1# Iroh relays
2
3Clients use `https://r1.iroh.paperclover.net` and
4`https://r2.iroh.paperclover.net`. Caddy terminates HTTPS on TCP 443; Iroh serves
5QUIC address discovery on UDP 7842. TCP 80 remains available for ACME.
6These are public relays without an application login.
7
8The upstream binary version and checksum live in
9[`Dockerfile`](../service/iroh-relay/Dockerfile). Both machines use
10[`run.py`](../service/iroh-relay/run.py) and
11[`network.json`](../service/iroh-relay/network.json).
12Iroh's `--dev` flag disables its HTTPS listener behind Caddy, while its
13`Reloading` certificate resolver still supplies valid TLS for UDP discovery.
14
15## Snow Globe
16
17[`service.pkl`](../service/iroh-relay/service.pkl) declares the relay and its
18certificate sidecar. The sidecar obtains the Cloudflare credential through the
19DDNS provider, keeps it in a private tmpfs file, and checks certificate renewal
20every twelve hours. Only the certificate volume is shared with the relay.
21The relay reloads renewed certificates without restarting connections.
22
23Stage and deploy with the normal `tools/deploy.py` workflow. Fresh previews have
24their own certificate storage and dynamically allocated UDP port; they do not
25bind production's port. The host's `public-ports.service` maintains the production
26router mapping; the firewall declaration is in `nixos/snowglobe.nix`.
27
28## paperclover.net
29
30Connect with `ssh root@paperclover.net`; the hostname is `usw-server-1`.
31The checksum-verified upstream binary is installed at `/usr/local/bin/iroh-relay`.
32Install `run.py` and `network.json` into `/usr/local/lib/iroh-relay/`, and
33[`iroh-relay.service`](../service/iroh-relay/iroh-relay.service) into
34`/etc/systemd/system/`.
35
36The unit sets `METRICS_ADDR`, so the relay serves metrics on `127.0.0.1:9091` for
37[vmagent](vps.md).
38
39[`r1.caddy`](../service/iroh-relay/r1.caddy) is installed as
40`/etc/caddy/Caddyfile.d/iroh-relay.caddy`, explicitly imported by the main
41Caddyfile. Validate before reloading Caddy. The ACME webroot is
42`/var/lib/iroh-acme`; Caddy must be able to read it.
43
44After Caddy's HTTPS certificate is ready, issue the discovery certificate:
45
46```sh
47certbot certonly --non-interactive --agree-tos --email account@paperclover.net \
48 --webroot -w /var/lib/iroh-acme --cert-name iroh-relay \
49 -d r1.iroh.paperclover.net \
50 --deploy-hook 'systemctl try-restart iroh-relay.service'
51systemctl daemon-reload
52systemctl enable --now iroh-relay.service certbot-renew.timer
53firewall-cmd --add-port=7842/udp
54firewall-cmd --permanent --add-port=7842/udp
55```
56
57Systemd loads the certificate and key as private service credentials. Certbot's
58renewal hook restarts the service to refresh those credentials. The key stays
59root-only under `/etc/letsencrypt`.
60
61## Verification
62
63`GET /healthz` reports the relay version, but does not test packet forwarding.
64Use two Iroh 1.3 endpoints with `clear_ip_transports()` and a custom relay map;
65transfer and verify a payload in both directions. For UDP, connect a
66`iroh_relay::quic::QuicClient` with normal CA validation and await its
67`observed_external_addr()` stream. Test from outside the server's network.
68
69Renewal can be exercised on r1 with
70`certbot renew --cert-name iroh-relay --dry-run --run-deploy-hooks`.
71Inspect the relay's restart count and health afterward.