Skip to main content
Version: Next

TLS and certificates

Native TLS is optional. Enable it only when both the certificate chain and private key are present and readable by the BeaRust process.

Configure mounted certificate files​

Mount certificate material read-only into the container, then point [server.tls] at the mounted paths.

[server.tls]
cert_path = "/etc/bearust/tls/fullchain.pem"
key_path = "/etc/bearust/tls/privkey.pem"

For a non-root container, the process user must be able to read both files and traverse their parent directories. Keep the private key non-world-readable; use group ownership or a narrowly scoped read permission instead of running the container as root. Never commit PEM files or private keys to the repository.

Verify: start or reload BeaRust with the mounted paths. A TLS handshake to the listener should succeed and present the expected certificate; a missing, unreadable, malformed, mismatched, or expired certificate is rejected before BeaRust begins serving it.

Upload and activate managed certificates​

The authenticated control plane can store uploaded certificate material in the configured persistent certificate store (server.certificate_store; the Compose example uses /data/certificates). Uploading is not the same as activating: validate the material, select the intended certificate, then apply the configuration change so the running listener reloads it.

Keep persistent certificate storage on a durable volume. Recreating a container without its certificate volume removes locally stored managed material. Keep a documented backup and restore procedure that protects the private key at rest.

Verify: after activation, inspect the certificate metadata in the management UI/API and make a new TLS connection. The served chain and expiry should match the selected record. Existing connections may finish normally; test a new connection to confirm the reload.

Recover safely​

If validation or activation fails, leave the last known-good certificate in place. Correct the certificate/key pair or file permissions, validate again, and only then activate it. Do not replace live PEM files in place: stage the replacement and use the documented reload workflow so readers never see a partial write.

Verify: deliberately validate an invalid certificate in a non-production environment. The operation should fail before it becomes active, while a new TLS connection continues to receive the prior valid certificate.