HTTPS certificates

A machine can get a trusted certificate for its full name (like grafana-box.acme.<domain>) from Let's Encrypt. Browsers then show a normal padlock, with no warnings and no self-signed certificates to install.

Before you start

On the dashboard's DNS page:

1. Give your workspace its own network name (for example acme).
2. Turn on HTTPS certificates.

Get a certificate

On a machine where the app was installed with the install command or the Windows installer, point cert at the background service's state folder:

# Linux and macOS
sudo underpass cert --state-dir /var/lib/tailnetd

# Windows, as administrator
& "C:\Program Files\Tailnet\tailnet.exe" cert --state-dir "$env:ProgramData\TailnetService"

On a machine that runs standalone (underpass up --auth-key or underpass run), plain sudo underpass cert is enough.

It takes up to a minute and prints where the files are:

Certificate: /var/lib/tailnetd/certs/grafana-box.acme.….crt
Key:         /var/lib/tailnetd/certs/grafana-box.acme.….key

To also copy them where your web server reads them:

sudo underpass cert --state-dir /var/lib/tailnetd \
  --cert-file /etc/ssl/grafana.crt --key-file /etc/ssl/grafana.key

The private key is made on the machine and never leaves it; only a certificate request is sent.

Renewal

The certificate in the state folder renews on its own while the app runs, 30 days before it expires. Copies made with --cert-file and --key-file don't update themselves: run the command again, or point your web server at the files in the state folder.

Things to know

• A machine can get at most one new certificate per hour, unless its current one is within 30 days of expiring.
• The certificate covers exactly the machine's full name.