Finds HAProxy certificate bundles, validates the certificate and key, and checks activation locally.
What happens
- The service agent on the server fetches the task from the appliance over outbound HTTPS, port 443.
- Discovery finds concrete PEM files from crt, certificate directories and crt-list, including RSA/ECDSA slots. On appliance 0.4.44, confirm CERT_PATH, CONFIG_PATH and SERVICE_NAME manually when there are multiple bindings. Unreadable configurations and multiple config files produce a partial result.
- The certificate and key are checked before hashing. The combined PEM file is staged privately and config-tested before atomic replacement; a journal retains state for retry and restore.
- Only the selected service is reloaded. Local TLS checks compare the served certificate before and after, using the binding’s port, SNI and key algorithm. If it fails: Restore is used only when a previously working local service is now broken. The old target certificate still being served produces a failure without service restore. If configtest rejects the file after replacement, the previous disk file is recovered without reload; operator edits are preserved and failures are reported separately.
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. Read access to the configuration and write access to a dedicated certificate directory. The deploy account must not be able to change the configuration, Lua files or other content executed during configtest/reload. With sudo: sudo -n for the exact haproxy -c -f command with the selected original configuration and reload of the selected service.
- Actions
- Discovery, Installation, Verification, Rollback
- Integrations
-
haproxy-ssh1.4.1 - Note
-
- Discovery reads the configuration the running HAProxy was started with (the process's -f, else the systemd unit), and only then /etc/haproxy/haproxy.cfg. Deploy also accepts a PEM file outside the standard folders when a bind line in the live configuration points at it. ACME is the protocol a CA uses to issue certificates automatically.
- An already active certificate needs no certificate switch; targeted takeover is still checked. Unproven activation produces a warning. Local identity checks do not prove public trust, external reachability or activation on other HA nodes.
- Generated test configurations run without sudo. Unreadable unrelated keys are reported as a limitation; the fixed original configuration is still tested before reload. A broad sudo grant for temporary configurations is unnecessary.
- The integration replaces before it disables: our certificate is written, HAProxy is reloaded and the local check must see the new certificate; only then is a proven ACME client writer of the selected bundle switched off. An isolated ACME client hook (directory deploy, pre or post hook) loses only its copy; the existing reload of the selected service is retained. When the copy is one hook line (renew_hook, pre_hook or post_hook) in the renewal configuration of one lineage and the line does nothing but copy, chmod/chown the target and reload the selected service, the file is backed up and exactly that line is commented out. Other lineages, the renewal timer of the ACME client and other services are untouched; the reconfigure command of the client, test renewals and hook execution are not used. A private receipt and backup report the change, and if the deployment fails, its rollback puts the backup back; a completed handover stays. The SSH account must be able to write the file without extra sudo. A proven writer that cannot be bounded this way (for example in cli.ini, in an sh -c string, in a script a hook starts, or in a line that also does other work) stops the deployment before switching with a precise explanation. The same applies to native HAProxy ACME and acme.sh installation to the target. Conditional or unreadable hook text, hooks of a lineage with autorenew off and references are reported but do not stop a deployment and do not prove exclusive management.
- New probe fields are optional. Existing raw PEM input on appliance 0.4.44 is preserved; binary-aware runners and explicit base64 fields are supported. Custom reload commands are not accepted.
- Alpine/musl and systems with BusyBox support the selected certificate paths. Bash 4+, OpenSSL 1.1.1+, GNU coreutils 8.24+ and util-linux flock are still required; install them on Alpine alongside BusyBox. Deployment supports one config file; directory/multi-file configs and crt-store aliases remain partial discovery results. The integration only requests reload: systemctl reload does not start a stopped service; other init scripts may behave differently. Manual rollback is conditional and does not revert an active new certificate.
- haproxy-ssh 2.0.0 is the next version, built for sslbrain v4 and released with it; until then the appliance installs 1.4.1 as described above. 2.0.0 runs the same script through the service agent on the server or over SSH. Over SSH it needs root or an account that may run sudo -n bash without a password, because the whole action runs as root. It reads every configuration file the running HAProxy was started with and keeps the inputs, the config test, the reload, the local check and the rollback. Taking a bundle over from the ACME client on the server turns its renewal off for exactly the lineage whose certificate is in the bundle (autorenew = False in its renewal file); the lineage, its files and hooks are kept, and rollback turns renewal back on.