Running the service via TLS (optional)
Serve slopscale over TLS with your own certificate or one from Let's Encrypt, pick the HTTP-01, TLS-ALPN-01 or DNS-01 challenge, and check that renewal works.
Bring your own certificate
Slopscale can be configured to expose its web service via TLS. To configure the certificate and key file manually, set the tls.cert_path and tls.key_path configuration parameters. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.
tls:
cert_path: ""
key_path: ""
The certificate should contain the full chain, else some clients, like the Tailscale Android client, will reject it.
Let’s Encrypt / ACME
To get a certificate automatically via Let’s Encrypt, set tls.acme.hostname to the desired certificate hostname. This name must resolve to the IP address(es) slopscale is reachable on (i.e., it must correspond to the server_url configuration parameter). The certificate and Let’s Encrypt account credentials will be stored in the directory configured in tls.acme.cache_dir. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.
tls:
acme:
hostname: ""
http_listen: ":http"
cache_dir: /var/lib/slopscale/cache
challenge_type: HTTP-01
# url: https://acme-v02.api.letsencrypt.org/directory
# email: ""
The certificate is ordered when slopscale starts, not on the first connection, and kept renewed.
Older keys
Earlier releases read flat keys. They still work, and a tls key wins over its flat key; slopscale logs a warning naming the new key for each flat key it reads.
| Flat key | tls key |
|---|---|
tls_cert_path |
tls.cert_path |
tls_key_path |
tls.key_path |
tls_letsencrypt_hostname |
tls.acme.hostname |
tls_letsencrypt_challenge_type |
tls.acme.challenge_type |
tls_letsencrypt_listen |
tls.acme.http_listen |
tls_letsencrypt_cache_dir |
tls.acme.cache_dir |
acme_url |
tls.acme.url |
acme_email |
tls.acme.email |
The environment follows the new keys: SLOPSCALE_TLS_ACME_HOSTNAME sets tls.acme.hostname.
A server upgraded from a release that used autocert keeps its certificate: on the first start slopscale copies the certificate autocert left in tls.acme.cache_dir into its own storage in the same directory, as long as it is still valid for tls.acme.hostname, and renews it when it is due.
Challenge types
Slopscale supports three values for tls.acme.challenge_type: HTTP-01 (default), TLS-ALPN-01 and DNS-01.
HTTP-01
For HTTP-01, slopscale must be reachable on port 80 for the Let’s Encrypt automated validation, in addition to whatever port is configured in listen_addr. By default, slopscale listens on port 80 on all local IPs for Let’s Encrypt automated validation. TLS-ALPN-01 on listen_addr stays available as well, so a server only reachable on port 443 still validates.
If you need to change the ip and/or port used by slopscale for the Let’s Encrypt validation process, set tls.acme.http_listen to the appropriate value. This can be handy if you are running slopscale as a non-root user (or can’t run setcap). Keep in mind, however, that Let’s Encrypt will only connect to port 80 for the validation callback, so if you change tls.acme.http_listen you will also need to configure something else (e.g. a firewall rule) to forward the traffic from port 80 to the ip:port combination specified in tls.acme.http_listen.
TLS-ALPN-01
For TLS-ALPN-01, slopscale listens on the ip:port combination defined in listen_addr. Let’s Encrypt will only connect to port 443 for the validation callback, so if listen_addr is not set to port 443, something else (e.g. a firewall rule) will be required to forward the traffic from port 443 to the ip:port combination specified in listen_addr.
DNS-01
For DNS-01, slopscale publishes the challenge as a TXT record through the DNS provider configured under https_certificates (see HTTPS certificates), waits until every authoritative nameserver of the zone serves it, and removes it afterwards. The server needs no inbound port for validation, which suits a server behind a firewall. The provider is used even when https_certificates.enabled is off:
tls:
acme:
hostname: slopscale.example.com
challenge_type: DNS-01
https_certificates:
provider: cloudflare
cloudflare:
api_token_path: /run/credentials/slopscale.service/cloudflare-token
Technical description
Slopscale uses CertMagic, a Golang library providing ACME protocol verification, to facilitate certificate renewals via Let’s Encrypt. Certificates will be renewed automatically, and the following can be expected:
- Certificates provided from Let’s Encrypt have a validity of 3 months from date issued.
- Renewals start when a third of the validity remains, or earlier when the CA asks for it through ACME renewal information.
- Renewal checks run every 10 minutes.
- When
tls.acme.urlis Let’s Encrypt’s production directory or empty, a failed order is retried against Let’s Encrypt’s staging CA first, to spare the production rate limits. - Log lines from the library carry
logger=acme.
Checking certificate expiry
If you want to validate that certificate renewal completed successfully, this can be done either manually, or through external monitoring software. Two examples of doing this manually:
- Open the URL for your slopscale server in your browser of choice, and manually inspecting the expiry date of the certificate you receive.
- Or, check remotely from CLI using
openssl:
$ openssl s_client -servername [hostname] -connect [hostname]:443 | openssl x509 -noout -dates
(...)
notBefore=Feb 8 09:48:26 2024 GMT
notAfter=May 8 09:48:25 2024 GMT