SSL Certificate
UTMStack v12 starts with a self-signed certificate. This page explains how to replace it with a certificate your browsers and agents trust: one from your own certificate authority or a commercial one, or a free Let's Encrypt certificate. It also covers certificates for several names (for example tenant domains) and renewal. SSL, more precisely TLS, is the encryption that protects HTTPS connections.
How UTMStack uses certificates
At installation the installer creates its own certificate authority and a server certificate in
/utmstack/cert:ca.crt,ca.key,utm.crtandutm.key. They are RSA 4096-bit and valid for 10 years. Browsers do not trust them, so they show a warning.nginx on the host serves
/utmstack/cert/utm.crtand/utmstack/cert/utm.keyon port 443, for every name the server is reached on. This is the certificate browsers, API clients, agents and collectors see.The agent manager and log intake services also load these two files when they start, for connections inside the server.
The installer rewrites the nginx settings at every update, and they always point to these two files. Replace the files, not the paths. Changes you make to the nginx settings, including changes made by
certbot --nginx, are lost at the next update.There is no page in the web interface for certificates. You replace the files on the server.
Agents install by default with the option Skip TLS certificate validation (self-signed server), so they work with the self-signed certificate. After you install a trusted certificate, you can install new agents without that option.
Certificate requirements
You need two files in PEM format (text files that start with -----BEGIN):
| File | Contents | Name in UTMStack |
|---|---|---|
| Certificate | Your server certificate first, followed by the intermediate certificates (the full chain) | utm.crt |
| Private key | The private key of the certificate, without a passphrase | utm.key |
The certificate must cover every name that users and agents use to reach the server.
Never share your private key. Keep it secure and backed up.
Certificates for several names
nginx serves one certificate for every name. If the server is reached on more than one name, one certificate must cover them all. This is always the case on a multi-tenant licence, where each tenant has its own domain (see Tenants).
| Type | Covers | Good for |
|---|---|---|
| Certificate with several names (SAN, Subject Alternative Names) | Exactly the names listed in it, for example siem.example.com, customer-a.example.net and customer-b.example.org | Tenant domains under different parent domains. Add or remove a tenant by issuing a new certificate with the new list. |
| Wildcard certificate | Every name one level below a domain, for example *.siem.example.com covers customer-a.siem.example.com and customer-b.siem.example.com | Tenant domains under one parent domain. New tenants need no new certificate. |
A wildcard covers only one level: *.siem.example.com does not cover siem.example.com itself, nor a.b.siem.example.com. Add the parent name to the certificate as well if you use it.
Example naming plan for a multi-tenant server: the operator signs in at siem.example.com, and tenants use customer-a.siem.example.com, customer-b.siem.example.com and so on. Create one wildcard DNS record *.siem.example.com pointing to the server, and one certificate for siem.example.com and *.siem.example.com.
Method 1: Install a certificate you already have
Use this for a certificate from your own certificate authority or a commercial one.
Request the certificate
If your certificate authority needs a certificate signing request (CSR), create the key and the request on the server. Replace the names with yours:
sudo openssl req -new -newkey rsa:2048 -nodes
-keyout /root/siem.example.com.key -out /root/siem.example.com.csr
-subj "/CN=siem.example.com"
-addext "subjectAltName=DNS:siem.example.com,DNS:*.siem.example.com"Send the .csr file to your certificate authority. Keep the .key file on the server.
Prepare the files
Separate certificate and intermediate files: join them into one file, server certificate first:
cat siem.example.com.crt intermediate.crt > fullchain.pemA
.pfxor.p12file (common when the certificate comes from Windows): extract the chain and the key. Add-legacyto both commands if OpenSSL refuses an older file.openssl pkcs12 -in certificate.pfx -nokeys -out fullchain.pem openssl pkcs12 -in certificate.pfx -nocerts -nodes -out private.key
Install the files
- 1
Back up the current files
sudo cp /utmstack/cert/utm.crt /utmstack/cert/utm.crt.bak sudo cp /utmstack/cert/utm.key /utmstack/cert/utm.key.bak - 2
Check that the certificate and the key belong together
The two lines must be identical:
openssl x509 -noout -pubkey -in fullchain.pem | openssl sha256 openssl pkey -pubout -in private.key | openssl sha256 - 3
Copy your certificate and key
Replace
fullchain.pemandprivate.keywith the names of your files:sudo cp fullchain.pem /utmstack/cert/utm.crt sudo cp private.key /utmstack/cert/utm.key sudo chmod 644 /utmstack/cert/utm.crt sudo chmod 600 /utmstack/cert/utm.keyUse
cp, notmv. On Red Hat Enterprise Linux, files copied into/utmstack/certkeep the security label the installer set on that folder. - 4
Test the nginx settings and reload nginx
openssl x509 -in /utmstack/cert/utm.crt -noout -subject -ext subjectAltName -dates sudo nginx -t sudo systemctl reload nginxIf
nginx -treports an error, restore the.bakfiles and reload nginx again. - 5
Restart the two services that also use the files
This is not needed for browsers, but it confirms now, rather than at the next update, that the services accept the new files:
sudo docker service update --force utmstack_agentmanager sudo docker service update --force utmstack_log-input sudo docker service ls --filter name=utmstack_Both services must show
1/1again after a minute. If one does not, read its log (sudo docker service logs --tail 50 utmstack_log-input) and see Troubleshooting below. - 6
Check in the browser
Open
https://your-domainand confirm that the browser shows no warning. Then set Base URL in Configure > Settings > Email Configuration to the same address, so that links in emails use it.
Method 2: Get a free certificate from Let's Encrypt
Let's Encrypt issues free certificates that are valid for 90 days. The examples use certbot, the Let's Encrypt client, and a deploy hook that copies every new certificate into UTMStack.
Choose how to prove that you own the names
| Challenge | Needs | Good for |
|---|---|---|
| HTTP challenge, standalone | Every name points to the server in public DNS, and port 80 on the server is reachable from the internet. nginx is stopped for a moment at each issue and renewal. | One or a few names on a server reachable from the internet. |
| DNS challenge | API access to your DNS provider through a certbot plugin. Port 80 and public access are not needed. | Wildcard certificates, and servers not reachable from the internet. |
The nginx settings that UTMStack writes send every request on port 80 to HTTPS, so certbot's webroot method does not work, and the --nginx method's changes are lost at the next update. Use one of the two methods above.
Install certbot
On Ubuntu and Debian:
sudo apt update
sudo apt install certbotOn Red Hat Enterprise Linux, install the certbot package from the EPEL repository.
Add the deploy hook first
This script copies the certificate into UTMStack and reloads nginx. certbot runs it after every renewal. The commands below also name it with --deploy-hook, so that it runs after the first issue too:
sudo mkdir -p /etc/letsencrypt/renewal-hooks/deploy
sudo tee /etc/letsencrypt/renewal-hooks/deploy/utmstack.sh > /dev/null <<'EOF'
#!/bin/bash
# Copy the new certificate into UTMStack and reload nginx
cp "$RENEWED_LINEAGE/fullchain.pem" /utmstack/cert/utm.crt
cp "$RENEWED_LINEAGE/privkey.pem" /utmstack/cert/utm.key
chmod 644 /utmstack/cert/utm.crt
chmod 600 /utmstack/cert/utm.key
systemctl reload-or-restart nginx
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/utmstack.shBack up /utmstack/cert/utm.crt and utm.key before the first issue, as in Method 1.
Option A: HTTP challenge (standalone)
nginx on the server owns port 80. certbot's standalone mode needs port 80 for a moment, so the hooks stop nginx while the certificate is issued. The web interface and agent connections are unavailable during that time, usually less than a minute.
sudo certbot certonly --standalone --cert-name siem.example.com
-d siem.example.com
--pre-hook "systemctl stop nginx"
--post-hook "systemctl start nginx"
--deploy-hook /etc/letsencrypt/renewal-hooks/deploy/utmstack.shFor several names, add one -d for each, for example -d siem.example.com -d customer-a.example.net. certbot asks for an email address and for your agreement to the Let's Encrypt terms of service, and remembers the hooks for renewals.
Option B: DNS challenge
certbot has plugins for many DNS providers. Two examples:
sudo apt install python3-certbot-dns-cloudflare
# Store an API token that can edit the zone's DNS records
sudo mkdir -p /root/.secrets
echo "dns_cloudflare_api_token = YOUR_API_TOKEN" | sudo tee /root/.secrets/cloudflare.ini > /dev/null
sudo chmod 600 /root/.secrets/cloudflare.ini
sudo certbot certonly --dns-cloudflare
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini
--cert-name siem.example.com
-d "siem.example.com" -d "*.siem.example.com"
--deploy-hook /etc/letsencrypt/renewal-hooks/deploy/utmstack.shWith the DNS challenge, nginx does not need to stop.
Check the result
The deploy hook has already copied the certificate into /utmstack/cert. Check it:
openssl x509 -in /utmstack/cert/utm.crt -noout -subject -ext subjectAltName -dates
sudo nginx -tThen restart the agent manager and log intake once, as in step 5 of Method 1.
Renew automatically
The certbot package installs a timer that renews certificates before they expire. Each renewal runs the deploy hook. Check the timer and test a renewal without changing anything:
systemctl list-timers | grep certbot
sudo certbot renew --dry-runDepending on how certbot was installed, you may have to enable the timer first. With the standalone method, the test also stops nginx for a moment.
Add or remove a name later
Issue the certificate again under the same name (--cert-name) with the complete new list of names. certbot replaces the certificate, the deploy hook copies it, and renewals continue:
sudo certbot certonly --standalone --cert-name siem.example.com
-d siem.example.com -d customer-a.example.net -d customer-c.example.com
--pre-hook "systemctl stop nginx" --post-hook "systemctl start nginx"
--deploy-hook /etc/letsencrypt/renewal-hooks/deploy/utmstack.shWith a wildcard certificate, new tenant names under the same parent domain need no change.
Monitor the certificate
# Expiry date of the installed certificate
openssl x509 -enddate -noout -in /utmstack/cert/utm.crt
# Expiry date and names as clients see them
echo | openssl s_client -servername siem.example.com -connect siem.example.com:443 2>/dev/null
| openssl x509 -noout -dates -ext subjectAltNameKeep a copy of your certificate and key outside /utmstack/cert so that you can put them back if the files are ever replaced. Do not delete files in /utmstack/locks: removing the certificate step's lock makes the installer create a new self-signed certificate over yours.
Troubleshooting
The browser does not trust the certificate
Make sure
utm.crtholds the full chain (usefullchain.pemfrom Let's Encrypt, notcert.pem).Make sure the certificate covers the name in the browser's address bar. For tenant domains, see Certificates for several names.
Check that nginx was reloaded after you copied the files.
certbot reports that port 80 is in use
nginx is still running. Use the --pre-hook "systemctl stop nginx" and --post-hook "systemctl start nginx" options shown above, or use the DNS challenge.
The HTTP challenge fails
Every name must point to the server's public address in public DNS: check with
dig +short <name>.Port 80 must be reachable from the internet while certbot runs, including in your cloud firewall or security group.
If the server is not reachable from the internet, use the DNS challenge.
nginx does not start after the change
sudo nginx -t
journalctl -u nginx --no-pager | tail -n 50
# Check that the certificate and the key belong together:
# the two lines must be identical
openssl x509 -noout -pubkey -in /utmstack/cert/utm.crt | openssl sha256
openssl pkey -pubout -in /utmstack/cert/utm.key | openssl sha256If the key has a passphrase, remove it or use the original key. To go back, restore the .bak files and run sudo systemctl reload nginx.
Log intake or the agent manager does not start after the change
Log intake reports "cannot read the certificate files" when it cannot load utm.crt or utm.key. Check the files as above, restore the .bak files if needed, and restart the service with sudo docker service update --force utmstack_log-input (or utmstack_agentmanager).
Agents stop connecting after the change
Agents installed with Skip TLS certificate validation are not affected. Agents installed without it check the certificate: it must be trusted by their system and must cover the name or address they were installed with. An agent installed with an IP address does not accept a certificate that covers only a DNS name.
The certificate shows as expired
Run
sudo certbot renewand check that the deploy hook copied the new files.Check that the server's date and time are correct.