HTTPS certificates
Let machines get Let's Encrypt certificates for their MagicDNS names, with slopscale publishing DNS-01 challenges through Cloudflare, RFC 2136, Hetzner, PowerDNS, acme-dns or a command.
A machine can get a TLS certificate for its MagicDNS name with
tailscale cert or tailscale serve, the way it does on Tailscale. The
client asks Let’s Encrypt for the certificate and proves it holds the name
with a DNS-01 challenge: a TXT record under _acme-challenge.<name>. It
cannot publish that record itself, so it sends it to the control server
over /machine/set-dns, and Slopscale publishes it in the zone that holds
the tailnet’s names.
This needs a base domain that is a real zone on the public internet, and a way for Slopscale to write to it.
Setting it up
dns:
base_domain: ts.example.com
https_certificates:
enabled: true
provider: cloudflare
cloudflare:
api_token_path: /run/credentials/slopscale.service/cloudflare-token
With enabled, every machine’s map response lists its MagicDNS name,
such as laptop.ts.example.com, as a cert domain, and the client picks
DNS-01 when it needs a certificate. The names only need to exist in
public DNS for the challenge record; they do not need to resolve to
anything, and the machines stay reachable over the tailnet alone, unless
Funnel opens one of them to the internet. The base domain
must be written in lowercase, because clients match certificate names
exactly.
The same provider publishes the server’s own certificate when
tls.acme.challenge_type is DNS-01 (see TLS), with or
without enabled.
Providers
Each provider’s settings sit under a key named after it. Any of them can
be read from a file instead, for secrets kept out of the configuration:
add _path to the key, as in api_token_path. The environment works key
by key too: SLOPSCALE_HTTPS_CERTIFICATES_CLOUDFLARE_API_TOKEN sets
https_certificates.cloudflare.api_token.
cloudflareuses the Cloudflare API withapi_token, a token holding Zone: Read and DNS: Edit on the zone. The zone is found from the record’s name, or pinned withzone_id, which needs only DNS: Edit.rfc2136sends a dynamic DNS update toserver(host and port), signed withtsig_key_name,tsig_secretandtsig_algorithm(hmac-sha256by default) when a key is set, and checks the signature of the reply. BIND, Knot and PowerDNS take these.hetzneruses the Hetzner Cloud DNS API withapi_token.powerdnsuses the PowerDNS API atserver_urlwithapi_token, onserver_id(localhostby default).acmednswrites to an acme-dns server. See below.commandruns the program atpathwith the record name and value as its two arguments, for any other zone, and the program atdelete_paththe same way to remove a record. Withoutdelete_pathrecords are left in place. A non-zero exit fails the call with the program’s output.
zone is the zone records are written to. It defaults to the
rfc2136.zone setting, then to the base domain, which must lie inside
it. ttl is the records’ time to live, a minute by default.
Propagation
The machine accepts the challenge the moment Slopscale answers, and
Let’s Encrypt looks the record up right away, but a provider’s API takes
a record some seconds before its nameservers serve it. So Slopscale
finds the zone’s authoritative nameservers through resolvers (1.1.1.1
and 8.8.8.8 by default; a bare IP means port 53), following a CNAME that
delegates the challenge elsewhere, and answers only once every one of
them serves the value. It gives up after propagation_timeout, a minute
by default; 0 answers as soon as the provider took the record.
When a name already had another value, such as the first half of a wildcard order, Slopscale also waits out that value’s TTL, so a resolver that cached the record set before sees the new value.
What a machine may publish
A machine may publish only a TXT record holding an ACME DNS-01 value at
the challenge name of one of its own cert domains,
_acme-challenge.<name>, matched exactly, over its own Noise session,
and only while its key has not expired. Anything else is refused before
it reaches the provider. Every record published lands in the
audit log as node.cert_challenge on the machine.
A name is left out of a machine’s cert domains, so it gets no certificate, when another party could hold it too:
- a machine name with capitals, kept from before names were lowercased, which could differ from another machine’s name by case only; rename the machine to fix it;
- a name the operator gave an extra DNS record at or below, since a machine picks its own name through its hostname;
- a name longer than DNS allows once
_acme-challenge.is added; - with
acmedns, a name without its own registration.
A machine holds at most four pending values at once; a fifth request is
answered 429 until one expires. Other answers tell the client whether
to retry: 502 when the provider refused the record, 504 when the
nameservers did not serve it in time, 503 while the server shuts down.
Removal
Clients never ask for a record to be removed, so Slopscale removes each value ten minutes, plus the propagation timeout, after it was last published, and every value it still holds when it shuts down. Other values at the same name are left alone. Nothing is kept across a restart: a crash, or a failed removal, leaves a few random TXT values behind, which are harmless.
acme-dns
acme-dns answers each registration’s challenge from one record, so a
registration shared between names would let one machine answer another’s
challenge. Machines therefore need a registration per certificate name
under config, keyed by the name, and each _acme-challenge.<name>
CNAMEd to its registration’s fulldomain. config_path reads the JSON
file acme-dns-client writes. A machine without a registration gets no
certificate. A registration holds two values; more are refused until one
expires.
https_certificates:
enabled: true
provider: acmedns
acmedns:
config:
laptop.ts.example.com:
username: <username from /register>
password: <password from /register>
subdomain: <subdomain from /register>
server_url: https://auth.acme-dns.io
One account given as username, password, subdomain and
server_url directly, instead of config, serves only the server’s own
certificate.
Without a public zone
A base domain that only exists inside the tailnet cannot pass a DNS-01
challenge, because Let’s Encrypt looks the record up from the outside.
Machines can still use tailscale cert with certificates issued some
other way, or serve plain HTTP; nothing else changes.