Skip to main content
Version: 0.4 · current

Set up names and TLS

How-to guideReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Installer (Linux administrator), Super admin
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

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 (excubius by 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​

NameWhat it is
Primary nameThe 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
AliasesOther 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 certificateThe 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.

warning

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 consoleInstaller answerUse it when
Let's Encrypt over HTTPletsencryptEvery 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 DNSletsencrypt-dnsYou 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-signedselfsignedAnywhere. Browsers warn until people trust the certificate on their computers and phones
Your own certificatecustomYour organisation issues certificates. You paste the chain and the key, and you replace them before they expire
Gateway in frontgatewayA 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 HTTPlaterA first test, or a network you fully trust. Nothing is encrypted

Change names or the mode in the console​

  1. Open Settings and select Server and certificates. You can also reach it from Settings › Instance with Server names and HTTPS.
  2. Under Names, check the Primary name. To add an alias, enter it and select Add; to remove one, select Remove next to it.
  3. Under HTTPS, choose the mode and fill in what it asks for. The sections below describe each one.
  4. Under Names in the certificate, untick any name a certificate cannot cover.
  5. 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​

  1. Enter the E-mail for the Let's Encrypt account.

  2. 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 dnsapi id.

  3. Under API credentials, enter the values the provider reads. The console lists them for each provider:

    Providerdnsapi idVariables
    Cloudflaredns_cfCF_Token, CF_Account_ID
    DreamHostdns_dreamhostDH_API_KEY
    Azure DNSdns_azureAZUREDNS_SUBSCRIPTIONID, AZUREDNS_TENANTID, AZUREDNS_APPID, AZUREDNS_CLIENTSECRET
    Amazon Route 53dns_awsAWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
    GoDaddydns_gdGD_Key, GD_Secret
    DigitalOceandns_dgonDO_API_KEY
    Gandidns_gandi_livednsGANDI_LIVEDNS_TOKEN
    Hetznerdns_hetznercloudHETZNER_TOKEN
    IONOSdns_ionosIONOS_PREFIX, IONOS_SECRET
    Linode (Akamai)dns_linode_v4LINODE_V4_API_KEY
    Namecheapdns_namecheapNAMECHEAP_USERNAME, NAMECHEAP_API_KEY, NAMECHEAP_SOURCEIP
    OVHclouddns_ovhOVH_END_POINT, OVH_AK, OVH_AS, OVH_CK
    Porkbundns_porkbunPORKBUN_API_KEY, PORKBUN_SECRET_API_KEY
  4. 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.

  1. Connect over SSH and become the service account:

    sudo -iu excubius
  2. Show the current settings and certificate:

    /opt/excubius/current/scripts/enable-tls.sh --status
  3. Change what you need. For example, switch to a self-signed certificate:

    /opt/excubius/current/scripts/enable-tls.sh --mode selfsigned

    Or 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=VALUE lines 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
  4. 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.