Qadmin: Created page with "= 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 Qu..."

2026-05-06T14:53:09Z

Created page with "= 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 <code>/var/opt/osnexus/quantastor/ssl/</code>. The <code>qs-util wuicustomcerts*</code> 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 Qu..."

New page

= 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 <code>/var/opt/osnexus/quantastor/ssl/</code>. The <code>qs-util wuicustomcerts*</code> 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 <code>qs-util wuicustomcerts</code> swaps the symlink to point at a user-owned copy under <code>/var/opt/osnexus/quantastor/ssl/</code>, which is safe to edit, persists across upgrades, and is not overwritten by QuantaStor.

== Commands ==

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

== Default Configuration (Reference) ==

The shipped default <code>nginx_quantastor_ssl_default.conf</code>:

<pre>
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;
</pre>

Note that <code>ssl_certificate</code> and <code>ssl_certificate_key</code> 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 <code>qs-util wuicustomcerts</code>, so you start from a known-good baseline.

== Typical Workflow: Installing a CA-Signed Certificate ==

'''1.''' Stage your certificate and key under <code>/var/opt/osnexus/quantastor/ssl/</code>. 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 <code>qsrestsrv_custom.pem</code> and <code>qscacert_custom.pem</code> if you prefer to keep the naming consistent.

'''2.''' Enable custom mode:

qs-util wuicustomcerts

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

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

<pre>
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;
</pre>

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 <code>server { }</code> block can be added. Common hardening edits:

<pre>
# Restrict to TLS 1.3 only
ssl_protocols TLSv1.3;
</pre>

After any edit, run <code>qs-util wuicustomcertsrestart</code> 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 <code>nginx_quantastor_ssl_default.conf</code>, and restarts Nginx in one step.

== Troubleshooting ==

; <code>qs-util wuicustomcerts</code> 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 <code>qs-util wuicustomcertsdefault</code> first, then <code>qs-util wuicustomcerts</code> again.

; Nginx fails to restart
: <code>wuicustomcertsrestart</code> will automatically show <code>systemctl status nginx</code> and the last 5 minutes of <code>journalctl -u nginx</code>. 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 <code>www-data</code>)
:* 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 <code>/var/opt/osnexus/quantastor/ssl/</code> which is preserved across upgrades. If the symlink got reset to defaults, simply re-run <code>qs-util wuicustomcerts</code> (it will not overwrite your existing custom file) to re-establish the symlink.

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

== File Locations Summary ==

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

== Related Commands ==

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

Applying Custom Web User Interface Certificates - Revision history