Skip to content
Docs sslbrain sslbrain.com

HAProxy

Copy link to the page “HAProxy”

← All integrations

Linux · Load balancer

Finds HAProxy certificate bundles, validates the certificate and key, and checks activation locally.

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. 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.
  3. 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.
  4. 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 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. 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
Packages
haproxy-ssh 1.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.
  • 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 package 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 agent 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.

Get started