Configuration

The settings the relay server, link-relay, reads. Each is a flag, and most can also come from a variable: link-relay --help names both, and lnk help <command> lists the variables each command reads, as Cargo.toml declares them.

On a server, bootstrap.sh writes the settings to /etc/link/relay.env (root-only), which the systemd unit loads. Change one with bootstrap's flag, or edit the file and run systemctl restart link-relay.

Its systemd unit

On a server, the systemd unit (plugins/networking/relay/deploy/files/link-relay.service) also limits the relay's open files, memory, threads, system calls and sockets: the server's security. Bootstrap installs it; re-run bootstrap after changing it.

Its job

Which of the three jobs a relay does, and what each needs.

--role (LINK_ROLE)

The one job this relay does: tunnels, users' tunnels (the default); remote, machines' connections reached by their owners; or hooks, the one tunnel --hooks-tunnel names, at /h/. Remote and hooks serve no public host, remote needs --accounts-url, and hooks takes no --website.

--hooks-tunnel (LINK_HOOKS_TUNNEL)

With --role hooks: the one tunnel it serves, <owner>/<tunnel>, the owner an account's ID (acct-...) or a --users-file name.

--machines-per-user (LINK_MACHINES_PER_USER)

With --role remote: the machines one account may hold connected, 100 unless set. It must let an account hold one.

Where it's reached

The address it listens on, the proxies in front of it, and the addresses it serves.

--listen (LINK_LISTEN)

The address to accept public requests and agent connections on, 127.0.0.1:7080 unless set.

--trusted-proxies (LINK_TRUSTED_PROXIES)

Proxies in front of the relay, beside Caddy on this machine, whose X-Forwarded-For it believes (a load balancer's ranges): each <address>[/<prefix>], separated by commas, none wider than a /8 (IPv4) or a /32 (IPv6). A visitor is the first entry from the right none of them sent, and their limits are kept by it.

--base-domain (LINK_DOMAIN)

The public base domain, with its port if non-standard, localhost:7080 unless set. Tunnels are served at <app>.<user>.<domain>.

--public-scheme

The scheme of public URLs, http or https: http for localhost domains and https otherwise, with TLS terminated in front of the relay, unless given.

--website (LINK_WEBSITE)

The website that browsing the bare domain redirects to, such as https://www.local.link. /_link/* and /install.sh stay on the relay.

Who signs in

The operator's own users, and the account service whose logins it takes.

--users-file (LINK_USERS_FILE)

A file of <username> <token> lines: the operator's own users. It's required unless --accounts-url is set, or the relay runs locally, a localhost domain on a loopback address.

--accounts-url (LINK_ACCOUNTS_URL)

The account service whose logins the relay takes: lnk auth login logs in there, and signs for access tokens there with its key, such as https://accounts.example.com. It's the service's origin, as its tokens name their issuer.

--accounts-key (LINK_ACCOUNTS_KEY)

The account service's public keys, which the relay checks its access tokens with, never asking it: each <id>:<key>, the key Ed25519's 32 bytes as base64url, separated by commas (its GET /api/v1/keys says them). It's required with --accounts-url.

Custom domains and state

Users' own domains, how they're proven, and where the relay keeps what it writes.

--domains-per-user (LINK_DOMAINS_PER_USER)

The custom domains each user may serve tunnels at (lnk tunnel open --domain), proven by a TXT record; 0 turns them off.

--dns-over-https (LINK_DNS_OVER_HTTPS)

The DNS-over-HTTPS service (JSON API) the relay reads custom domains' TXT records from.

--state-dir (LINK_STATE_DIR)

The directory for state the relay writes: blocked users, share links, the hosts approved for certificates and the custom domains proven.

Its measures and notice

Where it sends its own measures, and the message every agent gets.

--measures (LINK_MEASURES)

The OTLP endpoint the relay sends its own measures to, as JSON to <url>/v1/metrics: https://, or http:// to this machine, such as a collector beside it. Without it, it sends none.

--measures-every and --measures-machine

How often it sends them, as a duration, 60s unless set (LINK_MEASURES_EVERY), and the permanent ID of the machine hosting this relay, in its measures (LINK_MEASURES_MACHINE).

--measures-header-file (LINK_MEASURES_HEADER_FILE)

A private file of name: value headers for the OTLP endpoint, which authenticate a send.

--notice (LINK_NOTICE)

A message shown to every agent on connect, such as planned maintenance: lnk tunnel open shows it as its notice.

Off-site backups (/etc/link/backup.env)

Read by link-state backup, which runs nightly. Without this file, snapshots stay only on the server, in /var/backups/link. On your Mac, the same file is what fetch-backup.sh --env reads. It holds LINK_BACKUP_URL, LINK_BACKUP_REGION, LINK_BACKUP_KEY_ID and LINK_BACKUP_SECRET, and setup is in the runbook.

Its recipients

Uploads are encrypted to the public keys in /etc/link/backup-recipients, one ssh-ed25519 …, ssh-rsa … or age1… key per line. Without a key there, the backup refuses to upload.