Applying Custom Web User Interface Certificates

QuantaStor WebUI Custom Certificates and Cipher Settings

QuantaStor's web management UI is served via Nginx, which by default uses the auto-generated self-signed certificates installed at /var/opt/osnexus/quantastor/ssl/. The qs-util wuicustomcerts* family of commands lets administrators override the default Nginx SSL configuration with their own certificate paths, TLS protocols, cipher suites, and other directives, without modifying any QuantaStor-managed config file directly.

Overview

Nginx loads its SSL settings from a single included file:

/opt/osnexus/common/lib/nginx_quantastor_ssl.conf

This path is a symlink. By default, it points at the QuantaStor-shipped default:

/opt/osnexus/common/lib/nginx_quantastor_ssl.conf
  -> /opt/osnexus/common/lib/nginx_quantastor_ssl_default.conf

Running qs-util wuicustomcerts swaps the symlink to point at a user-owned copy under /var/opt/osnexus/quantastor/ssl/, which is safe to edit, persists across upgrades, and is not overwritten by QuantaStor.

Commands

Command	Purpose
qs-util wuicustomcerts	Enable custom mode. Creates /var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf (seeded from the default) and points the active symlink at it. Will not overwrite an existing custom file.
qs-util wuicustomcertsrestart	Restart Nginx so changes to the custom config take effect. Verifies that Nginx came back up active (running); on failure it prints systemctl status and the last 5 minutes of journalctl -u nginx.
qs-util wuicustomcertsdefault	Revert to the QuantaStor defaults. Removes the custom file, points the symlink back at nginx_quantastor_ssl_default.conf, and restarts Nginx.

Default Configuration (Reference)

The shipped default nginx_quantastor_ssl_default.conf:

ssl_certificate     /var/opt/osnexus/quantastor/ssl/qsrestsrv.pem;
ssl_certificate_key /var/opt/osnexus/quantastor/ssl/qsrestsrv.pem;
ssl_client_certificate /var/opt/osnexus/quantastor/ssl/qscacert.pem;

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256";
ssl_prefer_server_ciphers on;
gzip off;

Note that ssl_certificate and ssl_certificate_key both point at the same file. Nginx handles this correctly; it reads the file twice, locating the certificate block and the private key block independently. A single PEM file containing the certificate, private key, and CA certificate is a fully supported configuration.

The custom file is seeded with this exact content the first time you run qs-util wuicustomcerts, so you start from a known-good baseline.

Typical Workflow: Installing a CA-Signed Certificate

1. Stage your certificate and key under /var/opt/osnexus/quantastor/ssl/. The recommended filenames are:

/var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem
/var/opt/osnexus/quantastor/ssl/qscacert_custom.pem

The certificate file should contain the server certificate followed by any intermediate CA certificates (a "full chain" PEM). The private key must be unencrypted (no passphrase) since Nginx is started non-interactively.

If your CA provides a single PEM bundle containing the certificate, private key, and CA certificate, that file can be used for all three directives. You can also use it for both qsrestsrv_custom.pem and qscacert_custom.pem if you prefer to keep the naming consistent.

2. Enable custom mode:

qs-util wuicustomcerts

This creates /var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf and re-points the active symlink at it. On SELinux-enabled systems, the appropriate httpd_config_t context is also applied so Nginx can read the file.

3. Edit the custom config at /var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf and update the certificate paths:

ssl_certificate     /var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem;
ssl_certificate_key /var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem;
ssl_client_certificate /var/opt/osnexus/quantastor/ssl/qscacert_custom.pem;

You can also tighten protocols and ciphers here (see #Tightening TLS Protocols and Ciphers below).

4. Apply the change:

qs-util wuicustomcertsrestart

Confirm the command reports Nginx restarted successfully, then load the WebUI in a browser to verify the new certificate is presented.

Tightening TLS Protocols and Ciphers

Because the included file is a standard Nginx SSL fragment, any directive valid inside an Nginx server { } block can be added. Common hardening edits:

# Restrict to TLS 1.3 only
ssl_protocols TLSv1.3;

After any edit, run qs-util wuicustomcertsrestart to reload.

Reverting to Defaults

If a customized config breaks Nginx or you simply want to go back to QuantaStor-managed self-signed certs:

qs-util wuicustomcertsdefault

This deletes the custom file, restores the symlink to nginx_quantastor_ssl_default.conf, and restarts Nginx in one step.

Troubleshooting

qs-util wuicustomcerts reports "File already exists"

The custom file has already been created from a previous run. This is expected; edit the existing file rather than re-creating it. To start over from the shipped default, run qs-util wuicustomcertsdefault first, then qs-util wuicustomcerts again.

Nginx fails to restart

wuicustomcertsrestart will automatically show systemctl status nginx and the last 5 minutes of journalctl -u nginx. The most common causes are:

• Typos in directive names or missing semicolons in the custom file
• Certificate/key path doesn't exist or has wrong permissions (Nginx runs as www-data)
• Certificate and private key don't match
• Encrypted private key (passphrase-protected); Nginx cannot prompt for it
• On SELinux systems, missing or wrong file context on the cert/key files

Custom changes "disappeared" after upgrade

They shouldn't. The custom file lives under /var/opt/osnexus/quantastor/ssl/ which is preserved across upgrades. If the symlink got reset to defaults, simply re-run qs-util wuicustomcerts (it will not overwrite your existing custom file) to re-establish the symlink.

Verifying which config is active

ls -l /opt/osnexus/common/lib/nginx_quantastor_ssl.conf shows where the symlink currently points. A target of ..._ssl_custom.conf means custom mode is active; ..._ssl_default.conf means defaults are active.

File Locations Summary

Path	Purpose
/opt/osnexus/common/lib/nginx_quantastor_ssl.conf	Active SSL config; symlink, do not edit
/opt/osnexus/common/lib/nginx_quantastor_ssl_default.conf	Shipped defaults; do not edit, replaced on upgrade
/var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf	User-editable custom config; preserved across upgrades
/var/opt/osnexus/quantastor/ssl/qsrestsrv.pem	Default self-signed server cert + key
/var/opt/osnexus/quantastor/ssl/qscacert.pem	Default QuantaStor CA cert
/var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem	Customer-provided server cert + key (recommended filename)
/var/opt/osnexus/quantastor/ssl/qscacert_custom.pem	Customer-provided CA cert (recommended filename; may be the same file as qsrestsrv_custom.pem)

Related Commands

• qs-util cacertuselegacy / qs-util cacertusedefault - manage which CA certificate set the QuantaStor REST stack trusts (separate from the WebUI Nginx config covered here).