SSL Configuration 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 walks you through enabling SSL on your Diskover deployment. The process involves three main areas: preparing your SSL certificates, configuring NGINX to serve traffic over HTTPS, and updating the Diskover Worker's Python environment to trust your certificate chain.

Prerequisites

Before beginning, ensure you have the following:

A public SSL certificate (typically a .crt file)
An intermediate/bundle certificate (typically a .pem file)
A private key (.key file)
A DNS record (e.g., diskover.yourcompany.com) pointing to your Diskover Web server's IP address

Step 1: Prepare Your SSL Certificates

1.1 Generate a CSR and Key (if you don't already have them)

If you need to request a certificate from a Certificate Authority (CA), you'll first need to generate a Certificate Signing Request (CSR) and private key from your Diskover Web server. Refer to this OpenSSL guide for instructions.

1.2 Build a Complete SSL Certificate Chain

If your CA provided separate public, intermediate, and root certificate files (rather than a pre-bundled chain), you'll need to 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.3 Validate Your Certificate and Key Pair

Before proceeding, confirm that your 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.4 (Optional) Remove the Key Passphrase

NGINX requires a passphrase-free key. If your 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: Place Certificates on the Server

2.1 Copy Certificates Into Place

Create the required directories and copy your certificate and key into place:

mkdir -p /etc/pki/nginx/certs/
mkdir -p /etc/pki/nginx/private/

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

2.2 Add the Certificate to the System Trust Store

So that system-level tools (such as curl) and other services on the web host trust your certificate, add your certificate chain to the operating system's trust anchors and 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 shown here are specific to RHEL/Rocky Linux 9). It is separate from the Python certifi bundle used by the Diskover Worker in Step 4 — Python's requests library does not use the system trust store, so both must be updated.

Step 3: Configure NGINX

3.1 Back Up Existing Configuration Files

Always take backups before making changes:

cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bakPreSSL
cp /etc/nginx/conf.d/diskover-web.conf /etc/nginx/conf.d/diskover-web.conf.bakPreSSL

3.2 Update `/etc/nginx/nginx.conf`

⚠️ Before you replace this file: These instructions overwrite the entire contents of nginx.conf. If your server has existing customizations — additional modules, performance tuning, extra server/location blocks, or non-default paths — note them first and merge them back in afterward rather than losing them. The backup you made in Step 3.1 is your safety net.

Replace the contents of your nginx.conf with the following:

# For more information on configuration, see:
#   * Official English Documentation: http://nginx.org/en/docs/
#   * Official Russian Documentation: http://nginx.org/ru/docs/

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
include /usr/share/nginx/modules/*.conf;

events {
    worker_connections 1024;
}

http {
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    log_format custom_diskover '$remote_addr - $remote_user $cookie_username4log [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent"';

    access_log  /var/log/nginx/access.log  main;

    sendfile            on;
    tcp_nopush          on;
    tcp_nodelay         on;
    keepalive_timeout   65;
    types_hash_max_size 2048;

    include             /etc/nginx/mime.types;
    default_type        application/octet-stream;

    include /etc/nginx/conf.d/*.conf;

#    server {
#        listen       80 default_server;
#        listen       [::]:80 default_server;
#        server_name  _;
#        root         /usr/share/nginx/html;
#
#        include /etc/nginx/default.d/*.conf;
#
#        location / {
#        }
#
#        error_page 404 /404.html;
#            location = /40x.html {
#        }
#
#        error_page 500 502 503 504 /50x.html;
#            location = /50x.html {
#        }
#    }

#    server {
#        listen       443 ssl http2 default_server;
#        listen       [::]:443 ssl http2 default_server;
#        server_name  _;
#        root         /usr/share/nginx/html;
#
#        ssl_certificate "/etc/pki/nginx/server.crt";
#        ssl_certificate_key "/etc/pki/nginx/private/server.key";
#        ssl_session_cache shared:SSL:1m;
#        ssl_session_timeout  10m;
#        ssl_ciphers PROFILE=SYSTEM;
#        ssl_prefer_server_ciphers on;
#
#        include /etc/nginx/default.d/*.conf;
#
#        location / {
#        }
#
#        error_page 404 /404.html;
#            location = /40x.html {
#        }
#
#        error_page 500 502 503 504 /50x.html;
#            location = /50x.html {
#        }
#    }
}

Note: The default HTTP and HTTPS server blocks in nginx.conf should remain commented out. All Diskover server configuration is handled in diskover-web.conf. The custom_diskover log format is included for Diskover-specific access logging and is referenced in diskover-web.conf.

3.3 Update `/etc/nginx/conf.d/diskover-web.conf`

⚠️ Merge, don't replace. The template below shows the SSL-relevant configuration. Your installed diskover-web.conf may contain additional location blocks that the template predates (for example location = /diskover-log-agent.py, shipped with current Diskover versions) — replacing the whole file with the template silently removes them. Compare against your existing file (or the backup from Step 3.1) and carry over every location block you did not author, adding the SSL pieces (the listen 443 ssl settings, certificate paths, and the redirect block) around them.

Update server_name, ssl_certificate, and ssl_certificate_key to match your environment:

⚠️ Confirm your PHP-FPM socket path before saving. The fastcgi_pass line below uses /var/opt/remi/php84/run/php-fpm/www.sock, which is specific to PHP 8.4 from the Remi repo on RHEL/Rocky. Older PHP versions, and PHP on Amazon Linux, commonly use a different socket path (often under /run/php-fpm/). If you paste this file in wholesale without correcting this line, NGINX will be unable to reach PHP-FPM and the site will not load. Confirm your actual path from the listen = value in your PHP-FPM pool config (e.g., /etc/opt/remi/php-fpm.d/www.conf, or /etc/php-fpm.d/www.conf on some systems) and update fastcgi_pass to match before saving.

# HTTPS Server Block
server {
    listen   443 ssl;
    server_name  diskover.yourcompany.com;

    ssl_certificate        /etc/pki/nginx/certs/diskover.crt;
    ssl_certificate_key    /etc/pki/nginx/private/diskover.key;
    ssl_protocols          TLSv1.2 TLSv1.3;
    ssl_ciphers            ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384;
    ssl_prefer_server_ciphers on;

    root   /var/www/diskover-web/public;
    index  index.php index.html index.htm;

    error_log  /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log custom_diskover;

    location / {
        try_files $uri $uri/ /index.php?$args =404;
    }

    location ~ \.php(/|$) {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        set $path_info $fastcgi_path_info;
        fastcgi_param PATH_INFO $path_info;
        try_files $fastcgi_script_name =404;
        fastcgi_pass unix:/var/opt/remi/php84/run/php-fpm/www.sock;
        #fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_read_timeout 900;
        fastcgi_buffers 16 16k;
        fastcgi_buffer_size 32k;
    }

    location /diskover_admin {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://unix:/var/www/diskover-admin/run/diskover-admin.sock;
    }
}

# HTTP to HTTPS Redirect
server {
    listen   8000;
    server_name  diskover.yourcompany.com;
    return 301 https://$server_name$request_uri;
}

Notes:

The access_log directive references the custom_diskover log format defined in nginx.conf.

The PHP-FPM socket path is set to /var/opt/remi/php84/run/php-fpm/www.sock for PHP 8.4 (Remi repo). If you are on a different PHP version, confirm the correct socket path by checking listen = in /etc/opt/remi/php-fpm.d/www.conf (around line 38).

The HTTP redirect block listens on port 8000 and issues a 301 redirect to the HTTPS endpoint. Ensure port 8000 is accessible if clients may reach the server over HTTP.

Step 4: Update the Diskover Worker — Python SSL Trust

The Diskover Worker communicates with the web host via Python's requests library. When SSL is enabled, Python must trust your certificate chain.

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 Back Up the CA Bundle

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

Note: Substitute the python3.11 segment of these paths with the version returned in Step 4.1 if your environment differs.

4.3 Append Your 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 Alternative: Environment Variables Instead of Editing certifi

Appending to cacert.pem works, but is silently undone if the certifi package is ever upgraded (pip install -U certifi replaces the file). A lighter-touch alternative is to point Python at the system trust store (already updated in Step 2.2) via environment variables in the worker's service environment:

REQUESTS_CA_BUNDLE=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
SSL_CERT_FILE=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem

Set both variables: libraries built on requests honor REQUESTS_CA_BUNDLE, while urllib-based tools honor SSL_CERT_FILE. With these set (for example via a systemd drop-in or the service's environment file) every Python client follows the OS trust store with no site-packages edits, and the setting survives package upgrades. If you use this alternative, Steps 4.2–4.3 are not needed.

Step 5: Update Diskover Admin — API Settings

With NGINX now serving traffic over HTTPS, you need to update the Diskover Admin panel to reflect the new API endpoint.

Navigate to Diskover Admin → System → API and update the following fields:

Setting	Value
API Host	Your Diskover web server's fully qualified domain name (e.g., `diskover.yourcompany.com`)
API Port	`443`
Enable HTTPS for API	Checked
Web API Path	`/api.php` (default, leave unchanged)

Note: The default API Port for non-SSL deployments is 8000. When enabling SSL, this must be changed to 443 and the Enable HTTPS for API checkbox must be checked.

Save your changes when done.

5.1 Update the Web Host's PHP Environment

Introduced in 2.6, Diskover Web's PHP code reaches the Diskover Admin service using three environment variables. On deployments where these are not already set, PHP falls back to http://127.0.0.1:8000, and every Diskover Web page will fail with an error 500 once NGINX is reloaded in Step 7.

Add the following lines to the end of the PHP-FPM pool configuration (/etc/opt/remi/php84/php-fpm.d/www.conf for PHP 8.4 from the Remi repo — same file referenced in Step 3.3), replacing the host value with your domain:

env[DISKOVER_ADMIN_HOST]=diskover.yourcompany.com
env[DISKOVER_ADMIN_PORT]=443
env[DISKOVER_ADMIN_HTTPS]=1

Then restart PHP-FPM:

sudo systemctl restart php-fpm

Note: 2.6+ Deployments installed with the Diskover Ansible playbooks will already have these values set. If the Diskover Web UI returns error 500 on every page after Step 7, with Config API error: … http=301 in the NGINX error log, check these values first.

Step 6: Update the Diskover Worker Configuration

Each Diskover Worker node has a configuration file that controls how it communicates with the Diskover Web API. This file must be updated on every worker host to point to the HTTPS endpoint.

The configuration file is located at:

/root/.config/diskoverd/config.yaml

Update the apiurl field to use your HTTPS endpoint. If your API requires authentication, uncomment and set apiuser and apipass accordingly:

# diskover-web api url
apiurl: https://diskover.yourcompany.com/api.php

# diskover-web api username, comment out for no username or password
#apiuser: user
#apipass: somesupersecretpassword

Note: If you configured an API password in Diskover Admin under System → API → Diskover-Web API Password, uncomment apiuser and apipass and enter the matching credentials. If no API password is set, leave these lines commented out.

⚠️ Do not restart the Worker yet. The apiurl you just configured does not exist until NGINX is reloaded in Step 7. If diskoverd is restarted now, it exits immediately because the API is unreachable, systemd restarts it several times within seconds, hits its start limit noted by: "Start request repeated too quickly". This leaves the Worker stopped even after NGINX is reloaded and it must be recovered manually (see Step 7.1).

Step 7: Validate the NGINX Configuration

Before reloading, confirm the firewall allows HTTPS. If the host runs firewalld (default on RHEL-family systems), port 443 may be closed — an installation that has only ever served port 8000 typically never opened it:

sudo firewall-cmd --state
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Note: If firewall-cmd --state reports the firewall is not running, no change is needed.

Test the NGINX configuration for syntax errors 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

If the test passes, reload NGINX:

sudo systemctl reload nginx

Confirm NGINX is now listening on port 443:

netstat -tulpn | grep nginx

Expected output:

tcp   0   0 0.0.0.0:443   0.0.0.0:*   LISTEN   <pid>/nginx: master
tcp6  0   :::443          :::*         LISTEN   <pid>/nginx: master

7.1 Restart the Diskover Workers

With NGINX now serving HTTPS, restart the Diskover Worker service on every worker host:

sudo systemctl restart diskoverd

If a Worker was restarted too early (before NGINX was reloaded) it may be in a failed state and a plain restart is not enough — clear the start-limit first:
sudo systemctl reset-failed diskoverd
sudo systemctl start diskoverd

7.2 Verify the Workers are alive — check heartbeats, not just presence

In the Diskover Admin panel, open the Workers page and confirm each worker's last heartbeat is current (within the last minute or two). A worker row that is present and marked idle but with an old heartbeat is a stale registration — the worker process is not actually running. On the worker host, systemctl status diskoverd should show active (running).

Step 8: Validate DNS and SSL

8.1 Verify DNS Resolution

nslookup diskover.yourcompany.com

The returned IP address should match the IP of your Diskover Web host. If it does not, verify that your DNS CNAME record is configured correctly.

Note: nslookup queries DNS servers directly and does not consult /etc/hosts. If the hostname is resolved by hosts-file entries (common in lab and PoC deployments), use getent hosts diskover.yourcompany.com instead — it resolves the name the same way the applications do.

8.2 Test SSL Connectivity

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

A successful response looks like:

HTTP/1.1 200 OK
Server: nginx/...
Content-Type: text/html; charset=UTF-8

An HTTP/1.1 200 response confirms SSL is working correctly. You should now be able to access the Diskover Web UI in your browser at https://diskover.yourcompany.com/login.php.

8.3 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 over SSL.

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.3.
PHP-FPM socket path mismatch — Compare the fastcgi_pass path in diskover-web.conf with the listen path in your PHP-FPM www.conf.
DNS not resolving — Confirm your CNAME record points to the correct IP.
SSL errors on curl — Ensure the complete certificate chain was used and the CA bundle was updated on the Worker host.
Worker down after enabling SSL / "Start request repeated too quickly" — the Worker was restarted before NGINX began serving HTTPS (see Step 6 warning). Run sudo systemctl reset-failed diskoverd && sudo systemctl start diskoverd on the worker host, then confirm a current heartbeat on the Admin Workers page. Journal signature: Could not connect to api server. Check the values of ['apiurl', 'apiuser', 'apipass'] repeated several times in under a few seconds, followed by diskoverd.service: Start request repeated too quickly.

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.

Diskover - SSL Configuration Guide

SSL Configuration Guide

Overview

Prerequisites

Step 1: Prepare Your SSL Certificates

1.1 Generate a CSR and Key (if you don't already have them)

1.2 Build a Complete SSL Certificate Chain

1.3 Validate Your Certificate and Key Pair

1.4 (Optional) Remove the Key Passphrase

Step 2: Place Certificates on the Server

2.1 Copy Certificates Into Place

2.2 Add the Certificate to the System Trust Store

Step 3: Configure NGINX

3.1 Back Up Existing Configuration Files

3.2 Update `/etc/nginx/nginx.conf`

3.3 Update `/etc/nginx/conf.d/diskover-web.conf`

Step 4: Update the Diskover Worker — Python SSL Trust

4.1 Locate the Python CA Bundle

4.2 Back Up the CA Bundle

4.3 Append Your Certificate Chain

4.4 Alternative: Environment Variables Instead of Editing certifi

Step 5: Update Diskover Admin — API Settings

5.1 Update the Web Host's PHP Environment

Step 6: Update the Diskover Worker Configuration

Step 7: Validate the NGINX Configuration

7.1 Restart the Diskover Workers

7.2 Verify the Workers are alive — check heartbeats, not just presence

Step 8: Validate DNS and SSL

8.1 Verify DNS Resolution

8.2 Test SSL Connectivity

8.3 Validate the Python SSL Connection

Troubleshooting

Comments

SSL Configuration Guide

Overview

Prerequisites

Step 1: Prepare Your SSL Certificates

1.1 Generate a CSR and Key (if you don't already have them)

1.2 Build a Complete SSL Certificate Chain

1.3 Validate Your Certificate and Key Pair

1.4 (Optional) Remove the Key Passphrase

Step 2: Place Certificates on the Server

2.1 Copy Certificates Into Place

2.2 Add the Certificate to the System Trust Store

Step 3: Configure NGINX

3.1 Back Up Existing Configuration Files

3.2 Update /etc/nginx/nginx.conf

3.3 Update /etc/nginx/conf.d/diskover-web.conf

Step 4: Update the Diskover Worker — Python SSL Trust

4.1 Locate the Python CA Bundle

4.2 Back Up the CA Bundle

4.3 Append Your Certificate Chain

4.4 Alternative: Environment Variables Instead of Editing certifi

Step 5: Update Diskover Admin — API Settings

5.1 Update the Web Host's PHP Environment

Step 6: Update the Diskover Worker Configuration

Step 7: Validate the NGINX Configuration

7.1 Restart the Diskover Workers

7.2 Verify the Workers are alive — check heartbeats, not just presence

Step 8: Validate DNS and SSL

8.1 Verify DNS Resolution

8.2 Test SSL Connectivity

8.3 Validate the Python SSL Connection

Troubleshooting

Related articles

3.2 Update `/etc/nginx/nginx.conf`

3.3 Update `/etc/nginx/conf.d/diskover-web.conf`