Secure your own relay — access, device certificates and keys

What it is for

Your own relay can be reached from the internet and brokers access to all your devices. This page is a checklist: what to set after the installation so that only the right people get in, no foreign computer can pose as one of your devices, and your keys survive a server failure.

What you need

• Your own relay (B2) and a console account as system administrator.
• Access to the server (firewall, environment variables of the service).

How to do it

1. Network and certificate

1. Provide a real TLS certificate for the relay's name — RSA with the “ISRG Root X1” chain (B2).
2. Open only what the relay needs in the firewall: 9013/tcp, 3478/udp, 5349/tcp and, if set, the Relay ports from/Relay ports to range. Never open the database to the outside.
3. Run the relay without a reverse proxy that terminates TLS. It only evaluates the real peer address. Behind a proxy the per-address throttles and trusted networks do not work.

2. Console

1. Create named accounts and set up the second factor for each one (B4).
2. Give the emergency sign-in (without user name) a long password: Settings → Admin access → section Admin password → Change. The emergency sign-in has no second factor.
3. Restrict the console to your networks: Admin access → Trusted networks (B7).

3. Devices

1. Settings → Device certificates (mTLS). Every device gets its own certificate when it joins and identifies itself with it — so no foreign computer can pose as a known device.
2. Under Enforcement first turn on checking of presented certificates. Turn on enforcing the certificate only when all devices demonstrably connect via mTLS.
3. Devices that no longer have a certificate after a reinstallation wait under Enrollment requests. Check them and click Approve.
4. Decide per access who may control: Edit tenant → Governance policy → Control only from the device's own tenant (B6). Without this level, device ID and device password are enough.
5. Device passwords set centrally in older versions stay stored with a weaker method until you set them again: Devices → the device's menu → Set password.

4. Keys and backup

1. Set BD_KEYRING_KEY. With this value the relay encrypts its key ring. Docker writes it into .env during the installation. On Linux without the value the ring is stored unencrypted, and the relay warns at start-up. On Windows, Windows protects the ring for this machine.
2. Keep the value separately from the server, for example in a password manager — never in relay.json and never next to the backup.
3. Set a Backup passphrase (B8). Only then does the relay back up its keys.
4. Start every call of the program on the server (for example --set-setting) with the same environment as the service.

How you know it worked

• Every console sign-in asks for the code.
• The relay's start-up log no longer warns that the key ring is stored in plain text.
• The backup job no longer reports missing keys.

Good to know

• Losing BD_KEYRING_KEY means losing all encrypted values — device CA (all device certificates invalid), licence activation, passwords for mail and sign-in services.
• A program call without the value aborts if the ring is wrapped. That is intended; otherwise it would create new keys.
• Waiting viewers per address: at most five viewers without sign-in may wait for a device from one address at the same time (adjustable under Configuration → Server). Behind a proxy all of them share these five.
• Block a single device: Devices → the device's menu → Block. Reset its certificate: Reset certificate — the next join issues a new one.
• Suspicion that a copy of the database fell into the wrong hands: the key for sign-in tokens is renewed by a call to the administration API; there is no form for it. Afterwards all programs must join again. Write to info@browserdesk.de in that case.
• The server itself you harden like any other server (SSH with keys only, firewall, operating system updates). BrowserDesk does not provide its own guide for that.

If it does not work