Applying Custom Web User Interface Certificates: Difference between revisions

From OSNEXUS Online Documentation Site
Jump to navigation Jump to search
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..."
 
m osn-seo-utilities: applying-custom-web-user-interface-certificates-re @ 20afb26880b1 (approved in the portal)
 
Line 1: Line 1:
= QuantaStor WebUI Custom Certificates and Cipher Settings =
This page explains how to replace the self-signed certificate on the QuantaStor web interface and REST API with a certificate signed by your own or a public certificate authority (CA). It covers what the certificate must contain, how to assemble the PEM files, how to install them on each node, how to verify the result, and how to revert.


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.
Each QuantaStor node serves its web interface through nginx, and nginx presents one certificate on ports 443, 8080 and 8153. All three ports serve the same web interface and REST endpoints, so one certificate change covers all of them. Node-to-node grid communication uses a separate service on port 5151 with its own certificates and is not affected by anything on this page.


== Overview ==
* [[#Which file holds what|Which file holds what]] -- the three certificate directives and the files on disk
* [[#Certificate requirements|Certificate requirements]] -- SAN, key type and CA template checks before you start
* [[#Preparing the PEM files|Preparing the PEM files]] -- converting, assembling and verifying the files
* [[#Installing the certificate on each node|Installing the certificate on each node]] -- the six-step procedure
* [[#Renewing a certificate|Renewing a certificate]] and [[#Reverting to the default certificate|Reverting to the default certificate]]
* [[#Troubleshooting|Troubleshooting]]


Nginx loads its SSL settings from a single included file:
== Which file holds what ==


/opt/osnexus/common/lib/nginx_quantastor_ssl.conf
nginx reads its TLS settings from {{Code|1=/opt/osnexus/common/lib/nginx_quantastor_ssl.conf}}. That path is a symlink: by default it points at the shipped defaults, and in custom mode it points at a file you own. Three directives in that file name the certificate files:


This path is a symlink. By default, it points at the QuantaStor-shipped default:
{| class="wikitable"
! Directive !! What goes in it !! Notes
|-
| {{Code|1=ssl_certificate}} || The server (leaf) certificate first, then the intermediate CA certificates in order. The root CA certificate is optional and harmless. || The first certificate in the file is the one nginx serves. A CA bundle placed before the leaf makes nginx present the CA certificate instead of yours.
|-
| {{Code|1=ssl_certificate_key}} || The private key, unencrypted, with no passphrase. || PKCS#8 ({{Code|1=BEGIN PRIVATE KEY}}), RSA ({{Code|1=BEGIN RSA PRIVATE KEY}}) and EC ({{Code|1=BEGIN EC PRIVATE KEY}}) keys are all accepted. nginx starts non-interactively, so it cannot prompt for a passphrase.
|-
| {{Code|1=ssl_client_certificate}} || '''Leave this pointing at {{Code|1=qscacert.pem}}.''' || It is only used for client certificate authentication, which QuantaStor does not enable. Never put a private key or the server certificate in it. Nodes that already point it at a separate CA file still work; see [[#Installing the certificate on each node|step 3]].
|}
 
{| class="wikitable"
! Path !! Purpose
|-
| {{Code|1=/opt/osnexus/common/lib/nginx_quantastor_ssl.conf}} || Active TLS settings. A symlink; do not edit it.
|-
| {{Code|1=/opt/osnexus/common/lib/nginx_quantastor_ssl_default.conf}} || Shipped defaults. Do not edit; it is replaced on upgrade.
|-
| {{Code|1=/var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf}} || Your custom TLS settings, created by {{Code|1=qs-util wuicustomcerts}}. Preserved across upgrades.
|-
| {{Code|1=/var/opt/osnexus/quantastor/ssl/qsrestsrv.pem}} || Default self-signed certificate and key. On a default install this is a symlink to a package-owned file.
|-
| {{Code|1=/var/opt/osnexus/quantastor/ssl/qscacert.pem}} || The QuantaStor grid CA certificate. On a default install this is a symlink to a package-owned file. Do not replace it.
|-
| {{Code|1=/var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem}} || Suggested name for your combined key and certificate file.
|-
| {{Code|1=/var/opt/osnexus/quantastor/ssl/custom_fullchain.pem}} and {{Code|1=custom.key}} || Suggested names if you keep the certificate chain and the key in separate files.
|}
 
{| class="wikitable" style="border: 2px solid #c00;"
|-
| '''Before you start'''
* '''Never copy over {{Code|1=qsrestsrv.pem}} or {{Code|1=qscacert.pem}}.''' On a default install both are symlinks to package-owned files under {{Code|1=/opt/osnexus/common/lib}}. {{Code|1=cp}} follows the symlink and overwrites the packaged default. Always give your files new names.
* '''Never replace {{Code|1=qscacert.pem}} with your own CA.''' It is the QuantaStor grid CA that the QuantaStor service uses to authenticate other nodes in the grid. Replacing it breaks grid communication.
* '''A bad certificate or key stops nginx''', which takes down the web interface and REST API on that node. That is why you test the configuration with {{Code|1=nginx -t}} before restarting. To recover, run {{Code|1=qs-util wuicustomcertsdefault}} (see [[#Reverting to the default certificate|Reverting to the default certificate]]).
|}


/opt/osnexus/common/lib/nginx_quantastor_ssl.conf
== Certificate requirements ==
  -> /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.
Most failed installs trace back to the certificate itself, not to the QuantaStor side. Check each of these before you prepare files. For the full process of requesting a certificate from your CA, follow your CA's own documentation.


== Commands ==
* '''The Subject Alternative Name (SAN) must list every name and IP address a browser uses to reach the node''': the fully qualified name, the short name, the management IP, and any HA or site virtual interface (VIF) that resolves to this node. Browsers ignore the Common Name (CN). A certificate with a correct CN and no SAN passes {{Code|1=openssl verify}} but fails in every browser.
* '''The request must ask for the SAN.''' A reference request, generated in {{Code|1=/root}} or another working directory:
<pre style="font-size: smaller">
openssl req -new -newkey rsa:2048 -nodes -sha256 -keyout node.key -out node.csr \
  -subj "/CN=node1.example.com" \
  -addext "subjectAltName=DNS:node1.example.com,DNS:node1,IP:192.0.2.10"
</pre>
:Check that the request carries the SAN ({{Code|1=openssl req}} has no {{Code|1=-ext}} option):
<pre style="font-size: smaller">
openssl req -in node.csr -noout -text | grep -A1 'Subject Alternative Name'
</pre>
* '''The CA must keep the SAN.''' Microsoft AD CS drops it unless the certificate template's Subject Name setting is ''Supply in the request'', or the CA has the {{Code|1=EDITF_ATTRIBUTESUBJECTALTNAME2}} flag set and you pass the SAN as a request attribute:
<pre style="font-size: smaller">
certreq -submit -attrib "CertificateTemplate:WebServer\nSAN:dns=node1.example.com&dns=node1&ipaddress=192.0.2.10" node.csr node.cer
</pre>
:Always check the '''issued''' certificate, not the request:
<pre style="font-size: smaller">
openssl x509 -in node.cer -noout -subject -ext subjectAltName
</pre>
* '''It must be a server certificate, not a CA certificate''': {{Code|1=basicConstraints}} {{Code|1=CA:FALSE}} and {{Code|1=extendedKeyUsage}} {{Code|1=serverAuth}}. Check with {{Code|1=openssl x509 -in node.cer -noout -ext basicConstraints,extendedKeyUsage}}.
* '''Key and signature''': RSA 2048 bits or larger, or EC P-256 or larger, signed with SHA-256. The default configuration accepts TLS 1.2 and TLS 1.3 with ECDHE cipher suites only. ''(Note: due to the frequency of security updates this may be out of date and system configuration files should be referenced. The authoritative list is in {{Code|1=/opt/osnexus/common/lib/nginx_quantastor_ssl_default.conf}}.)''
* '''One certificate per node, or one shared certificate.''' Either generate a key and request on each node and get a certificate for each (the usual case with a corporate CA; never copy a private key between nodes), or use one multi-SAN or wildcard certificate on every node.
* '''Keep working files out of the QuantaStor certificate directory.''' Generate keys and requests in {{Code|1=/root}} or a working directory. Only the final files go in {{Code|1=/var/opt/osnexus/quantastor/ssl/}}.
 
== Preparing the PEM files ==
 
nginx needs PEM files. Convert what your CA returned, then check the files before they go anywhere near nginx.
 
=== Converting from other formats ===


{| class="wikitable"
{| class="wikitable"
! Command !! Purpose
! You have !! Command
|-
|-
| <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.
| PFX / PKCS#12 bundle || {{Code|1=openssl pkcs12 -in cert.pfx -out all.pem -nodes}}, then split the output into the leaf certificate, the chain and the key.
|-
|-
| <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>.
| DER-encoded {{Code|1=.cer}} (Windows CAs often return this) || {{Code|1=openssl x509 -inform der -in cert.cer -out cert.pem}}
|-
|-
| <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.
| PKCS#7 chain ({{Code|1=.p7b}}, from ''Download certificate chain'' on a Windows CA) || {{Code|1=openssl pkcs7 -inform DER -in chain.p7b -print_certs -out chain.pem}}. A {{Code|1=.cer}} from {{Code|1=certreq -submit}} is the leaf only, not the chain.
|-
| A passphrase-protected key || {{Code|1=openssl pkey -in enc.key -out key.pem}}
|-
| Windows CRLF line endings || {{Code|1=dos2unix key.pem leaf.pem chain.pem}}
|}
|}


== Default Configuration (Reference) ==
=== Checking the key, the names and the order ===
 
Confirm the key belongs to the certificate. The two hashes must be identical:
<pre style="font-size: smaller">
openssl x509 -in leaf.pem -noout -pubkey | sha256sum
openssl pkey -in key.pem -pubout | sha256sum
</pre>
 
Confirm the SAN lists every name and IP address used to reach the web interface on this node:
<pre style="font-size: smaller">
openssl x509 -in leaf.pem -noout -ext subjectAltName
</pre>
 
Then build the file nginx will read. QuantaStor's own default is one combined file, referenced by both {{Code|1=ssl_certificate}} and {{Code|1=ssl_certificate_key}}. In a combined file the key can sit anywhere; QuantaStor's own files put it first:
<pre style="font-size: smaller">
cat key.pem leaf.pem chain.pem > qsrestsrv_custom.pem
</pre>


The shipped default <code>nginx_quantastor_ssl_default.conf</code>:
If you prefer separate files, put the leaf followed by the chain in one file and keep the key in its own file:
<pre style="font-size: smaller">
cat leaf.pem chain.pem > custom_fullchain.pem
cp key.pem custom.key
</pre>


<pre>
'''Check the certificate order.''' This is the most common assembly mistake. The first subject listed must be the node, then the intermediate, then the root:
ssl_certificate    /var/opt/osnexus/quantastor/ssl/qsrestsrv.pem;
<pre style="font-size: smaller">
ssl_certificate_key /var/opt/osnexus/quantastor/ssl/qsrestsrv.pem;
openssl crl2pkcs7 -nocrl -certfile qsrestsrv_custom.pem | openssl pkcs7 -print_certs -noout
ssl_client_certificate /var/opt/osnexus/quantastor/ssl/qscacert.pem;
</pre>


ssl_protocols TLSv1.2 TLSv1.3;
'''Check the chain and the names.''' {{Code|1=openssl verify}} reads only the first certificate in the file it is given, so pass the combined (or full-chain) file both as the subject and as {{Code|1=-untrusted}}. {{Code|1=ca-bundle.pem}} holds your root CA certificate (and any intermediates you want to treat as trusted). Check one name or IP per run:
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";
<pre style="font-size: smaller">
ssl_prefer_server_ciphers on;
openssl verify -show_chain -purpose sslserver -verify_hostname node1.example.com \
gzip off;
  -CAfile ca-bundle.pem -untrusted qsrestsrv_custom.pem qsrestsrv_custom.pem
openssl verify -purpose sslserver -verify_ip 192.0.2.10 \
  -CAfile ca-bundle.pem -untrusted qsrestsrv_custom.pem qsrestsrv_custom.pem
</pre>
</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.
Expect {{Code|1=OK}}, and with {{Code|1=-show_chain}} one depth line per certificate in the chain (three for leaf, intermediate and root). Never put the node certificate in {{Code|1=ca-bundle.pem}}: a trusted leaf makes {{Code|1=openssl verify}} print {{Code|1=OK}} on a broken chain.


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.
{| class="wikitable"
! Error !! Meaning
|-
| 2 or 20, ''unable to get issuer certificate'' || An intermediate or the root is missing from the chain or from {{Code|1=ca-bundle.pem}}.
|-
| 10, ''certificate has expired'' || The certificate is past its end date.
|-
| 26, ''unsupported certificate purpose'' || A CA certificate is first in the file, or the CA issued the certificate from the wrong template (no {{Code|1=serverAuth}}).
|-
| 62, ''hostname mismatch'' || The name or IP is not in the SAN (or, for a certificate with no SAN at all, not in the CN). Name matching is case-insensitive.
|}


== Typical Workflow: Installing a CA-Signed Certificate ==
== Installing the certificate on each node ==


'''1.''' Stage your certificate and key under <code>/var/opt/osnexus/quantastor/ssl/</code>. The recommended filenames are:
nginx runs on every node, so repeat these steps on each node whose web interface you want to secure, logged in over SSH as root. The commands are described on [[QuantaStor Shell Utilities]].


/var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem
'''1. Enable custom mode.'''
/var/opt/osnexus/quantastor/ssl/qscacert_custom.pem
<pre style="font-size: smaller">
qs-util wuicustomcerts
</pre>
This copies the shipped defaults to {{Code|1=/var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf}} and points the active symlink at it. On systems with SELinux tools installed it also applies the {{Code|1=httpd_config_t}} context so nginx can read the file. If the custom file already exists, the command reports {{Code|1=File already exists}} and does not touch the file or the symlink.
 
'''2. Copy your files into place under new names, and lock them down.'''
<pre style="font-size: smaller">
cp qsrestsrv_custom.pem /var/opt/osnexus/quantastor/ssl/
chown root:root /var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem
chmod 600 /var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem
</pre>
For separate files, copy {{Code|1=custom_fullchain.pem}} and {{Code|1=custom.key}} the same way. The nginx master process reads certificates as root, so {{Code|1=root:root}} with mode {{Code|1=0600}} is correct.


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.
'''3. Edit the custom configuration.''' In {{Code|1=/var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf}}, change only {{Code|1=ssl_certificate}} and {{Code|1=ssl_certificate_key}}. Leave {{Code|1=ssl_client_certificate}} as it is. For a combined file:
<pre style="font-size: smaller">
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.pem;
</pre>
For separate files:
<pre style="font-size: smaller">
ssl_certificate /var/opt/osnexus/quantastor/ssl/custom_fullchain.pem;
ssl_certificate_key /var/opt/osnexus/quantastor/ssl/custom.key;
ssl_client_certificate /var/opt/osnexus/quantastor/ssl/qscacert.pem;
</pre>
{{Code|1=ssl_client_certificate}} names the CAs nginx would use to verify client certificates. QuantaStor never enables client certificate verification (no {{Code|1=ssl_verify_client}} in any server block), so this directive has no effect on what browsers see. Your CA chain reaches browsers through {{Code|1=ssl_certificate}}. Three settings are all functionally identical for the web interface:
* leaving it on {{Code|1=qscacert.pem}} (recommended, nothing to get wrong);
* pointing it at a separate {{Code|1=qscacert_custom.pem}} holding your root and intermediate CA certificates (what earlier versions of this page recommended; harmless, leave it if a node already has it);
* pointing it at your server bundle (what the oldest version of this page said; also harmless).
Never overwrite {{Code|1=qscacert.pem}} itself and never put a private key or the server certificate in any file named by this directive.
The file is a standard nginx TLS fragment, so you can also tighten {{Code|1=ssl_protocols}} or {{Code|1=ssl_ciphers}} here, for example {{Code|1=ssl_protocols TLSv1.3;}} to accept TLS 1.3 only. For the wider TLS hardening options, see [[Custom SSL TLS Security]].


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.
'''4. Test the configuration.''' Do not continue until this reports that the syntax is ok and the test is successful:
<pre style="font-size: smaller">
nginx -t
</pre>


'''2.''' Enable custom mode:
'''5. Restart nginx.'''
<pre style="font-size: smaller">
qs-util wuicustomcertsrestart
</pre>
Confirm it prints {{Code|1=Nginx restarted successfully.}} If nginx does not come back, the command prints the nginx service status and the last five minutes of the nginx journal.


qs-util wuicustomcerts
'''6. Verify what the node serves.''' Check the return code, not just the subject:
<pre style="font-size: smaller">
echo | openssl s_client -connect node1.example.com:443 -servername node1.example.com \
  -verify_hostname node1.example.com -CAfile ca-bundle.pem 2>/dev/null | grep -E 'Verify return code|subject='
</pre>
Expect {{Code|1=Verify return code: 0 (ok)}} and the node's own subject. Then load the web interface in a new private or incognito window; a browser that already has a session open can keep showing the old certificate.


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.
The Certificates view shows your certificate on the NGINX row after the next scan ({{Code|1=qs cert-rescan}}, or within 30 minutes). The Rest Service row continues to show the shipped default certificate; that is a known display issue and does not affect what nginx serves.


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


<pre>
<pre style="font-size: smaller">
ssl_certificate    /var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem;
ls -l /opt/osnexus/common/lib/nginx_quantastor_ssl.conf
ssl_certificate_key /var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem;
ssl_client_certificate /var/opt/osnexus/quantastor/ssl/qscacert_custom.pem;
</pre>
</pre>


You can also tighten protocols and ciphers here (see [[#Tightening TLS Protocols and Ciphers]] below).
A target of {{Code|1=/var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf}} means custom mode is active; {{Code|1=/opt/osnexus/common/lib/nginx_quantastor_ssl_default.conf}} means the defaults are active. Upgrades leave an existing symlink alone, so custom mode survives an upgrade.


'''4.''' Apply the change:
If the custom file exists but the symlink points at the defaults, running {{Code|1=qs-util wuicustomcerts}} again does not fix it: the command does nothing once the custom file exists. Re-point the symlink by hand, then test and restart:
<pre style="font-size: smaller">
ln -sf /var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf /opt/osnexus/common/lib/nginx_quantastor_ssl.conf
nginx -t
qs-util wuicustomcertsrestart
</pre>


qs-util wuicustomcertsrestart
== Renewing a certificate ==


Confirm the command reports '''Nginx restarted successfully''', then load the WebUI in a browser to verify the new certificate is presented.
To renew, prepare and check the new files exactly as for a first install, copy them over your own custom files (never over {{Code|1=qsrestsrv.pem}} or {{Code|1=qscacert.pem}}), then run {{Code|1=nginx -t}} and {{Code|1=qs-util wuicustomcertsrestart}} and verify as in [[#Installing the certificate on each node|step 6]]. The custom configuration already points at your file names, so it needs no edit.


== Tightening TLS Protocols and Ciphers ==
You can reuse the existing private key for a renewal if your CA accepts the original certificate request. Otherwise generate a new key and request as in [[#Certificate requirements|Certificate requirements]]. The NGINX row in the Certificates view updates on the next scan ({{Code|1=qs cert-rescan}}, or within 30 minutes).


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:
== Reverting to the default certificate ==


<pre>
<pre style="font-size: smaller">
# Restrict to TLS 1.3 only
qs-util wuicustomcertsdefault
ssl_protocols TLSv1.3;
</pre>
</pre>


After any edit, run <code>qs-util wuicustomcertsrestart</code> to reload.
This deletes {{Code|1=nginx_quantastor_ssl_custom.conf}}, points the symlink back at the shipped defaults and restarts nginx, so the node serves its self-signed certificate again. It does not delete your certificate and key files; remove them yourself if you no longer need them. To start a fresh custom configuration from the shipped defaults, run {{Code|1=qs-util wuicustomcertsdefault}} and then {{Code|1=qs-util wuicustomcerts}}.


== Reverting to Defaults ==
== Troubleshooting ==


If a customized config breaks Nginx or you simply want to go back to QuantaStor-managed self-signed certs:
; nginx fails to restart
: {{Code|1=qs-util wuicustomcertsrestart}} prints the service status and recent journal. The usual causes are a typo or missing semicolon in the custom file, a certificate or key path that does not exist, a certificate and key that do not match, or a passphrase-protected key. On SELinux systems, check the file context on the certificate and key files. To get the web interface back while you investigate, run {{Code|1=qs-util wuicustomcertsdefault}}.


qs-util wuicustomcertsdefault
; The browser still reports the certificate as invalid
: Check the SAN against the exact name or IP in the address bar, and check the certificate order: if the first certificate in the file is a CA certificate, nginx serves it and the browser rejects it. The web interface sends a Strict-Transport-Security header, so once a browser has visited the node it does not offer a way to bypass a certificate error.


This deletes the custom file, restores the symlink to <code>nginx_quantastor_ssl_default.conf</code>, and restarts Nginx in one step.
; {{Code|1=openssl verify}} reports OK but the browser fails
: The certificate probably has no SAN, or {{Code|1=ca-bundle.pem}} contains the node certificate. Run the checks in [[#Checking the key, the names and the order|Checking the key, the names and the order]] again against the issued certificate.


== Troubleshooting ==
== Certificate Template Manager and the web interface ==


; <code>qs-util wuicustomcerts</code> reports "File already exists"
{{Navigation|Security &rarr; Certificates ''(section)''}}
: 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
The [[Certificate Template Manager]] stores certificates centrally and applies them to services such as the object gateways and HAProxy. Its [[Update Certificates]] dialog does not offer the web interface as a use case. Use the manual procedure on this page to install a certificate on the web interface and REST API. The {{Code|1=qs cert-update}} command has an {{Code|1=nginx}} use case, but the manual procedure is the supported path until that command checks the key, tests the nginx configuration and can roll back.
: <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
[[File:Docs-wui-certs-grid.png|thumb|right|449px|The Certificates view before a custom install. Each node has an NGINX row for the web interface certificate.]]
: 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
The Certificates view lists each node's certificates by use case, and the NGINX row is the web interface certificate. QuantaStor finds that certificate by reading {{Code|1=ssl_certificate}} from {{Code|1=/opt/osnexus/common/lib/nginx_quantastor_ssl.conf}}, the symlink that {{Code|1=qs-util wuicustomcerts}} repoints. After a custom install, the NGINX row shows your certificate, and certificate expiry alerting follows it. Discovery runs every 30 minutes; {{Code|1=qs cert-rescan}} refreshes it on demand. The Rest Service row keeps showing the shipped default certificate, even though nginx no longer serves it.
: <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 ==
== Related pages ==


{| class="wikitable"
* [[Certificate Template Manager]]
! Path !! Purpose
* [[Custom SSL TLS Security]]
|-
* [[Security Configuration]]
| <code>/opt/osnexus/common/lib/nginx_quantastor_ssl.conf</code> || Active SSL config; symlink, do not edit
* [[QuantaStor Shell Utilities]]
|-
* [[Network Port Usage]]
| <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 ==
----
<small>''Verified against QuantaStor 6.9.0.''</small>


* <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).
[[Category:admin_guide]]

Latest revision as of 21:15, 6 November 2026

This page explains how to replace the self-signed certificate on the QuantaStor web interface and REST API with a certificate signed by your own or a public certificate authority (CA). It covers what the certificate must contain, how to assemble the PEM files, how to install them on each node, how to verify the result, and how to revert.

Each QuantaStor node serves its web interface through nginx, and nginx presents one certificate on ports 443, 8080 and 8153. All three ports serve the same web interface and REST endpoints, so one certificate change covers all of them. Node-to-node grid communication uses a separate service on port 5151 with its own certificates and is not affected by anything on this page.

Which file holds what

nginx reads its TLS settings from /opt/osnexus/common/lib/nginx_quantastor_ssl.conf. That path is a symlink: by default it points at the shipped defaults, and in custom mode it points at a file you own. Three directives in that file name the certificate files:

Directive What goes in it Notes
ssl_certificate The server (leaf) certificate first, then the intermediate CA certificates in order. The root CA certificate is optional and harmless. The first certificate in the file is the one nginx serves. A CA bundle placed before the leaf makes nginx present the CA certificate instead of yours.
ssl_certificate_key The private key, unencrypted, with no passphrase. PKCS#8 (BEGIN PRIVATE KEY), RSA (BEGIN RSA PRIVATE KEY) and EC (BEGIN EC PRIVATE KEY) keys are all accepted. nginx starts non-interactively, so it cannot prompt for a passphrase.
ssl_client_certificate Leave this pointing at qscacert.pem. It is only used for client certificate authentication, which QuantaStor does not enable. Never put a private key or the server certificate in it. Nodes that already point it at a separate CA file still work; see step 3.
Path Purpose
/opt/osnexus/common/lib/nginx_quantastor_ssl.conf Active TLS settings. A symlink; do not edit it.
/opt/osnexus/common/lib/nginx_quantastor_ssl_default.conf Shipped defaults. Do not edit; it is replaced on upgrade.
/var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf Your custom TLS settings, created by qs-util wuicustomcerts. Preserved across upgrades.
/var/opt/osnexus/quantastor/ssl/qsrestsrv.pem Default self-signed certificate and key. On a default install this is a symlink to a package-owned file.
/var/opt/osnexus/quantastor/ssl/qscacert.pem The QuantaStor grid CA certificate. On a default install this is a symlink to a package-owned file. Do not replace it.
/var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem Suggested name for your combined key and certificate file.
/var/opt/osnexus/quantastor/ssl/custom_fullchain.pem and custom.key Suggested names if you keep the certificate chain and the key in separate files.
Before you start
  • Never copy over qsrestsrv.pem or qscacert.pem. On a default install both are symlinks to package-owned files under /opt/osnexus/common/lib. cp follows the symlink and overwrites the packaged default. Always give your files new names.
  • Never replace qscacert.pem with your own CA. It is the QuantaStor grid CA that the QuantaStor service uses to authenticate other nodes in the grid. Replacing it breaks grid communication.
  • A bad certificate or key stops nginx, which takes down the web interface and REST API on that node. That is why you test the configuration with nginx -t before restarting. To recover, run qs-util wuicustomcertsdefault (see Reverting to the default certificate).

Certificate requirements

Most failed installs trace back to the certificate itself, not to the QuantaStor side. Check each of these before you prepare files. For the full process of requesting a certificate from your CA, follow your CA's own documentation.

  • The Subject Alternative Name (SAN) must list every name and IP address a browser uses to reach the node: the fully qualified name, the short name, the management IP, and any HA or site virtual interface (VIF) that resolves to this node. Browsers ignore the Common Name (CN). A certificate with a correct CN and no SAN passes openssl verify but fails in every browser.
  • The request must ask for the SAN. A reference request, generated in /root or another working directory:
openssl req -new -newkey rsa:2048 -nodes -sha256 -keyout node.key -out node.csr \
  -subj "/CN=node1.example.com" \
  -addext "subjectAltName=DNS:node1.example.com,DNS:node1,IP:192.0.2.10"
Check that the request carries the SAN (openssl req has no -ext option):
openssl req -in node.csr -noout -text | grep -A1 'Subject Alternative Name'
  • The CA must keep the SAN. Microsoft AD CS drops it unless the certificate template's Subject Name setting is Supply in the request, or the CA has the EDITF_ATTRIBUTESUBJECTALTNAME2 flag set and you pass the SAN as a request attribute:
certreq -submit -attrib "CertificateTemplate:WebServer\nSAN:dns=node1.example.com&dns=node1&ipaddress=192.0.2.10" node.csr node.cer
Always check the issued certificate, not the request:
openssl x509 -in node.cer -noout -subject -ext subjectAltName
  • It must be a server certificate, not a CA certificate: basicConstraints CA:FALSE and extendedKeyUsage serverAuth. Check with openssl x509 -in node.cer -noout -ext basicConstraints,extendedKeyUsage.
  • Key and signature: RSA 2048 bits or larger, or EC P-256 or larger, signed with SHA-256. The default configuration accepts TLS 1.2 and TLS 1.3 with ECDHE cipher suites only. (Note: due to the frequency of security updates this may be out of date and system configuration files should be referenced. The authoritative list is in /opt/osnexus/common/lib/nginx_quantastor_ssl_default.conf.)
  • One certificate per node, or one shared certificate. Either generate a key and request on each node and get a certificate for each (the usual case with a corporate CA; never copy a private key between nodes), or use one multi-SAN or wildcard certificate on every node.
  • Keep working files out of the QuantaStor certificate directory. Generate keys and requests in /root or a working directory. Only the final files go in /var/opt/osnexus/quantastor/ssl/.

Preparing the PEM files

nginx needs PEM files. Convert what your CA returned, then check the files before they go anywhere near nginx.

Converting from other formats

You have Command
PFX / PKCS#12 bundle openssl pkcs12 -in cert.pfx -out all.pem -nodes, then split the output into the leaf certificate, the chain and the key.
DER-encoded .cer (Windows CAs often return this) openssl x509 -inform der -in cert.cer -out cert.pem
PKCS#7 chain (.p7b, from Download certificate chain on a Windows CA) openssl pkcs7 -inform DER -in chain.p7b -print_certs -out chain.pem. A .cer from certreq -submit is the leaf only, not the chain.
A passphrase-protected key openssl pkey -in enc.key -out key.pem
Windows CRLF line endings dos2unix key.pem leaf.pem chain.pem

Checking the key, the names and the order

Confirm the key belongs to the certificate. The two hashes must be identical:

openssl x509 -in leaf.pem -noout -pubkey | sha256sum
openssl pkey -in key.pem -pubout | sha256sum

Confirm the SAN lists every name and IP address used to reach the web interface on this node:

openssl x509 -in leaf.pem -noout -ext subjectAltName

Then build the file nginx will read. QuantaStor's own default is one combined file, referenced by both ssl_certificate and ssl_certificate_key. In a combined file the key can sit anywhere; QuantaStor's own files put it first:

cat key.pem leaf.pem chain.pem > qsrestsrv_custom.pem

If you prefer separate files, put the leaf followed by the chain in one file and keep the key in its own file:

cat leaf.pem chain.pem > custom_fullchain.pem
cp key.pem custom.key

Check the certificate order. This is the most common assembly mistake. The first subject listed must be the node, then the intermediate, then the root:

openssl crl2pkcs7 -nocrl -certfile qsrestsrv_custom.pem | openssl pkcs7 -print_certs -noout

Check the chain and the names. openssl verify reads only the first certificate in the file it is given, so pass the combined (or full-chain) file both as the subject and as -untrusted. ca-bundle.pem holds your root CA certificate (and any intermediates you want to treat as trusted). Check one name or IP per run:

openssl verify -show_chain -purpose sslserver -verify_hostname node1.example.com \
  -CAfile ca-bundle.pem -untrusted qsrestsrv_custom.pem qsrestsrv_custom.pem
openssl verify -purpose sslserver -verify_ip 192.0.2.10 \
  -CAfile ca-bundle.pem -untrusted qsrestsrv_custom.pem qsrestsrv_custom.pem

Expect OK, and with -show_chain one depth line per certificate in the chain (three for leaf, intermediate and root). Never put the node certificate in ca-bundle.pem: a trusted leaf makes openssl verify print OK on a broken chain.

Error Meaning
2 or 20, unable to get issuer certificate An intermediate or the root is missing from the chain or from ca-bundle.pem.
10, certificate has expired The certificate is past its end date.
26, unsupported certificate purpose A CA certificate is first in the file, or the CA issued the certificate from the wrong template (no serverAuth).
62, hostname mismatch The name or IP is not in the SAN (or, for a certificate with no SAN at all, not in the CN). Name matching is case-insensitive.

Installing the certificate on each node

nginx runs on every node, so repeat these steps on each node whose web interface you want to secure, logged in over SSH as root. The commands are described on QuantaStor Shell Utilities.

1. Enable custom mode.

qs-util wuicustomcerts

This copies the shipped defaults to /var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf and points the active symlink at it. On systems with SELinux tools installed it also applies the httpd_config_t context so nginx can read the file. If the custom file already exists, the command reports File already exists and does not touch the file or the symlink.

2. Copy your files into place under new names, and lock them down.

cp qsrestsrv_custom.pem /var/opt/osnexus/quantastor/ssl/
chown root:root /var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem
chmod 600 /var/opt/osnexus/quantastor/ssl/qsrestsrv_custom.pem

For separate files, copy custom_fullchain.pem and custom.key the same way. The nginx master process reads certificates as root, so root:root with mode 0600 is correct.

3. Edit the custom configuration. In /var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf, change only ssl_certificate and ssl_certificate_key. Leave ssl_client_certificate as it is. For a combined file:

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.pem;

For separate files:

ssl_certificate /var/opt/osnexus/quantastor/ssl/custom_fullchain.pem;
ssl_certificate_key /var/opt/osnexus/quantastor/ssl/custom.key;
ssl_client_certificate /var/opt/osnexus/quantastor/ssl/qscacert.pem;

ssl_client_certificate names the CAs nginx would use to verify client certificates. QuantaStor never enables client certificate verification (no ssl_verify_client in any server block), so this directive has no effect on what browsers see. Your CA chain reaches browsers through ssl_certificate. Three settings are all functionally identical for the web interface:

  • leaving it on qscacert.pem (recommended, nothing to get wrong);
  • pointing it at a separate qscacert_custom.pem holding your root and intermediate CA certificates (what earlier versions of this page recommended; harmless, leave it if a node already has it);
  • pointing it at your server bundle (what the oldest version of this page said; also harmless).

Never overwrite qscacert.pem itself and never put a private key or the server certificate in any file named by this directive. The file is a standard nginx TLS fragment, so you can also tighten ssl_protocols or ssl_ciphers here, for example ssl_protocols TLSv1.3; to accept TLS 1.3 only. For the wider TLS hardening options, see Custom SSL TLS Security.

4. Test the configuration. Do not continue until this reports that the syntax is ok and the test is successful:

nginx -t

5. Restart nginx.

qs-util wuicustomcertsrestart

Confirm it prints Nginx restarted successfully. If nginx does not come back, the command prints the nginx service status and the last five minutes of the nginx journal.

6. Verify what the node serves. Check the return code, not just the subject:

echo | openssl s_client -connect node1.example.com:443 -servername node1.example.com \
  -verify_hostname node1.example.com -CAfile ca-bundle.pem 2>/dev/null | grep -E 'Verify return code|subject='

Expect Verify return code: 0 (ok) and the node's own subject. Then load the web interface in a new private or incognito window; a browser that already has a session open can keep showing the old certificate.

The Certificates view shows your certificate on the NGINX row after the next scan (qs cert-rescan, or within 30 minutes). The Rest Service row continues to show the shipped default certificate; that is a known display issue and does not affect what nginx serves.

Checking which configuration is active

ls -l /opt/osnexus/common/lib/nginx_quantastor_ssl.conf

A target of /var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf means custom mode is active; /opt/osnexus/common/lib/nginx_quantastor_ssl_default.conf means the defaults are active. Upgrades leave an existing symlink alone, so custom mode survives an upgrade.

If the custom file exists but the symlink points at the defaults, running qs-util wuicustomcerts again does not fix it: the command does nothing once the custom file exists. Re-point the symlink by hand, then test and restart:

ln -sf /var/opt/osnexus/quantastor/ssl/nginx_quantastor_ssl_custom.conf /opt/osnexus/common/lib/nginx_quantastor_ssl.conf
nginx -t
qs-util wuicustomcertsrestart

Renewing a certificate

To renew, prepare and check the new files exactly as for a first install, copy them over your own custom files (never over qsrestsrv.pem or qscacert.pem), then run nginx -t and qs-util wuicustomcertsrestart and verify as in step 6. The custom configuration already points at your file names, so it needs no edit.

You can reuse the existing private key for a renewal if your CA accepts the original certificate request. Otherwise generate a new key and request as in Certificate requirements. The NGINX row in the Certificates view updates on the next scan (qs cert-rescan, or within 30 minutes).

Reverting to the default certificate

qs-util wuicustomcertsdefault

This deletes nginx_quantastor_ssl_custom.conf, points the symlink back at the shipped defaults and restarts nginx, so the node serves its self-signed certificate again. It does not delete your certificate and key files; remove them yourself if you no longer need them. To start a fresh custom configuration from the shipped defaults, run qs-util wuicustomcertsdefault and then qs-util wuicustomcerts.

Troubleshooting

nginx fails to restart
qs-util wuicustomcertsrestart prints the service status and recent journal. The usual causes are a typo or missing semicolon in the custom file, a certificate or key path that does not exist, a certificate and key that do not match, or a passphrase-protected key. On SELinux systems, check the file context on the certificate and key files. To get the web interface back while you investigate, run qs-util wuicustomcertsdefault.
The browser still reports the certificate as invalid
Check the SAN against the exact name or IP in the address bar, and check the certificate order: if the first certificate in the file is a CA certificate, nginx serves it and the browser rejects it. The web interface sends a Strict-Transport-Security header, so once a browser has visited the node it does not offer a way to bypass a certificate error.
openssl verify reports OK but the browser fails
The certificate probably has no SAN, or ca-bundle.pem contains the node certificate. Run the checks in Checking the key, the names and the order again against the issued certificate.

Certificate Template Manager and the web interface

Navigation: Security → Certificates (section)

The Certificate Template Manager stores certificates centrally and applies them to services such as the object gateways and HAProxy. Its Update Certificates dialog does not offer the web interface as a use case. Use the manual procedure on this page to install a certificate on the web interface and REST API. The qs cert-update command has an nginx use case, but the manual procedure is the supported path until that command checks the key, tests the nginx configuration and can roll back.

The Certificates view before a custom install. Each node has an NGINX row for the web interface certificate.

The Certificates view lists each node's certificates by use case, and the NGINX row is the web interface certificate. QuantaStor finds that certificate by reading ssl_certificate from /opt/osnexus/common/lib/nginx_quantastor_ssl.conf, the symlink that qs-util wuicustomcerts repoints. After a custom install, the NGINX row shows your certificate, and certificate expiry alerting follows it. Discovery runs every 30 minutes; qs cert-rescan refreshes it on demand. The Rest Service row keeps showing the shipped default certificate, even though nginx no longer serves it.

Related pages


Verified against QuantaStor 6.9.0.