Installing a Custom SSL Certificate on a Self-Hosted Nanitor Server

By default, self-hosted Nanitor servers use an SSL certificate issued by the Nanitor Certificate Authority. If your organisation requires a certificate from your own CA, a public CA, or Let's Encrypt, you can replace the default certificate with your own.

How It Works

Nanitor uses nginx as a reverse proxy. The certificate and key are stored at:

/etc/ssl/local/nanitor.crt    ← certificate (full chain)
/etc/ssl/local/nanitor.key    ← private key

Replacing these files and reloading nginx is all that is required.

Prerequisites

• Root or sudo access on the Nanitor server
• A valid SSL certificate and private key for the server's FQDN
• The certificate file should include the full chain (server cert + any intermediate certs), concatenated in order

Step 1 — Back Up the Existing Certificate

sudo cp /etc/ssl/local/nanitor.crt /etc/ssl/local/nanitor.crt.bak
sudo cp /etc/ssl/local/nanitor.key /etc/ssl/local/nanitor.key.bak

Step 2 — Install Your Certificate and Key

Copy your certificate and private key to the server and place them at the required paths:

sudo cp /path/to/your/fullchain.pem /etc/ssl/local/nanitor.crt
sudo cp /path/to/your/private.key   /etc/ssl/local/nanitor.key

Set correct permissions:

sudo chmod 644 /etc/ssl/local/nanitor.crt
sudo chmod 600 /etc/ssl/local/nanitor.key
sudo chown root:root /etc/ssl/local/nanitor.crt /etc/ssl/local/nanitor.key

Step 3 — Test the nginx Configuration

Before reloading, verify nginx accepts the new certificate:

sudo nginx -t

You should see:

nginx: configuration file /etc/nginx/nginx.conf test is successful

If you see an error, check that: - The certificate file is a valid PEM-format cert (starts with -----BEGIN CERTIFICATE-----) - The key matches the certificate - The full chain is included if required by your CA

Step 4 — Reload nginx

sudo systemctl reload nginx

This applies the new certificate without downtime.

Step 5 — Verify

Open your Nanitor URL in a browser and confirm the certificate shown is your custom one. You can also verify from the command line:

echo | openssl s_client -connect localhost:443 2>/dev/null | openssl x509 -noout -issuer -subject -dates

Using Let's Encrypt (Certbot)

If you want to use a free Let's Encrypt certificate with automatic renewal:

Install Certbot

sudo apt install -y certbot python3-certbot-nginx

sudo dnf install -y certbot python3-certbot-nginx

Obtain and Install the Certificate

sudo certbot --nginx -d your-nanitor-hostname.example.com

Certbot will automatically update the nginx configuration and install the certificate.

Configure Auto-Renewal to Use Nanitor Paths

Certbot stores certificates in /etc/letsencrypt/live/<domain>/. You can either:

Option A: Point nginx directly at the Let's Encrypt paths by editing /etc/nginx/conf.d/nanitor.conf:

ssl_certificate     /etc/letsencrypt/live/your-domain/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain/privkey.pem;

Option B: Add a renewal hook to copy to /etc/ssl/local/ after each renewal:

sudo tee /etc/letsencrypt/renewal-hooks/deploy/nanitor.sh << 'EOF'
#!/bin/bash
cp /etc/letsencrypt/live/your-domain/fullchain.pem /etc/ssl/local/nanitor.crt
cp /etc/letsencrypt/live/your-domain/privkey.pem   /etc/ssl/local/nanitor.key
chmod 644 /etc/ssl/local/nanitor.crt
chmod 600 /etc/ssl/local/nanitor.key
systemctl reload nginx
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/nanitor.sh

Test auto-renewal:

sudo certbot renew --dry-run

Reverting to the Nanitor-Issued Certificate

If you need to revert to the default Nanitor certificate:

sudo cp /etc/ssl/local/nanitor.crt.bak /etc/ssl/local/nanitor.crt
sudo cp /etc/ssl/local/nanitor.key.bak /etc/ssl/local/nanitor.key
sudo systemctl reload nginx

Or force a fresh fetch from the Nanitor Hub:

sudo /opt/nanitor-server/bin/nanitor-server-ctl check_server_certificate
sudo systemctl reload nginx

Troubleshooting

Agents stop connecting after certificate change

Nanitor agents trust the Nanitor CA by default. If you replace the server certificate with one from a different CA, agents will fail SSL verification. To resolve:

• Use a certificate from a CA that is already trusted by your endpoints (e.g. your internal domain CA or a public CA like Let's Encrypt)
• Or deploy the new CA certificate to all agent machines' system trust store

For more information on SSL errors in the agent, see How do I troubleshoot SSL errors in the Nanitor Agent?

nginx fails to start after certificate change

Check the nginx error log:

sudo journalctl -u nginx -n 50

Common causes: key does not match certificate, wrong file format, missing intermediate certificate in the chain.