Finds active TLS server blocks and replaces certificate and key with local activation checks.
What happens
- The service agent on the server fetches the task from the appliance over outbound HTTPS, port 443.
- The certificate and key are checked and the integration reads the configuration the running Nginx uses, with every include. When the files already hold the certificate and Nginx presents it, nothing changes. If it fails: Invalid PEM or a key that does not match the certificate is refused before anything is written.
- The certificate and key are written atomically to CERT_PATH and KEY_PATH, and the previous files are kept as backups. With RELOAD=true (the default) nginx -t tests the configuration with the new files. If it fails: When nginx -t refuses the configuration, the previous files are put back and the running service is not touched.
- Nginx is reloaded. RELOAD_MAY_RESTART=true allows one nginx restart if two reloads still present the previous certificate. Other services are not restarted.
- Verification compares the certificate Nginx presents locally with the new certificate SHA-256 fingerprint. If it fails: If the reload fails or the local TLS service stops answering, restoration is attempted: the previous files are put back and Nginx is reloaded. The result says whether the restoration succeeded. Rollback later puts back what the last deploy replaced.
Technical details
- Connection
- The integration runs through the service agent on the server. The service agent connects over outbound HTTPS to the appliance, port 443 by default. You open no port into the server.
- Service ports
- 443, 80
- What you need
- The service agent installed on the server. The integration runs on the server under the Linux service agent. The service agent needs to read the nginx configuration, write the certificate and key files and run nginx -t and nginx -s reload; for a takeover also write the site's configuration file and /etc/nginx/ssl. check-access checks the access and nginx -t.
- Actions
- Discovery, Installation, Verification, Rollback
- Integrations
-
nginx-ssh2.0.0 - Note
-
- Takeover: when the site uses a certificate that an ACME client on the server or Nginx's own ACME module (Native ACME) renews, choosing the target is also the choice to take it over. Deploy writes the certificate to its own files in /etc/nginx/ssl and points the site's ssl_certificate lines at them. The ACME client or module keeps its files, settings and timers and goes on renewing into files the site no longer uses. The result says the site was taken over, and rollback points the lines back. For Native ACME, LOCAL_TLS_SNI selects the site. The certificate chain consists of the intermediate certificates that link the server certificate to a root certificate the browser trusts. ACME is the protocol a CA uses to issue certificates automatically.
- CERT_PATH and KEY_PATH come from discovery, which reports the active server blocks and the certificate manager each uses. The integration writes only under /etc/ssl, /etc/pki/tls, /etc/nginx/ssl, /etc/nginx/certs, /usr/local/etc/ssl and /usr/local/etc/nginx/ssl, or where the live configuration names the file.
- RELOAD=false writes the files without reloading Nginx. Activation is unconfirmed and the result is a warning. RELOAD_MAY_RESTART defaults to false.
- LOCAL_TLS_HOST is 127.0.0.1 or ::1. LOCAL_TLS_PORT and LOCAL_TLS_SNI can select the listener. The check measures local certificate identity; it does not prove external access, the complete trust chain or other nodes.
- Version 2.0.0 keeps the actions and input names of 1.4.0. CERT_PEM and KEY_PEM are binary inputs; the former CERT_PEM_BASE64 and KEY_PEM_BASE64 no longer exist.