Applying Custom Web User Interface Certificates
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 -- the three certificate directives and the files on disk
- Certificate requirements -- SAN, key type and CA template checks before you start
- Preparing the PEM files -- converting, assembling and verifying the files
- Installing the certificate on each node -- the six-step procedure
- Renewing a certificate and Reverting to the default certificate
- Troubleshooting
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
|
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 verifybut fails in every browser. - The request must ask for the SAN. A reference request, generated in
/rootor 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 reqhas no-extoption):
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_ATTRIBUTESUBJECTALTNAME2flag 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:
basicConstraintsCA:FALSEandextendedKeyUsageserverAuth. Check withopenssl 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
/rootor 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.pemholding 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 wuicustomcertsrestartprints 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, runqs-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 verifyreports OK but the browser fails- The certificate probably has no SAN, or
ca-bundle.pemcontains 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
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 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
- Certificate Template Manager
- Custom SSL TLS Security
- Security Configuration
- QuantaStor Shell Utilities
- Network Port Usage
Verified against QuantaStor 6.9.0.