| 1 | # Iroh relays |
| 2 | |
| 3 | Clients use `https://r1.iroh.paperclover.net` and |
| 4 | `https://r2.iroh.paperclover.net`. Caddy terminates HTTPS on TCP 443; Iroh serves |
| 5 | QUIC address discovery on UDP 7842. TCP 80 remains available for ACME. |
| 6 | These are public relays without an application login. |
| 7 | |
| 8 | The 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). |
| 12 | Iroh'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 |
| 18 | certificate sidecar. The sidecar obtains the Cloudflare credential through the |
| 19 | DDNS provider, keeps it in a private tmpfs file, and checks certificate renewal |
| 20 | every twelve hours. Only the certificate volume is shared with the relay. |
| 21 | The relay reloads renewed certificates without restarting connections. |
| 22 | |
| 23 | Stage and deploy with the normal `tools/deploy.py` workflow. Fresh previews have |
| 24 | their own certificate storage and dynamically allocated UDP port; they do not |
| 25 | bind production's port. The host's `public-ports.service` maintains the production |
| 26 | router mapping; the firewall declaration is in `nixos/snowglobe.nix`. |
| 27 | |
| 28 | ## paperclover.net |
| 29 | |
| 30 | Connect with `ssh root@paperclover.net`; the hostname is `usw-server-1`. |
| 31 | The checksum-verified upstream binary is installed at `/usr/local/bin/iroh-relay`. |
| 32 | Install `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 | |
| 36 | The 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 |
| 41 | Caddyfile. Validate before reloading Caddy. The ACME webroot is |
| 42 | `/var/lib/iroh-acme`; Caddy must be able to read it. |
| 43 | |
| 44 | After Caddy's HTTPS certificate is ready, issue the discovery certificate: |
| 45 | |
| 46 | ```sh |
| 47 | certbot 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' |
| 51 | systemctl daemon-reload |
| 52 | systemctl enable --now iroh-relay.service certbot-renew.timer |
| 53 | firewall-cmd --add-port=7842/udp |
| 54 | firewall-cmd --permanent --add-port=7842/udp |
| 55 | ``` |
| 56 | |
| 57 | Systemd loads the certificate and key as private service credentials. Certbot's |
| 58 | renewal hook restarts the service to refresh those credentials. The key stays |
| 59 | root-only under `/etc/letsencrypt`. |
| 60 | |
| 61 | ## Verification |
| 62 | |
| 63 | `GET /healthz` reports the relay version, but does not test packet forwarding. |
| 64 | Use two Iroh 1.3 endpoints with `clear_ip_transports()` and a custom relay map; |
| 65 | transfer 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 | |
| 69 | Renewal can be exercised on r1 with |
| 70 | `certbot renew --cert-name iroh-relay --dry-run --run-deploy-hooks`. |
| 71 | Inspect the relay's restart count and health afterward. |