nginx

The Linux agent finds your nginx sites, you pick which get which certificate, and on every renewal it writes the files, points nginx at them, tests, reloads and checks the site, or puts everything back.

Setting it up

1. Add a Linux - nginx (agent, pull) host and pick its certificate. Target directory is optional: the folder for the certificate files (default /etc/nginx/ssl/neverlapse).
2. Save, reopen the host and install the agent on the nginx server with the install command at the top of the host's page. nginx needs the native agent: x86_64, systemd and glibc 2.27 or newer (RHEL/Rocky/Alma 8+, Ubuntu 18.04+, Debian 10+). The installer stops instead of falling back to the script agent.
3. After the agent's first check-in (about a minute), Site placement on the host's page lists every server block nginx loads, by its first server_name. A server without a name (a distro's default site) is listed as "Default Site". Uses now shows the certificate file a site has today.
4. Tick the sites, check the two file paths (full chain and key; suggested from the target directory and the certificate's name), pick the certificate per site if the host has several, and save. The next check-in applies it.

What happens on every new or renewed certificate

1. The agent reads the configuration the way nginx does, following every include. Debian/Ubuntu (sites-enabled) and RHEL-style (conf.d, servers in nginx.conf) layouts both work.
2. It backs up the certificate files and every config file it's about to change to /var/lib/neverlapse-pull/nginx-backup/ on the server (the last 10 are kept). Never next to the config, where include sites-enabled/* would load the copy.
3. It writes the full chain and the key. The key is mode 600, owned by root. It never writes over the file a server uses today; it writes its own files and points nginx at them.
4. It points each picked server's ssl_certificate and ssl_certificate_key at the new files, in the file that holds those lines (an included snippet too: then every server that includes that snippet gets the certificate). A server that has no lines of its own gets them added.
5. It runs nginx -t and, only if that passes, reloads nginx (a reload, not a restart).
6. It connects to each site on its own address and port, with its name, and checks it serves the new certificate.

If the test, the reload or the check fails, the agent puts every backed-up file back, reloads nginx, and shows the error under Agent status on the host's page. It tries that certificate again after 15 minutes; sudo neverlapse-agent run --force on the server tries right away.

A site without HTTPS yet

If a picked site only has a plain HTTP server, the agent adds an HTTPS server right after it, in the same file: listen 443 ssl on the same addresses, plus the plain server's server_name, root, index, location blocks and includes, and the two certificate lines. It leaves out return, rewrite and if (a "redirect to https" would loop forever) and default_server. Look over the new server once afterwards; later renewals only change the two certificate paths.

Good to know

• Several certificates: one nginx server can carry several; each site picks its own (see several certificates).
• Not managed: a server whose ssl_certificate uses a variable such as $ssl_server_name. A server with two certificate pairs (RSA + ECDSA) only gets its first pair changed, so the check may fail and roll back: remove the second pair first.
• No key passphrase for nginx hosts: nginx can't reload with an encrypted key unless ssl_password_file is set up.
• Wildcard names: for server_name *.example.com the check asks for neverlapse-check.example.com.
• Where to look: sudo neverlapse-agent discover lists the servers the agent sees, sudo neverlapse-agent run checks in now, the log is /var/log/neverlapse-agent.log.