SSL Certificate Rotation Guide

Infrastructure: nginx, task-workers, & python env
Platform: RHEL/Rocky Linux 9

Overview

Environment: This guide assumes a RHEL / Rocky Linux environment. File paths (e.g., /etc/pki/nginx/, PHP-FPM socket paths) and package management commands are specific to RHEL-based systems. If you are running Ubuntu/Debian, paths and commands will differ — refer to your distribution's documentation for the equivalent locations.

This guide covers rotating (renewing or replacing) an SSL certificate on a Diskover deployment that already has SSL configured. It assumes NGINX, DNS, Diskover Admin, and the Diskover Worker(s) were previously set up for HTTPS — typically by following the Diskover - SSL Configuration Guide. If you are enabling SSL for the first time, use that full guide instead.

Because the deployment is already serving HTTPS, rotation only touches the certificate material itself. As long as your domain name and certificate file paths stay the same, you will not need to modify nginx.conf, diskover-web.conf, the Diskover Admin API settings, or the Worker config.yaml. (If your domain or CA is changing, see Notes on Changing Domain or CA at the end of this guide.)

A typical rotation has three parts: prepare the new certificate, swap it into place (refreshing both trust stores), and validate.

Prerequisites

Before beginning, ensure you have the following:

• The new public SSL certificate (typically a .crt file)

• The new intermediate/bundle certificate (typically a .pem file), if your CA provides one separately

• The new private key (.key file)

• Confirmation that the new certificate is for the same domain currently in use (e.g., diskover.yourcompany.com)

• Root/sudo access to the Diskover Web host and to each Diskover Worker host

Tip: Plan to rotate before the current certificate expires, and keep the existing certificate and key until the new one is validated so you can roll back if needed.

Step 1: Prepare the New Certificate

1.1 Build a Complete SSL Certificate Chain

If your CA provided separate public, intermediate, and root certificate files (rather than a pre-bundled chain), combine them into a single chain certificate:

cat public-cert.crt > diskover-chain.crt
cat intermediate-cert.pem >> diskover-chain.crt
cat root.crt >> diskover-chain.crt

Review the resulting file to confirm all certificates are included. A complete chain typically contains three to four certificates.

Note: If your CA provided a pre-bundled chain certificate, you can skip this step and use that file directly.

1.2 Validate the New Certificate and Key Pair

Confirm the new certificate and private key are properly paired using OpenSSL. The MD5 checksums must match. If they do not, stop here and verify you have the correct files.

openssl x509 -noout -modulus -in diskover-chain.crt | openssl md5
openssl rsa -noout -modulus -in diskover.key | openssl md5

Both commands should return the same hash. Example:

(stdin)= db2d29014664307355d096711dc215bc
(stdin)= db2d29014664307355d096711dc215bc

1.3 (Optional) Confirm the New Expiry Date

Verify the new certificate's validity window before deploying it, so you know the rotation actually extends your coverage:

openssl x509 -noout -dates -in diskover-chain.crt

1.4 (Optional) Remove the Key Passphrase

NGINX requires a passphrase-free key. If your new key has a passphrase, remove it by running the following (press Enter when prompted to skip setting a new passphrase):

openssl rsa -in diskover.key -out nopass.key

This creates a new key file nopass.key that can be freely renamed.

Step 2: Back Up the Current Certificate and Key

Before overwriting anything, back up the certificate and key currently in use. This is your rollback path if the new certificate fails validation:

cp /etc/pki/nginx/certs/diskover.crt /etc/pki/nginx/certs/diskover.crt.bak-$(date +%Y%m%d)
cp /etc/pki/nginx/private/diskover.key /etc/pki/nginx/private/diskover.key.bak-$(date +%Y%m%d)

Step 3: Install the New Certificate and Key

3.1 Copy the New Certificate Into Place

Overwrite the existing certificate and key at their current paths. Because these are the same paths NGINX already references, no configuration changes are required:

cp /tmp/diskover-chain.crt /etc/pki/nginx/certs/diskover.crt
cp /tmp/nopass.key /etc/pki/nginx/private/diskover.key

3.2 Refresh the System Trust Store

Replace the old certificate in the operating system's trust anchors with the new chain, then refresh the trust store:

cp /tmp/diskover-chain.crt /etc/pki/ca-trust/source/anchors/diskover-chain.crt
update-ca-trust

Note: This updates the operating system's trust store on the web host (the /etc/pki/ca-trust/source/anchors/ path and update-ca-trust command are specific to RHEL/Rocky Linux 9). It is separate from the Python certifi bundle used by the Diskover Worker, which is refreshed in Step 4 — both must be updated on rotation.

Step 4: Refresh the Diskover Worker — Python SSL Trust

The Diskover Worker trusts your certificate chain through Python's requests library, which uses its own certifi CA bundle. During the original setup, your chain was appended to that bundle.

⚠️ On rotation, do not simply append again. Appending the new chain on top of the old one leaves the expired certificate in the bundle and grows the file with every rotation. Instead, restore the pristine bundle from the backup made during setup, then append the new chain.

Perform these steps on every Diskover Worker host.

4.1 Locate the Python CA Bundle

python3 -c "import requests; print(requests.certs.where())"

Example output:

/opt/python-venv-diskover/lib64/python3.11/site-packages/certifi/cacert.pem

Note: The path above is only an example, shown for Python 3.11. Your environment may run a different version (e.g., python3.9, python3.12), which changes the lib64/python3.X/ portion of the path. Use the exact path returned by the command above wherever python3.11 appears in the rest of this step, and adjust accordingly.

4.2 Restore the Pristine CA Bundle

If you have the backup created during the original setup (cacert.pem.bak), restore it so you start from a clean bundle that does not contain the old certificate:

cp /opt/python-venv-diskover/lib64/python3.11/site-packages/certifi/cacert.pem.bak \
   /opt/python-venv-diskover/lib64/python3.11/site-packages/certifi/cacert.pem

⚠️ No backup available? If cacert.pem.bak does not exist, do not guess at editing the bundle by hand. Regenerate a clean bundle by reinstalling certifi in the Diskover virtual environment (for example, pip install --force-reinstall certifi), then take a fresh cacert.pem.bak backup so future rotations start clean. Avoid repeatedly appending to a bundle that already contains the previous certificate.

4.3 Append the New Certificate Chain

cat diskover-chain.crt >> /opt/python-venv-diskover/lib64/python3.11/site-packages/certifi/cacert.pem

Update the path above to match the Python version returned in Step 4.1.

4.4 Validate the Python SSL Connection

python3 -c "import requests; print(requests.get('https://diskover.yourcompany.com').status_code)"

A response of 200 confirms that Python can successfully connect using the new certificate.

Step 5: Reload NGINX and Validate

5.1 Test the NGINX Configuration

Even though the configuration files are unchanged, confirm NGINX can load the new certificate before reloading:

nginx -t

Expected output:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

5.2 Reload NGINX

Reload (rather than restart) to apply the new certificate gracefully, without dropping active connections:

sudo systemctl reload nginx

5.3 Verify the New Certificate Is Being Served

Confirm the live certificate is the new one by checking the expiry date returned by the server:

echo | openssl s_client -connect diskover.yourcompany.com:443 -servername diskover.yourcompany.com 2>/dev/null | openssl x509 -noout -dates

You can also confirm general connectivity with a quick request:

curl -I https://diskover.yourcompany.com/login.php

A successful response looks like:

HTTP/2 200
server: nginx/...
content-type: text/html; charset=UTF-8

An HTTP/2 200 response, with the expiry date matching your new certificate, confirms the rotation succeeded. Load the Diskover Web UI in your browser to confirm the padlock shows the updated certificate.

Rolling Back

If validation fails and you need to restore the previous certificate, copy your backups (from Step 2) back into place and reload NGINX:

cp /etc/pki/nginx/certs/diskover.crt.bak-YYYYMMDD /etc/pki/nginx/certs/diskover.crt
cp /etc/pki/nginx/private/diskover.key.bak-YYYYMMDD /etc/pki/nginx/private/diskover.key
sudo systemctl reload nginx

Replace YYYYMMDD with the date suffix from your backup files. If you had already updated the Worker certifi bundle, also revert it (restore from cacert.pem.bak and re-append the previous chain).

Notes on Changing Domain or CA

This guide assumes the domain name stays the same and only the certificate is being renewed. If your rotation also changes the domain (e.g., diskover.yourcompany.com → diskover.newcompany.com) or moves to a CA whose intermediate/root chain differs, you will additionally need to:

• Update server_name, and confirm the ssl_certificate / ssl_certificate_key paths, in diskover-web.conf

• Update the API Host in Diskover Admin (System → API)

• Update apiurl in each Worker's config.yaml

• Update DNS so the new name resolves to the Diskover Web host

For those changes, follow the relevant steps in the full Diskover - SSL Configuration Guide.

Troubleshooting

If you encounter issues, check the NGINX error log for details:

tail -f /var/log/nginx/error.log

Common issues to check:

• Certificate/key mismatch — Re-run the MD5 validation from Step 1.2; the new certificate and new key must match.

• Browser or curl still shows the old certificate — Confirm nginx -t passed and that you ran systemctl reload nginx; the reload is what loads the new file.

• Python SSL errors after rotation — The certifi bundle may still contain only the old chain. Restore from cacert.pem.bak and re-append the new chain (Step 4).

• Expired-certificate warnings — Verify the new certificate's dates with openssl x509 -noout -dates and confirm you copied the correct file into place.

If you are still unable to resolve the issue after following this guide, please contact Diskover Support and include the steps you performed along with any relevant error messages from /var/log/nginx/error.log.