Files
2026-10-21 00:12:33 -04:00

28 lines
2.7 KiB
Markdown

# TLS
Reference for native TLS. Settings overview in [configuration.md](configuration.md#servertls-https); design in [ARCHITECTURE.md](../ARCHITECTURE.md#tls).
TLS is optional and off by default. With `server.tls.enabled = false` (the default) the server speaks plain HTTP exactly as before, the certificate paths are ignored and never read, and no TLS code runs. A non-loopback `bind` without TLS logs a startup warning (it is not refused).
Enable it in the config file or the environment (`SKYG_SERVER__TLS__ENABLED=true`, `SKYG_SERVER__TLS__CERT_FILE`, `SKYG_SERVER__TLS__KEY_FILE`):
```toml
[server.tls]
enabled = true
cert_file = "/etc/skyg/tls/cert.pem" # PEM chain, leaf first
key_file = "/etc/skyg/tls/key.pem" # PEM, PKCS#8, PKCS#1 or SEC1
```
Both files are required and checked at startup; a missing, unparsable or mismatched pair stops the server with an error naming the file (key contents are never logged). REST and `/mcp` are then served over HTTPS only (plain HTTP on that port fails), and the default MCP `Origin` allowlist uses `https://` instead of `http://`. Add your public names to `server.allowed_hosts` and `server.allowed_origins` as before. TLS is rustls with the ring provider; openssl is not used.
Self-signed example:
```sh
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -days 365 \
-keyout key.pem -out cert.pem -subj '/CN=monitor.lan' \
-addext 'subjectAltName=DNS:monitor.lan,DNS:localhost,IP:127.0.0.1'
curl --cacert cert.pem -H "Authorization: Bearer $TOKEN" https://localhost:1984/api/v1/systemd/units
```
Rotation: replace the files and send `SIGHUP` (`kill -HUP $(pidof slinuxm)`, or `systemctl kill -s HUP <unit>`). New connections get the new certificate; established ones are not dropped. The certificate and key are read as two separate files, so rotation tooling must send SIGHUP only after BOTH are in place; if the pair is unreadable or mismatched (for example the cert was replaced but the key not yet), the old certificate stays, an error is logged, and you send SIGHUP again once the files are consistent. Any intermediate certificates must be in the `cert_file` chain. Both the TLS and the plain listener are HTTP/1.1 only, share one accept loop, cap concurrent connections at 1024 and close connections that send no request header within 30 seconds. SIGHUP is harmless when TLS is disabled (it is logged and ignored). For ACME, point `cert_file` and `key_file` at the client's output (for example certbot's `live/<name>/fullchain.pem` and `privkey.pem`, or the NixOS `security.acme` directory) and send SIGHUP from the renewal hook. For sops-nix or systemd `LoadCredential`, point at the decrypted or credential path (`/run/credentials/<unit>/...`) so the service user needs no access to the original key file.