Set up names and TLS
Your Excubius server answers to a primary name and any number of aliases, and serves HTTPS in one of six modes, from a Let's Encrypt certificate to a gateway that ends TLS in front of it. The installer's answers set the first values. After that you change them in the console, and the change applies within a minute without a restart. This guide shows how to choose and change them.
Before you begin
- To change names and TLS in the console, you need the Super admin role.
- To work from the server instead, you need SSH access and
sudo, so you can act as the service account (excubiusby default). - Create the DNS records first. Every name must resolve to the server, or to the gateway in front of it, from where people will use Excubius.
The three kinds of name
| Name | What it is |
|---|---|
| Primary name | The host name in the public address, for example monitoring.ciguapa.example. Links that Excubius sends, in Slack messages and Jira issues, use it. Sign-in always happens on it: a person who opens an alias is sent to the primary name to sign in |
| Aliases | Other names people may open, for example monitoring.areito.example in a domain you control when the client's DNS zone is out of reach. The server answers to all of them |
| Names in the certificate | The names a certificate is requested for. All names by default, and new aliases join automatically. Untick a name a certificate cannot cover, for example one whose DNS you do not control |
A server has at most 100 names in all.
The redirect addresses registered for Microsoft Entra ID and Google sign-in start with the primary name. When you change the primary name, update them first; see Set up sign-in providers.
Choose a mode
| Mode in the console | Installer answer | Use it when |
|---|---|---|
| Let's Encrypt over HTTP | letsencrypt | Every name in the certificate is in public DNS pointing at this server, and port 80 is reachable from the internet, directly or forwarded by a NAT or gateway |
| Let's Encrypt over DNS | letsencrypt-dns | You have API credentials for the DNS zone of the names. The server does not need to be reachable from the internet, so this is the usual choice for a server reached over a VPN |
| Self-signed | selfsigned | Anywhere. Browsers warn until people trust the certificate on their computers and phones |
| Your own certificate | custom | Your organisation issues certificates. You paste the chain and the key, and you replace them before they expire |
| Gateway in front | gateway | A load balancer or reverse proxy, such as Azure Application Gateway or Front Door, ends TLS and forwards plain HTTP. Its X-Forwarded-Proto header is honoured |
| Plain HTTP | later | A first test, or a network you fully trust. Nothing is encrypted |
Change names or the mode in the console
- Open Settings and select Server and certificates. You can also reach it from Settings › Instance with Server names and HTTPS.
- Under Names, check the Primary name. To add an alias, enter it and select Add; to remove one, select Remove next to it.
- Under HTTPS, choose the mode and fill in what it asks for. The sections below describe each one.
- Under Names in the certificate, untick any name a certificate cannot cover.
- Select Apply. The page shows Saved. The certificate service is applying it.
Under Current certificate you see what is being served: the issuer, the names, Valid until, the Last attempt with its result, and the Next check. If an attempt fails, What went wrong explains it.
Every change is checked before it is saved and is written to the audit log.
Let's Encrypt over HTTP
Enter the E-mail for the Let's Encrypt account. Before you apply, make sure every name in the certificate resolves publicly to the server and that port 80 is open from the internet. A name that cannot be public, such as an IP address or a name ending in .local, .internal or .corp, is refused: untick it, or use a self-signed certificate.
Let's Encrypt over DNS
-
Enter the E-mail for the Let's Encrypt account.
-
Choose the DNS provider of the names' zone. For a provider that is not in the list, choose Other (acme.sh dnsapi id) and enter its acme.sh
dnsapiid. -
Under API credentials, enter the values the provider reads. The console lists them for each provider:
Provider dnsapiidVariables Cloudflare dns_cfCF_Token,CF_Account_IDDreamHost dns_dreamhostDH_API_KEYAzure DNS dns_azureAZUREDNS_SUBSCRIPTIONID,AZUREDNS_TENANTID,AZUREDNS_APPID,AZUREDNS_CLIENTSECRETAmazon Route 53 dns_awsAWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEYGoDaddy dns_gdGD_Key,GD_SecretDigitalOcean dns_dgonDO_API_KEYGandi dns_gandi_livednsGANDI_LIVEDNS_TOKENHetzner dns_hetznercloudHETZNER_TOKENIONOS dns_ionosIONOS_PREFIX,IONOS_SECRETLinode (Akamai) dns_linode_v4LINODE_V4_API_KEYNamecheap dns_namecheapNAMECHEAP_USERNAME,NAMECHEAP_API_KEY,NAMECHEAP_SOURCEIPOVHcloud dns_ovhOVH_END_POINT,OVH_AK,OVH_AS,OVH_CKPorkbun dns_porkbunPORKBUN_API_KEY,PORKBUN_SECRET_API_KEY -
Optionally set Let's Encrypt server to Staging to rehearse without touching Let's Encrypt's rate limits. Staging certificates are not trusted by browsers; switch back to Production when it works.
The credential values are write-only: they are stored encrypted and never shown again. To keep a stored value when you edit the settings, leave its field empty.
Self-signed
Nothing to enter. The certificate is valid for 825 days and is renewed the same way as the others. To stop the browser warnings, select Download the certificate and install it as trusted on the computers and phones that use the server.
Your own certificate
Paste the Certificate chain in PEM format, server certificate first, and the Private key in PEM format without a passphrase. The key must be RSA of 2048 bits or more, or ECDSA. The console refuses a certificate that has expired, that does not cover the server's names, or whose key does not match. Replace both before the certificate expires; Excubius does not renew it for you.
Gateway in front
Nothing to enter. Configure the gateway to forward plain HTTP to port 80 of the server and to send the X-Forwarded-Proto header.
Renewal
Renewal is automatic for Let's Encrypt and self-signed certificates. The certificate service checks the active certificate every day and renews it when 30 days or less remain. There is no timer to set up on the server.
- A failed attempt never removes what works. The previous certificate, or plain HTTP, keeps being served; the error appears on the page with the next retry time, after 15 minutes and then doubling up to a day.
- A change of the settings is tried at once.
- Renew now requests a new certificate immediately.
- Use self-signed now switches to a self-signed certificate, the quick way to HTTPS while Let's Encrypt cannot work yet.
Session cookies are marked Secure whenever a request arrives over HTTPS, so changing the mode needs no restart. Leave COOKIE_SECURE empty in the configuration file; it only forces the behaviour one way or the other.
The addresses /healthz and /heartbeat answer over plain HTTP in every mode, so a watcher outside keeps working while you change TLS.
Change TLS from the server
When the console is out of reach, for example because the certificate is broken and the browser refuses the page, change the same settings from the server. The script goes through the same checks and the same audit log as the console.
-
Connect over SSH and become the service account:
sudo -iu excubius -
Show the current settings and certificate:
/opt/excubius/current/scripts/enable-tls.sh --status -
Change what you need. For example, switch to a self-signed certificate:
/opt/excubius/current/scripts/enable-tls.sh --mode selfsignedOr use Let's Encrypt over DNS with Cloudflare, with two names and a certificate for the second one only. The credentials are read as
KEY=VALUElines from standard input:/opt/excubius/current/scripts/enable-tls.sh --mode letsencrypt-dns \--email ops@areito.example --dns-provider dns_cf \--names "monitoring.ciguapa.example monitoring.areito.example" \--cert-names monitoring.areito.example < credentials.txt -
To renew at once, run
enable-tls.sh --renew.
Replace /opt/excubius if you chose another install directory. Run enable-tls.sh --help for every option, including --staging and --production. A certificate of your own can only be uploaded from the console.
Change the answers with the installer
sudo ./install.sh --reconfigure asks every question again. The TLS answers you give then are applied to the running platform, as if you had changed them in the console.