Applying Custom Web User Interface Certificates

Revision as of 21:15, 6 November 2026 by Qadmin (talk | contribs) (osn-seo-utilities: applying-custom-web-user-interface-certificates-re @ 20afb26880b1 (approved in the portal))
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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.