Apache, HAProxy and several certificates

The Linux agent finds your Apache sites and HAProxy frontends, you pick which get which certificate, and it writes the files and the HTTPS config for you.

Site placement

1. Add a Linux - Apache or Linux - HAProxy host and install the agent.
2. On its first check-in the agent reports every Apache site (virtual host) or HAProxy frontend it finds, with or without HTTPS. Until you pick one it says it's waiting for site placements.
3. Open the host's page. Under Site placement, tick the sites that should get a certificate, check the file paths it suggests, and save.
4. On its next check-in (within a minute by default, or run sudo neverlapse-agent run) the agent installs the certificate and reloads the web server.

Apache sites are read from /etc/apache2/sites-enabled, /etc/httpd/conf.d, /etc/apache2/conf.d and /etc/apache2/vhost.d; HAProxy from /etc/haproxy/haproxy.cfg. A site without a ServerName (a distribution's default site) is listed under a name taken from its file.

How config changes are made safely

• If a picked site has no HTTPS yet, the agent adds it: a :443 virtual host copied from the plain one for Apache (ServerName, aliases and DocumentRoot carried over), or a bind *:443 ssl crt ... line for HAProxy. Otherwise it points the existing HTTPS config at the new files.
• Before any change it saves a copy next to the file (<file>.neverlapse-bak-<time>).
• It then runs the server's own config test (apachectl configtest, httpd -t or haproxy -c). If the test fails, the original file is put back and the site keeps serving what it had.
• If the reload fails, the agent tries again on its next check-in.

HAProxy files

HAProxy wants one combined PEM file per certificate (certificate, chain and key, no passphrase). NeverLapse writes it that way. Don't set a private key passphrase on HAProxy hosts.

Several certificates on one server

Apache, HAProxy, IIS and General agent hosts can carry more than one certificate, for example a reverse proxy in front of several sites. A General host gets all of them, each in its own folder (see General below).

1. Certificate at the top of the host's page is its main certificate.
2. Under Additional certificates, tick every other certificate this server should get.
3. In Site placement (or IIS site bindings), each row has a Certificate dropdown: Main, any of your certificates, or for HAProxy All certificates. Picking a certificate on a row adds it to the host even if you didn't tick it above.
4. Save. The agent installs each one where it belongs on its next check-in.

HAProxy: one frontend, many domains

Set the frontend to All certificates (directory, SNI) and give it a folder ending in / (default /etc/haproxy/certs/). The agent writes one file per certificate, named after the domain (example.com.pem, wildcard.example.com.pem for *.example.com), and points the frontend at the folder:

bind *:443 ssl crt /etc/haproxy/certs/

HAProxy then answers each visitor with the certificate for the name they asked for. Adding a domain is just ticking another certificate on the host. Take one off and the agent deletes the file it wrote; files you put in that folder yourself are never touched.

Apache

Each site picks its certificate. Suggested file names follow the certificate (<target directory>/<domain>.crt, .key, .chain.crt). Two sites on the same certificate share its files; saving is refused if two sites would write different certificates to the same file.

IIS (agent)

Each binding picks its certificate. The agent imports all of the host's certificates and binds each to its own binding. For several HTTPS sites on one IP and port, give each binding its host name (SNI).

General (Linux or Windows)

Tick the extra certificates under Additional certificates. The main certificate is written to the target directory exactly as before. Each additional one goes into its own sub-folder of it, named after the certificate (wildcard.example.org for *.example.org), as the usual PEM files or a PFX named after the certificate:

C:\certs\cert.pfx                                         main certificate
C:\certs\shop.example.com\shop.example.com.pfx            additional certificate
C:\certs\wildcard.example.org\wildcard.example.org.pfx    additional certificate (*.example.org)

A custom script runs once per certificate, each time with that certificate's folder, PFX file and PFX password as its first three arguments. This needs NeverLapse Cert and its agents on 1.2.7 or later; older agents keep installing only the main certificate.

Linux - General

For anything that isn't Apache or HAProxy (or if you'd rather NeverLapse didn't touch their config): the certificate is written to a folder as PEM files or one PFX, nothing is reloaded, and a post-deploy script can do the rest. VMware Cloud Director cells have their own host type; see VMware Cloud Director cells.