Skip to content
Docs sslbrain sslbrain.com

Nginx

Copy link to the page “Nginx”

← All integrations

Linux · Web server

Finds active TLS server blocks and replaces certificate and key with local activation checks.

The service agent on the server fetches the task from the appliance over outbound HTTPS on port 443 and installs the certificate locally on the server. The appliance never connects to the server.

What happens

  1. The service agent on the server fetches the task from the appliance over outbound HTTPS, port 443.
  2. The certificate and key are validated and staged at the selected CERT_PATH and KEY_PATH. Previous files are saved and a local journal records progress. If it fails: Invalid PEM or a key that does not match the certificate returns a JSON result without switching the active files.
  3. With RELOAD=true, Nginx tests the configuration and loads the staged files as a check before the switch.
  4. The files are switched and Nginx is reloaded by default. RELOAD_MAY_RESTART=true allows one nginx restart if two reloads still present the previous certificate. Other services are not restarted.
  5. Verification compares the certificate Nginx presents locally with the new certificate SHA-256 fingerprint. An interrupted run is reconciled with the journal and current service before new work. If it fails: If the switch breaks a previously working local TLS service, restoration is attempted with a separate result. A working new certificate is not rolled back on resume. Rollback uses the journal and preserves later file edits.

Technical details

Connection
The package runs through the service agent on the server. The agent connects over outbound HTTPS to the appliance, port 443 by default. You open no port into the server.
Service ports
443, 80
You need
The service agent installed on the server. The service agent needs to read the nginx configuration and write in the certificate and key directories and the selected configuration directory during takeover. check-access checks access and nginx -t. Optional sudo permission for nginx -T reads the active configuration privately; it covers only fixed nginx checks and service operations, not file writes or custom commands.
Actions
Discovery, Installation, Verification, Rollback
Packages
nginx-ssh 1.4.0
Note
  • Discovery asks the running Nginx where its configuration is: the master process's -c, else the systemd unit, else nginx -V. Includes are followed as Nginx follows them. Deploy and rollback also accept a certificate and key outside the standard folders when a server block in the live configuration uses exactly that pair.
  • CERT_PATH and KEY_PATH must be supplied by discovery or configuration, including ad hoc deployment. The package does not guess filenames from the domain. Discovery reports active server blocks and known certificate managers; an enabled-config fallback is labelled in the result.
  • CERT_PEM and KEY_PEM accept raw PEM from appliance 0.4.44 or base64. Optional CERT_PEM_BASE64 and KEY_PEM_BASE64 each take precedence. The limit is 48,000 decoded bytes per value. An invalid supplied base64 value is not replaced with another value.
  • RELOAD=false changes the files and any selected certificate binding on disk without reloading the service. Activation is unconfirmed; original files and the journal are retained for later checks or restoration. RELOAD_MAY_RESTART defaults to false. The package uses systemctl, OpenRC or the existing nginx service control.
  • A rule changes only the selected server block. Native ACME is removed only when no other binding in that server block uses it. Ordinary external renewal and acme.sh saved installation paths with ordinary nginx reload use dedicated certificate files, so later source renewal does not overwrite the selected binding. Other servers, certificates and shared renewal timers remain unchanged; the package does not run hooks. During first takeover the agent coordinates concretely discovered acme.sh writers of the affected configuration file: new starts wait, existing challenges finish and the client resumes after the switch. This may briefly delay other lineages in the same installation. LOCAL_TLS_SNI distinguishes servers sharing a source certificate. The result supplies actual cert_path/key_path for subsequent checks.
  • Coordination uses Linux fanotify to hold new client starts without changing the client file. The concrete installation requires existing CAP_SYS_ADMIN and kernel support; fixed nginx sudo does not grant that capability. Missing capability causes a concrete failure before the switch, not a global root requirement. Ordinary renewal after takeover is preserved. Hidden privileged launchers and custom asynchronous hooks are not universally excluded. On interruption the kernel barrier releases waiting starts; the next agent invocation coordinates again before recovery. Client settings and upgrades are preserved.
  • Restoring the previously served certificate requires a readable matching certificate and key. Native ACME cache is used only when its leaf and key match the local observation. First native takeover refuses before configuration changes or reload with native_restore_material_unavailable when the working old certificate has no validated recoverable key pair, including state_path off or unusable cache. Preserve or export the old pair before retrying. A validated incoming pair matching the observed old certificate also suffices. Ordinary renewal after takeover is preserved. Older already switched journals can still report restore_material_unavailable; the journal cannot reconstruct a private key.
  • 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.

Get started