Nginx on Linux

1. Choose the store type

• ▸PEM directory: use pem_dir when nginx reads a combined PEM containing the chain and key. The store path is the containing directory; the agent must be able to write there.
• ▸Separate certificate/key files: use nginx_pem. The store path is a profile name such as web-example, approved on the host. One store represents both files.

2. Prepare the host as an administrator

Download and extract the current Linux archive from your ens0key appliance. Install or migrate both agent binaries with sudo sh ./install.sh. See the Linux migration instructions if upgrading an installation from 1.0.27 or earlier.

• ▸Start with a working nginx site and a successful /usr/sbin/nginx -t. The helper uses the standard nginx service and does not create sites or split combined PEM files.
• ▸Keep the existing certificate/key and their parent directories root-owned, without group/other write access. Targets must be regular files with no symlinks or extra hard links. The existing key must match the certificate and have mode 0600.
• ▸In Deploy → Agent stores, select the Linux agent and Nginx PEM files (Linux). Enter the profile name and existing paths, then use the generated host command.

Example paths for an existing site; substitute your own approved paths:

# Run from the extracted Linux agent archive on the target host.
sudo sh ./install-nginx-helper.sh --profile web-example \
  --certificate /etc/pki/nginx/web-example.crt \
  --key /etc/pki/nginx/private/web-example.key

The installer validates the existing pair and nginx baseline, writes a root-approved profile, generates scoped systemd write exceptions for the destination parents and enables the socket. It does not rewrite nginx site configuration. Existing profile paths cannot be changed by this command; overlapping profiles are rejected.

On SELinux hosts, retain the correct persistent labeling policy. The helper restores labels when writing; SELinux and agent hardening stay enabled. Only trusted service users should belong to the group allowed to access /run/ens0key-nginx.sock.

3. Check readiness and add the store

Select Check readiness. The actual worker/helper checks the approved profile, existing certificate/key pair, nginx configuration and temporary writes in the helper's service context. It does not change the live certificate or reload nginx. Pending recovery blocks readiness.

Readiness requires supervisor and worker 1.0.28 or newer. The GUI requires a successful check before adding a Linux PEM store and the result expires after five minutes. The API can save an unverified store; the worker repeats readiness before every deployment. Use the profile name as the store path, not a directory, and do not add a second store for the key.

4. Deploy and verify

Run Inventory, select the intended certificate and deploy to the store. The helper validates the chain/key, records recovery state, replaces the pair, checks nginx configuration and reloads. Custom post-deploy commands, passwords and trust-issuer options are not supported for this store type. A failed validation or reload triggers restoration of the previous pair; a failed rollback remains explicit in the job result.

Add an HTTPS service check using the actual connect IP/DNS, port and, where needed, a separate TLS server name (SNI). Follow the HTTPS verification guide. A successful reload alone does not prove that the endpoint serves the expected certificate or that clients trust its issuer.

5. Handle interrupted or failed work

Two file renames do not form one atomic transaction across power loss. A private pending journal lets a subsequent operation for the same profile restore the previous pair. Other profiles are blocked while recovery is pending; readiness reports it without triggering recovery. Keep host access to inspect the journal and served certificate, especially after a lost response. A host administrator may need to restart nginx after recovery; automatic boot-time recovery is not provided.