A TLS client sends its request through the network to the Ignition Gateway HTTPS listener. The listener then loads its server identity from the active keystore. Troubleshoot that path in order: link, address, port, process, keystore, certificate chain, and client validation.
How does the HTTPS request reach the gateway?
Start outside the gateway. A certificate change cannot repair a failed link, an incorrect hostname, a blocked port, or a request reaching another server. Confirm that DNS resolves the requested hostname to the intended gateway and that the client can establish a TCP connection to the configured HTTPS listener.
| Path element | Value to record | Passing check |
|---|---|---|
| Client request | Exact HTTPS hostname | Matches the intended certificate name |
| Address | Resolved gateway address | Reaches the correct host |
| Port | Configured HTTPS listener port | TCP connection completes |
| Gateway process | Running Ignition installation | The process owns the listener |
| TLS identity | Active server keystore | Listener presents the expected leaf certificate |
If TCP does not connect, inspect cabling, interface state, routing, address translation, and firewall policy before touching certificates. The proof for this stage is a successful TCP connection to the intended gateway address and HTTPS port.
Where is the active Linux installation?
Windows paths do not translate directly to Linux. Find the directory belonging to the process that actually owns the HTTPS listener. One installation placed Ignition under /usr/local/bin/ignition; that location is installation-specific, not a universal Linux path.
| Location | Observed contents or role | Decision |
|---|---|---|
/var/lib/ignition/ |
data, Gateway, temp, user-lib
|
Treat as runtime data until the service configuration proves otherwise |
/etc/ignition/ |
gateway.xml, gateway.xml_clean, ignition.conf, log4j.properties
|
Inspect configuration for the process and installation path; do not place private keys here by guesswork |
/var/lib/ignition/data/certificates/ |
cert-chain-store, cert-chain-store-old, gateway_network
|
Do not overwrite these internal stores merely because their names contain “certificate” |
{Ignition installation}/webserver/ssl.key |
Web-server keystore location identified for this layout | Use only after confirming this installation owns the HTTPS listener |
If /usr/local/bin/ignition is the confirmed installation root, the derived candidate is /usr/local/bin/ignition/webserver/ssl.key. Verify the service launch configuration and file access under the gateway service account. The proof is one installation root tied to the running gateway process and one confirmed web-server keystore path beneath it.
Which certificate objects belong in the keystore?
The HTTPS listener needs a server identity, not just a file containing certificate issuers. Assemble three related objects: the private key, the leaf certificate issued for the gateway hostname, and the intermediate certificate chain required to reach a client-trusted root.
| Object | Purpose | Failure when missing or wrong |
|---|---|---|
| Private key | Proves possession of the gateway identity | Listener cannot use the leaf certificate or retains the previous identity |
| Leaf certificate | Binds the public key to the gateway hostname | Name, validity, or key-pair checks fail |
| Intermediate chain | Connects the leaf to a trusted root | Some clients report an incomplete or untrusted chain |
| Root certificate | Client trust anchor | Normally belongs in the client trust store rather than the server identity entry |
A “full chain” file still does not replace the private key. Before import, use a certificate inspection utility to compare the public key derived from the private key with the public key in the leaf certificate. Inspect the leaf subject names and validity dates as separate checks. The proof is a matching key pair and an ordered leaf-to-intermediate chain for the requested hostname.
How do you install the identity into Ignition?
Use the Java keystore workflow associated with the running gateway installation. A Java development kit supplies the keystore tooling on Linux, but the tool location and package source depend on the distribution. Do not reuse a Windows drive path; create the keystore at a valid Unix path and install it at the confirmed Ignition web-server location.
- Stop certificate experiments on
cert-chain-storeandcert-chain-store-old. Their presence does not identify either file as the HTTPS server identity. - Back up the current
webserver/ssl.keyfile with its ownership and permissions intact. - Import the matching private key, leaf certificate, and intermediate chain into one private-key entry using the keystore type, password, and entry name required by the installed gateway configuration. Read those settings from the installation or its certificate procedure; do not substitute arbitrary values.
- Place the completed keystore at
{Ignition installation}/webserver/ssl.key. - Apply ownership and read permissions that let the gateway service account open the file without exposing the private key to unrelated users.
- Restart or reload the gateway component using the installation’s supported service procedure so the HTTPS listener reopens the keystore.
Watch the gateway startup diagnostics for keystore-open, password, entry, key, or chain errors. The proof is a clean listener startup followed by presentation of the new leaf certificate.
How should 90-day certificate renewal work?
Certificates issued with a 90-day lifetime require more than automated issuance. A renewal client such as certbot can obtain replacement files, but Ignition must also receive the renewed private key and certificate chain in its active keystore.
| Renewal stage | Required action | Verification |
|---|---|---|
| Issue | Renew before the current certificate expires | New leaf has a later expiration date |
| Validate | Confirm hostname, key pair, and intermediate chain | All three checks pass before deployment |
| Import | Rebuild or update the Ignition keystore | Private-key entry contains the renewed leaf and chain |
| Deploy | Replace the active keystore while preserving access controls | Gateway service account can read it |
| Activate | Perform the required reload or restart | Listener presents the renewed serial number and dates |
Make deployment transactional: build and validate a new keystore away from the live file, retain the last working copy, then replace the target. A renewal job that updates only the certificate files leaves Ignition serving the old identity. The proof is an off-host TLS query showing the renewed certificate after every automated run.
How do you verify the complete certificate path?
- Connect from another machine using the production hostname, not a loopback address or an address that bypasses normal routing.
- Confirm the connection reaches the expected address and configured HTTPS port.
- Inspect the presented leaf certificate and compare its identity and validity dates with the imported certificate.
- Verify that the hostname matches a name in the leaf certificate and that the server supplies the required intermediate chain.
- Repeat the test with every important client class because browsers, Java runtimes, and embedded clients can use different trust stores.
- Review gateway diagnostics after the handshake and confirm that no keystore or TLS error appeared during startup or connection handling.
If the old certificate remains visible, follow the packet again: confirm the client did not reach a proxy or second gateway, verify that the modified keystore belongs to the listening process, and confirm that the listener reloaded it. The proof is an external connection that presents the intended leaf and chain without a trust, name, or validity error.
FAQ
Can I copy a full-chain file over cert-chain-store?
No. A full-chain file does not contain the matching private key, and cert-chain-store is not proven to be the HTTPS identity keystore. Install the key, leaf, and intermediates in the confirmed webserver/ssl.key keystore.
Does Ignition use the Windows certificate path on Linux?
No. Use a Unix path under the installation that owns the running gateway. For the identified layout, the target pattern is {Ignition installation}/webserver/ssl.key.
Can I use a 90-day certificate with Ignition?
Yes, but renewal must also rebuild or update the Ignition keystore, deploy it, and activate it. Automating certificate issuance alone leaves the HTTPS listener on the old certificate.
Does the full chain include the private key?
No. The private key is a separate object and must match the leaf certificate. The server identity entry needs that key plus the leaf and required intermediate certificates.
Can I verify the certificate from the gateway itself?
A local check helps, but it can miss DNS, routing, proxy, firewall, and alternate-gateway errors. Finish by connecting from another machine through the production hostname and confirm the listener presents the intended leaf certificate and complete chain.