Configuration

The scripts that set up, rebuild and back up a relay server, in plugins/networking/relay/deploy, and the flags each takes. When to run each is in the runbook, and the settings the relay itself reads are on the relay's Configuration.

bootstrap.sh

Run on the server as root, piped from your checkout, never from a download, so the release keys in it are the ones you trust. It turns an Ubuntu 24.04 server into a relay, or brings one up to date, keeping the users, certificates and settings already there. Settings marked "kept" are saved in /etc/link/relay.env and stay on later runs.

ssh root@relay.example.com 'bash -s -- --domain relay.example.com --email you@example.com --user dana' \
  < plugins/networking/relay/deploy/bootstrap.sh

--domain D, --email E and --user NAME

The public domain, required on the first run and kept afterwards; the Let's Encrypt contact for Caddy, required on the first run; and a user to create if there is no users file yet, whose token it prints once.

--accounts-url URL and --accounts-key KEYS

The account service whose logins it takes (lnk auth login logs in there), such as https://accounts.example.com, and its public keys, each <kid>:<key>, which its access tokens are checked with (its /api/v1/keys says them). The key is needed with the URL, and both are kept.

--website URL

Redirects browsers on the bare domain to this site, such as https://www.example.com, kept afterwards.

--state FILE

Restores a link-state export snapshot (users, settings, certificates) before starting. A snapshot is only as trustworthy as where it was kept.

--min-version V

Refuses a relay older than V; create-droplet.sh passes its checkout's version. The highest given is kept, in /etc/link/min-relay-version.

--from DIR

Installs the files in DIR, a folder on the server holding a copy of plugins/networking/relay/deploy/files, instead of the release's. It's for development: nothing in DIR is signature-checked.

create-droplet.sh

Run on your Mac. It needs doctl, logged in, and an SSH key on the DigitalOcean account. It creates a droplet and runs this checkout's bootstrap on it, with --min-version set to the checkout's version.

Its flags

--domain (local.link unless given), --email and --user (neither needed with --state), --state FILE to restore a snapshot, and --reserved-ip IP to point that reserved IP at the new droplet.

The droplet's own flags

--name (link-relay-<date> unless given), --region (nyc1), --size (s-1vcpu-512mb-10gb) and --ssh-keys, comma-separated key IDs or fingerprints, all on the account unless given.

rebuild.sh

Run on your Mac, with --old IP, the droplet to replace, and --reserved-ip IP, both required. Any other flag goes to create-droplet.sh. The old droplet keeps running until you delete it.

fetch-backup.sh

Run on your Mac; it needs age. It downloads an off-site backup and decrypts it into ./link-state-<time or latest>.tar.gz, ready for create-droplet.sh --state.

--env FILE

The same settings as /etc/link/backup.env on the server: LINK_BACKUP_URL, LINK_BACKUP_REGION, LINK_BACKUP_KEY_ID and LINK_BACKUP_SECRET.

--identity FILE and --name NAME

The private key matching a line of backup-recipients (~/.ssh/id_ed25519 unless given), and a specific backup, such as state-20260926T031500Z.tar.gz.age (state-latest.tar.gz.age unless given).

Environment variables

Mostly for testing the scripts. LNK_RELEASES_URL is where bootstrap and create-droplet.sh take the release from, the relay-latest release of so-local/link-releases unless set (no release publishes one now), and LINK_RELAY_BIN is the relay bootstrap checks the version of, /usr/local/bin/link-relay unless set.