<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/"><channel><title>Let's Encrypt | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/letsencrypt/</link><description>Hands-on DevOps and homelab content: Kubernetes clusters, self-hosted services, CI/CD pipelines and infrastructure as code, by Patrick de Ruiter of We Build Your Cloud.</description><language>en</language><image><url>https://blog.bsdserver.nl/images/app-icon.svg</url><title>A DevOps Blog</title><link>https://blog.bsdserver.nl/</link></image><lastBuildDate>Wed, 18 Nov 2026 09:00:00 +0100</lastBuildDate><atom:link href="https://blog.bsdserver.nl/tag/letsencrypt/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title>HAProxy with Let's Encrypt: Automated HTTPS Certificate Management</title><link>https://blog.bsdserver.nl/haproxy-with-lets-encrypt-automated-https-certificate-management/</link><guid isPermaLink="false">693b734379eb54000160a5f2</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:43:31 +0000</pubDate><description>HTTPS is no longer optional - it's a requirement for modern web applications.</description><category>HAProxy</category><category>Let's Encrypt</category><category>HTTPS</category><category>TLS</category><category>Certificates</category><category>Security</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/haproxy-letsencrypt-certificates.png" medium="image"/><content:encoded><![CDATA[<p>HTTPS is no longer optional - it&rsquo;s a requirement for modern web applications. Let&rsquo;s Encrypt certificates are free but expire after 90 days, so renewing and installing them by hand does not scale.</p>
<p>This guide connects HAProxy to certbot: HAProxy terminates TLS and routes the ACME challenge, certbot obtains and renews the certificates, and a deploy hook loads renewed certificates into HAProxy, without a restart where possible.</p>
<h2 id="why-lets-encrypt-with-haproxy">Why Let&rsquo;s Encrypt with HAProxy? <a class="anchor" data-pagefind-ignore href="#why-lets-encrypt-with-haproxy" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Free, trusted certificates</strong> for every domain behind the load balancer</li>
<li><strong>One place for TLS</strong>: backends speak plain HTTP, certificates live only on HAProxy</li>
<li><strong>Automatic renewal</strong> with a systemd timer or cron</li>
<li><strong>No downtime</strong>: the runtime API swaps certificates in a running HAProxy</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> for public sites where HAProxy is the TLS endpoint and is reachable from the internet (HTTP-01) or your DNS has an API (DNS-01).</li>
<li><strong>Skip it</strong> for internal services without public DNS (use an internal CA), or when backends must terminate TLS themselves (TLS passthrough).</li>
</ul>
<h2 id="architecture-overview">Architecture Overview <a class="anchor" data-pagefind-ignore href="#architecture-overview" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>HAProxy</td>
					<td>Load balancer</td>
					<td>Terminates TLS with the PEM files in <code>/etc/haproxy/certs/</code>; sends <code>/.well-known/acme-challenge/</code> on port 80 to the challenge server.</td>
			</tr>
			<tr>
					<td>Challenge server</td>
					<td>Load balancer, <code>127.0.0.1:8080</code> (8888 in Method 1)</td>
					<td>Serves the webroot where certbot writes challenge files.</td>
			</tr>
			<tr>
					<td>Certbot</td>
					<td>Load balancer</td>
					<td>Requests and renews certificates in <code>/etc/letsencrypt/live/&lt;name&gt;/</code>.</td>
			</tr>
			<tr>
					<td>Deploy hook</td>
					<td>Load balancer</td>
					<td>Combines <code>fullchain.pem</code> and <code>privkey.pem</code>, loads the result into HAProxy.</td>
			</tr>
	</tbody>
</table>
<p>The flow: certbot writes a challenge file → Let&rsquo;s Encrypt fetches it over HTTP → HAProxy routes it to the challenge server → certificate issued → deploy hook builds the PEM → runtime API updates HAProxy.</p>
<h3 id="choosing-a-method">Choosing a method <a class="anchor" data-pagefind-ignore href="#choosing-a-method" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Method</th>
					<th>HAProxy downtime</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>1. HTTP-01 webroot</td>
					<td>None</td>
					<td>The basic setup behind HAProxy</td>
			</tr>
			<tr>
					<td>2. Standalone with hooks</td>
					<td>Seconds per renewal</td>
					<td>Simple setups where a short stop is acceptable</td>
			</tr>
			<tr>
					<td>3. Runtime API</td>
					<td>None, no reload</td>
					<td>Production (recommended)</td>
			</tr>
			<tr>
					<td>4. DNS-01</td>
					<td>None</td>
					<td>Wildcard certificates, servers not reachable on port 80</td>
			</tr>
	</tbody>
</table>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<ul>
<li>HAProxy from the official packages (examples checked on 3.4 LTS and on 3.3, the newest branch for Ubuntu 24.04)</li>
<li>Certbot installed</li>
<li>Domain(s) pointing to your HAProxy server</li>
<li>Port 80 and 443 accessible from the internet</li>
</ul>
<h2 id="installation">Installation <a class="anchor" data-pagefind-ignore href="#installation" aria-label="Link to this section">#</a></h2>
<h3 id="install-haproxy">Install HAProxy <a class="anchor" data-pagefind-ignore href="#install-haproxy" aria-label="Link to this section">#</a></h3>
<p>The runtime certificate API used in Method 3 needs HAProxy 2.4 or later. Use the official packages from <a href="https://haproxy.debian.net" rel="noopener">haproxy.debian.net</a> rather than the distribution package:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Ubuntu 24.04: official PPA. 3.3 is the newest branch built for 24.04; it is a</span>
</span></span><span class="line"><span class="cl"><span class="c1"># short-lived, non-LTS branch. HAProxy 3.4 LTS is available for Ubuntu 26.04</span>
</span></span><span class="line"><span class="cl"><span class="c1"># (ppa:vbernat/haproxy-3.4) and for Debian 13 (below).</span>
</span></span><span class="line"><span class="cl">apt update
</span></span><span class="line"><span class="cl">apt install --no-install-recommends software-properties-common
</span></span><span class="line"><span class="cl">add-apt-repository ppa:vbernat/haproxy-3.3
</span></span><span class="line"><span class="cl">apt install <span class="nv">haproxy</span><span class="o">=</span>3.3.<span class="se">\*</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Debian 13: official haproxy.debian.net repository (3.4 LTS)</span>
</span></span><span class="line"><span class="cl">curl https://haproxy.debian.net/haproxy-archive-keyring.gpg <span class="se">\
</span></span></span><span class="line"><span class="cl">  --create-dirs --output /etc/apt/keyrings/haproxy-archive-keyring.gpg
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> deb <span class="s2">&#34;[signed-by=/etc/apt/keyrings/haproxy-archive-keyring.gpg]&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://haproxy.debian.net trixie-backports-3.4 main <span class="se">\
</span></span></span><span class="line"><span class="cl">  &gt; /etc/apt/sources.list.d/haproxy.list
</span></span><span class="line"><span class="cl">apt update
</span></span><span class="line"><span class="cl">apt install <span class="nv">haproxy</span><span class="o">=</span>3.4.<span class="se">\*</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># RHEL/CentOS (no official repository: AppStream ships 2.8)</span>
</span></span><span class="line"><span class="cl">yum install haproxy
</span></span><span class="line"><span class="cl"><span class="c1"># RHEL only: the unit does not create /run/haproxy, which the admin socket below needs</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/systemd/system/haproxy.service.d
</span></span><span class="line"><span class="cl"><span class="nb">printf</span> <span class="s1">&#39;[Service]\nRuntimeDirectory=haproxy\n&#39;</span> &gt; /etc/systemd/system/haproxy.service.d/runtime-directory.conf
</span></span><span class="line"><span class="cl">systemctl daemon-reload
</span></span></code></pre></div><h3 id="install-certbot">Install Certbot <a class="anchor" data-pagefind-ignore href="#install-certbot" aria-label="Link to this section">#</a></h3>
<p>Certbot is the Let&rsquo;s Encrypt client. Pick one source; the snap gets updates first.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Debian/Ubuntu</span>
</span></span><span class="line"><span class="cl">apt install certbot
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># RHEL/CentOS (certbot comes from EPEL)</span>
</span></span><span class="line"><span class="cl">yum install epel-release
</span></span><span class="line"><span class="cl">yum install certbot
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or using snap (recommended by Let&#39;s Encrypt)</span>
</span></span><span class="line"><span class="cl">snap install --classic certbot
</span></span><span class="line"><span class="cl">ln -s /snap/bin/certbot /usr/bin/certbot
</span></span></code></pre></div><h2 id="haproxy-certificate-format">HAProxy Certificate Format <a class="anchor" data-pagefind-ignore href="#haproxy-certificate-format" aria-label="Link to this section">#</a></h2>
<p>HAProxy requires certificates in a specific format: the certificate chain and private key combined in a single PEM file.</p>
<pre tabindex="0"><code>-----BEGIN CERTIFICATE-----
[Your domain certificate]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Intermediate certificate]
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
[Private key]
-----END PRIVATE KEY-----
</code></pre><p>Let&rsquo;s Encrypt provides separate files (<code>fullchain.pem</code>, <code>privkey.pem</code>), so every method below combines them. Repeat this after each renewal, or HAProxy keeps serving the old certificate.</p>
<h2 id="method-1-http-01-challenge-with-haproxy">Method 1: HTTP-01 Challenge with HAProxy <a class="anchor" data-pagefind-ignore href="#method-1-http-01-challenge-with-haproxy" aria-label="Link to this section">#</a></h2>
<p>Let&rsquo;s Encrypt checks that you control a domain by fetching a token from <code>http://&lt;domain&gt;/.well-known/acme-challenge/</code> on port 80. HAProxy already owns port 80, so it routes that path to a small local web server and redirects everything else to HTTPS.</p>
<h3 id="haproxy-configuration">HAProxy Configuration <a class="anchor" data-pagefind-ignore href="#haproxy-configuration" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>acl is_acme_challenge</code>: matches the challenge path; <code>use_backend</code> sends it to <code>127.0.0.1:8888</code>.</li>
<li><code>redirect scheme https unless is_acme_challenge</code>: all other HTTP goes to HTTPS. The challenge must stay on HTTP.</li>
<li><code>crt /etc/haproxy/certs/</code>: loads every PEM in the directory; HAProxy picks one by SNI.</li>
<li><code>Strict-Transport-Security</code>: tells browsers to use HTTPS only. <code>preload</code> and <code>includeSubDomains</code> are hard to undo, so add them only when every subdomain has HTTPS.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy"># /etc/haproxy/haproxy.cfg

global
    log /dev/log local0
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin
    user haproxy
    group haproxy
    daemon
    
    # SSL/TLS settings
    ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
    ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
    ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets
    tune.ssl.default-dh-param 2048

defaults
    log global
    mode http
    option httplog
    option dontlognull
    timeout connect 5s
    timeout client  50s
    timeout server  50s

# HTTP Frontend - handles Let&#39;s Encrypt challenges and redirects
frontend http_frontend
    bind *:80
    
    # Let&#39;s Encrypt ACME challenge
    acl is_acme_challenge path_beg /.well-known/acme-challenge/
    use_backend letsencrypt_backend if is_acme_challenge
    
    # Redirect all other HTTP to HTTPS
    http-request redirect scheme https unless is_acme_challenge

# HTTPS Frontend
frontend https_frontend
    bind *:443 ssl crt /etc/haproxy/certs/ alpn h2,http/1.1
    
    # HSTS header
    http-response set-header Strict-Transport-Security &#34;max-age=31536000; includeSubDomains; preload&#34;
    
    # Default backend
    default_backend web_servers

# Backend for Let&#39;s Encrypt challenges
backend letsencrypt_backend
    server certbot 127.0.0.1:8888

# Your web servers
backend web_servers
    balance roundrobin
    server web1 192.168.1.10:8080 check
    server web2 192.168.1.11:8080 check
</code></pre><h3 id="initial-certificate-request">Initial Certificate Request <a class="anchor" data-pagefind-ignore href="#initial-certificate-request" aria-label="Link to this section">#</a></h3>
<p>HAProxy does not start with an empty certificate directory, so the first certificate comes from certbot&rsquo;s standalone mode: certbot runs its own web server on port 80 while HAProxy is stopped.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Stop HAProxy temporarily</span>
</span></span><span class="line"><span class="cl">systemctl stop haproxy
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Get initial certificate</span>
</span></span><span class="line"><span class="cl">certbot certonly --standalone <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d www.example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  --email admin@example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  --agree-tos <span class="se">\
</span></span></span><span class="line"><span class="cl">  --non-interactive
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Combine certificate files for HAProxy</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/haproxy/certs
</span></span><span class="line"><span class="cl"><span class="nv">BASE_DIR</span><span class="o">=</span>/etc/letsencrypt/live/example.com
</span></span><span class="line"><span class="cl">cat <span class="nv">$BASE_DIR</span>/fullchain.pem <span class="nv">$BASE_DIR</span>/privkey.pem &gt; /etc/haproxy/certs/example.com.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">600</span> /etc/haproxy/certs/example.com.pem
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Start HAProxy</span>
</span></span><span class="line"><span class="cl">systemctl start haproxy
</span></span></code></pre></div><h3 id="renewal-with-http-01-challenge">Renewal with HTTP-01 Challenge <a class="anchor" data-pagefind-ignore href="#renewal-with-http-01-challenge" aria-label="Link to this section">#</a></h3>
<p>Once HAProxy is running, use webroot mode for renewals: certbot writes the token into a directory, and a web server on port 8888 serves it to HAProxy&rsquo;s ACME backend.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Create directory for challenges</span>
</span></span><span class="line"><span class="cl">mkdir -p /var/www/letsencrypt/.well-known/acme-challenge
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Use a simple HTTP server for challenges</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Option 1: Python</span>
</span></span><span class="line"><span class="cl"><span class="nb">cd</span> /var/www/letsencrypt <span class="o">&amp;&amp;</span> python3 -m http.server <span class="m">8888</span> <span class="p">&amp;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Option 2: socat (install socat package)</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Create a script to serve files</span>
</span></span></code></pre></div><p>Then point certbot at the webroot. Method 3 replaces the background Python process with a systemd service.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># For a certificate that already exists, add --force-renewal (otherwise certbot asks interactively)</span>
</span></span><span class="line"><span class="cl">certbot certonly --webroot <span class="se">\
</span></span></span><span class="line"><span class="cl">  -w /var/www/letsencrypt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d www.example.com
</span></span></code></pre></div><h2 id="method-2-using-certbot-standalone-with-haproxy">Method 2: Using Certbot Standalone with HAProxy <a class="anchor" data-pagefind-ignore href="#method-2-using-certbot-standalone-with-haproxy" aria-label="Link to this section">#</a></h2>
<p>This method temporarily stops HAProxy during renewal, so certbot&rsquo;s standalone server can use port 80. Simple, but the site is down for a few seconds per renewal.</p>
<h3 id="pre-and-post-hooks">Pre and Post Hooks <a class="anchor" data-pagefind-ignore href="#pre-and-post-hooks" aria-label="Link to this section">#</a></h3>
<p>Certbot runs <code>pre-hook</code> before and <code>post-hook</code> after each renewal attempt.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># /etc/letsencrypt/cli.ini</span>
</span></span><span class="line"><span class="cl"><span class="c1"># cli.ini has no sections: these hooks apply to every certbot run.</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Only use this for certificates obtained with --standalone; webroot</span>
</span></span><span class="line"><span class="cl"><span class="c1"># renewals fail while HAProxy is stopped.</span>
</span></span><span class="line"><span class="cl">pre-hook <span class="o">=</span> systemctl stop haproxy
</span></span><span class="line"><span class="cl">post-hook <span class="o">=</span> /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh
</span></span></code></pre></div><h3 id="deployment-script">Deployment Script <a class="anchor" data-pagefind-ignore href="#deployment-script" aria-label="Link to this section">#</a></h3>
<p>Combines the renewed files for each domain and brings HAProxy back. <code>RENEWED_DOMAINS</code> is set by certbot.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_CERT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/certs&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Process each renewed domain</span>
</span></span><span class="line"><span class="cl"><span class="k">for</span> domain in <span class="nv">$RENEWED_DOMAINS</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Find the certificate directory</span>
</span></span><span class="line"><span class="cl">    <span class="nv">CERT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/letsencrypt/live/</span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="o">[</span> -d <span class="s2">&#34;</span><span class="nv">$CERT_DIR</span><span class="s2">&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># Combine cert and key for HAProxy</span>
</span></span><span class="line"><span class="cl">        cat <span class="s2">&#34;</span><span class="nv">$CERT_DIR</span><span class="s2">/fullchain.pem&#34;</span> <span class="s2">&#34;</span><span class="nv">$CERT_DIR</span><span class="s2">/privkey.pem&#34;</span> &gt; <span class="s2">&#34;</span><span class="nv">$HAPROXY_CERT_DIR</span><span class="s2">/</span><span class="nv">$domain</span><span class="s2">.pem&#34;</span>
</span></span><span class="line"><span class="cl">        chmod <span class="m">600</span> <span class="s2">&#34;</span><span class="nv">$HAPROXY_CERT_DIR</span><span class="s2">/</span><span class="nv">$domain</span><span class="s2">.pem&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="nb">echo</span> <span class="s2">&#34;Updated certificate for </span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">fi</span>
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload HAProxy</span>
</span></span><span class="line"><span class="cl">systemctl reload haproxy <span class="o">||</span> systemctl start haproxy
</span></span></code></pre></div><p>Make it executable:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">chmod +x /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh
</span></span></code></pre></div><h2 id="method-3-zero-downtime-renewal-recommended">Method 3: Zero-Downtime Renewal (Recommended) <a class="anchor" data-pagefind-ignore href="#method-3-zero-downtime-renewal-recommended" aria-label="Link to this section">#</a></h2>
<p>This approach uses HAProxy&rsquo;s runtime API to reload certificates without restart or reload. Existing connections are untouched.</p>
<h3 id="haproxy-configuration-1">HAProxy Configuration <a class="anchor" data-pagefind-ignore href="#haproxy-configuration-1" aria-label="Link to this section">#</a></h3>
<p>Changes from Method 1:</p>
<ul>
<li><code>expose-fd listeners</code> on the stats socket: allows seamless reloads for the fallback path.</li>
<li><code>strict-sni</code>: refuse TLS handshakes for names without a certificate instead of serving a wrong one.</li>
<li>The ACME backend moves to <code>127.0.0.1:8080</code>.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy"># /etc/haproxy/haproxy.cfg

global
    log /dev/log local0
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
    stats timeout 30s
    user haproxy
    group haproxy
    daemon
    
    # Enable runtime API for certificate management
    ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
    ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
    ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets

defaults
    log global
    mode http
    option httplog
    timeout connect 5s
    timeout client  50s
    timeout server  50s

# HTTP Frontend
frontend http_frontend
    bind *:80
    
    # ACME challenge path
    acl is_acme path_beg /.well-known/acme-challenge/
    use_backend acme_backend if is_acme
    
    # Redirect to HTTPS
    http-request redirect scheme https code 301 unless is_acme

# HTTPS Frontend
frontend https_frontend
    bind *:443 ssl crt /etc/haproxy/certs/ strict-sni alpn h2,http/1.1
    
    http-response set-header Strict-Transport-Security &#34;max-age=63072000&#34;
    
    default_backend web_servers

# ACME challenge backend
backend acme_backend
    server acme 127.0.0.1:8080

backend web_servers
    balance roundrobin
    option httpchk GET /health
    server web1 192.168.1.10:8080 check
    server web2 192.168.1.11:8080 check
</code></pre><h3 id="zero-downtime-certificate-update-script">Zero-Downtime Certificate Update Script <a class="anchor" data-pagefind-ignore href="#zero-downtime-certificate-update-script" aria-label="Link to this section">#</a></h3>
<p>For a certificate HAProxy already has loaded, the script swaps it in memory with <code>set ssl cert</code> and <code>commit ssl cert</code>. A new certificate is not known to the running process yet, so it falls back to a reload.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/haproxy-cert-update.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_CERT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/certs&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_SOCKET</span><span class="o">=</span><span class="s2">&#34;/run/haproxy/admin.sock&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">update_certificate<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">    <span class="nb">local</span> <span class="nv">domain</span><span class="o">=</span><span class="nv">$1</span>
</span></span><span class="line"><span class="cl">    <span class="nb">local</span> <span class="nv">cert_dir</span><span class="o">=</span><span class="s2">&#34;/etc/letsencrypt/live/</span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">local</span> <span class="nv">combined_cert</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$HAPROXY_CERT_DIR</span><span class="s2">/</span><span class="nv">$domain</span><span class="s2">.pem&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Combine certificates</span>
</span></span><span class="line"><span class="cl">    cat <span class="s2">&#34;</span><span class="nv">$cert_dir</span><span class="s2">/fullchain.pem&#34;</span> <span class="s2">&#34;</span><span class="nv">$cert_dir</span><span class="s2">/privkey.pem&#34;</span> &gt; <span class="s2">&#34;</span><span class="nv">$combined_cert</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    chmod <span class="m">600</span> <span class="s2">&#34;</span><span class="nv">$combined_cert</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Check if HAProxy is running with this certificate</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="nb">echo</span> <span class="s2">&#34;show ssl cert&#34;</span> <span class="p">|</span> socat stdio <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span> <span class="p">|</span> grep -q <span class="s2">&#34;</span><span class="nv">$combined_cert</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># Update certificate in running HAProxy: the payload must be sent in the</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># same session as &#34;set ssl cert&#34;, the commit in a second session</span>
</span></span><span class="line"><span class="cl">        <span class="o">{</span> <span class="nb">echo</span> <span class="s2">&#34;set ssl cert </span><span class="nv">$combined_cert</span><span class="s2"> &lt;&lt;&#34;</span><span class="p">;</span> cat <span class="s2">&#34;</span><span class="nv">$combined_cert</span><span class="s2">&#34;</span><span class="p">;</span> <span class="nb">echo</span> <span class="s2">&#34;&#34;</span><span class="p">;</span> <span class="o">}</span> <span class="p">|</span> socat stdio <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="nb">echo</span> <span class="s2">&#34;commit ssl cert </span><span class="nv">$combined_cert</span><span class="s2">&#34;</span> <span class="p">|</span> socat stdio <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="nb">echo</span> <span class="s2">&#34;Certificate for </span><span class="nv">$domain</span><span class="s2"> updated in-place&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">else</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># Certificate not yet loaded, reload HAProxy</span>
</span></span><span class="line"><span class="cl">        systemctl reload haproxy
</span></span><span class="line"><span class="cl">        <span class="nb">echo</span> <span class="s2">&#34;HAProxy reloaded for new certificate </span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">fi</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Process the renewed certificate (certbot sets RENEWED_LINEAGE to its live directory)</span>
</span></span><span class="line"><span class="cl">update_certificate <span class="s2">&#34;</span><span class="k">$(</span>basename <span class="s2">&#34;</span><span class="nv">$RENEWED_LINEAGE</span><span class="s2">&#34;</span><span class="k">)</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h3 id="haproxy-24-runtime-certificate-api">HAProxy 2.4+ Runtime Certificate API <a class="anchor" data-pagefind-ignore href="#haproxy-24-runtime-certificate-api" aria-label="Link to this section">#</a></h3>
<p>The same commands by hand, to inspect or update a certificate. The update only changes memory; the file on disk is what HAProxy loads at the next start.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># List certificates</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show ssl cert&#34;</span> <span class="p">|</span> socat stdio /run/haproxy/admin.sock
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Show certificate details</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show ssl cert /etc/haproxy/certs/example.com.pem&#34;</span> <span class="p">|</span> socat stdio /run/haproxy/admin.sock
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Update certificate in-place (HAProxy 2.4+): payload in the same session, then commit</span>
</span></span><span class="line"><span class="cl"><span class="o">{</span> <span class="nb">echo</span> <span class="s2">&#34;set ssl cert /etc/haproxy/certs/example.com.pem &lt;&lt;&#34;</span><span class="p">;</span> cat /etc/haproxy/certs/example.com.pem<span class="p">;</span> <span class="nb">echo</span> <span class="s2">&#34;&#34;</span><span class="p">;</span> <span class="o">}</span> <span class="p">|</span> socat stdio /run/haproxy/admin.sock
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;commit ssl cert /etc/haproxy/certs/example.com.pem&#34;</span> <span class="p">|</span> socat stdio /run/haproxy/admin.sock
</span></span></code></pre></div><h2 id="method-4-dns-01-challenge-wildcard-certificates">Method 4: DNS-01 Challenge (Wildcard Certificates) <a class="anchor" data-pagefind-ignore href="#method-4-dns-01-challenge-wildcard-certificates" aria-label="Link to this section">#</a></h2>
<p>For wildcard certificates or when HTTP challenges aren&rsquo;t possible. Certbot proves control by creating a TXT record through your DNS provider&rsquo;s API; port 80 is not involved.</p>
<h3 id="with-cloudflare-dns">With Cloudflare DNS <a class="anchor" data-pagefind-ignore href="#with-cloudflare-dns" aria-label="Link to this section">#</a></h3>
<p>Use an API token limited to editing DNS for the zone, not your global API key.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Install Cloudflare DNS plugin</span>
</span></span><span class="line"><span class="cl">apt install python3-certbot-dns-cloudflare
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or, if certbot itself was installed with pip in /opt/certbot</span>
</span></span><span class="line"><span class="cl"><span class="c1"># (Ubuntu 24.04 and Debian 12 refuse a system-wide pip install)</span>
</span></span><span class="line"><span class="cl">/opt/certbot/bin/pip install certbot-dns-cloudflare
</span></span></code></pre></div><p>Create credentials file (readable by root only):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="c1"># /etc/letsencrypt/cloudflare.ini</span>
</span></span><span class="line"><span class="cl"><span class="na">dns_cloudflare_api_token</span> <span class="o">=</span> <span class="s">your-api-token-here</span>
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">chmod <span class="m">600</span> /etc/letsencrypt/cloudflare.ini
</span></span></code></pre></div><p>Request wildcard certificate:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">certbot certonly <span class="se">\
</span></span></span><span class="line"><span class="cl">  --dns-cloudflare <span class="se">\
</span></span></span><span class="line"><span class="cl">  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;*.example.com&#39;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  --email admin@example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  --agree-tos
</span></span></code></pre></div><h3 id="with-route53">With Route53 <a class="anchor" data-pagefind-ignore href="#with-route53" aria-label="Link to this section">#</a></h3>
<p>The plugin uses standard AWS credentials; an IAM role or <code>~/.aws/credentials</code> is better than exported keys.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">apt install python3-certbot-dns-route53
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Configure AWS credentials</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_ACCESS_KEY_ID</span><span class="o">=</span>your-key
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_SECRET_ACCESS_KEY</span><span class="o">=</span>your-secret
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">certbot certonly <span class="se">\
</span></span></span><span class="line"><span class="cl">  --dns-route53 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;*.example.com&#39;</span>
</span></span></code></pre></div><h2 id="automated-renewal-setup">Automated Renewal Setup <a class="anchor" data-pagefind-ignore href="#automated-renewal-setup" aria-label="Link to this section">#</a></h2>
<p>Certbot only renews certificates that are close to expiry, so running it twice a day is cheap. The <code>--deploy-hook</code> runs only when a certificate was actually renewed.</p>
<table>
	<thead>
			<tr>
					<th>Option</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Systemd timer</td>
					<td>Most systems; <code>Persistent=true</code> catches up on missed runs</td>
			</tr>
			<tr>
					<td>Cron</td>
					<td>Systems without systemd</td>
			</tr>
	</tbody>
</table>
<p>Packaged certbot often ships its own timer (<code>certbot.timer</code>) or cron entry. Use one scheduler, not both.</p>
<h3 id="systemd-timer">Systemd Timer <a class="anchor" data-pagefind-ignore href="#systemd-timer" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="c1"># /etc/systemd/system/certbot-renewal.service</span>
</span></span><span class="line"><span class="cl"><span class="k">[Unit]</span>
</span></span><span class="line"><span class="cl"><span class="na">Description</span><span class="o">=</span><span class="s">Certbot Renewal</span>
</span></span><span class="line"><span class="cl"><span class="na">After</span><span class="o">=</span><span class="s">network-online.target</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Service]</span>
</span></span><span class="line"><span class="cl"><span class="na">Type</span><span class="o">=</span><span class="s">oneshot</span>
</span></span><span class="line"><span class="cl"><span class="na">ExecStart</span><span class="o">=</span><span class="s">/usr/bin/certbot renew --deploy-hook /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh</span>
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="c1"># /etc/systemd/system/certbot-renewal.timer</span>
</span></span><span class="line"><span class="cl"><span class="k">[Unit]</span>
</span></span><span class="line"><span class="cl"><span class="na">Description</span><span class="o">=</span><span class="s">Run certbot renewal twice daily</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Timer]</span>
</span></span><span class="line"><span class="cl"><span class="na">OnCalendar</span><span class="o">=</span><span class="s">*-*-* 00,12:00:00</span>
</span></span><span class="line"><span class="cl"><span class="na">RandomizedDelaySec</span><span class="o">=</span><span class="s">43200</span>
</span></span><span class="line"><span class="cl"><span class="na">Persistent</span><span class="o">=</span><span class="s">true</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Install]</span>
</span></span><span class="line"><span class="cl"><span class="na">WantedBy</span><span class="o">=</span><span class="s">timers.target</span>
</span></span></code></pre></div><p>Enable the timer:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">systemctl daemon-reload
</span></span><span class="line"><span class="cl">systemctl <span class="nb">enable</span> certbot-renewal.timer
</span></span><span class="line"><span class="cl">systemctl start certbot-renewal.timer
</span></span></code></pre></div><h3 id="cron-job-alternative">Cron Job Alternative <a class="anchor" data-pagefind-ignore href="#cron-job-alternative" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># /etc/cron.d/certbot</span>
</span></span><span class="line"><span class="cl"><span class="m">0</span> 0,12 * * * root certbot renew --deploy-hook /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh
</span></span></code></pre></div><h2 id="multi-domain-configuration">Multi-Domain Configuration <a class="anchor" data-pagefind-ignore href="#multi-domain-configuration" aria-label="Link to this section">#</a></h2>
<p>One HAProxy can serve many domains, each with its own certificate.</p>
<h3 id="separate-certificates-per-domain">Separate Certificates per Domain <a class="anchor" data-pagefind-ignore href="#separate-certificates-per-domain" aria-label="Link to this section">#</a></h3>
<p>List each PEM on the bind line and route on the SNI name.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend https_frontend
    bind *:443 ssl crt /etc/haproxy/certs/example.com.pem crt /etc/haproxy/certs/example.org.pem
    
    # Route based on SNI
    use_backend example_com_servers if { ssl_fc_sni example.com }
    use_backend example_org_servers if { ssl_fc_sni example.org }
</code></pre><h3 id="certificate-directory">Certificate Directory <a class="anchor" data-pagefind-ignore href="#certificate-directory" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend https_frontend
    # Load all .pem files from directory
    bind *:443 ssl crt /etc/haproxy/certs/
</code></pre><p>HAProxy automatically matches certificates based on SNI. New files are picked up at the next reload.</p>
<h3 id="request-multiple-certificates">Request Multiple Certificates <a class="anchor" data-pagefind-ignore href="#request-multiple-certificates" aria-label="Link to this section">#</a></h3>
<p>Each line in <code>DOMAINS</code> becomes one certificate; the first name is the certificate name and the file name in <code>/etc/letsencrypt/live/</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/request-certs.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">DOMAINS</span><span class="o">=(</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;example.com www.example.com&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;api.example.com&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;app.example.com&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">for</span> domain_set in <span class="s2">&#34;</span><span class="si">${</span><span class="nv">DOMAINS</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    <span class="nv">primary</span><span class="o">=</span><span class="k">$(</span><span class="nb">echo</span> <span class="nv">$domain_set</span> <span class="p">|</span> awk <span class="s1">&#39;{print $1}&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    certbot certonly <span class="se">\
</span></span></span><span class="line"><span class="cl">        --webroot <span class="se">\
</span></span></span><span class="line"><span class="cl">        -w /var/www/letsencrypt <span class="se">\
</span></span></span><span class="line"><span class="cl">        <span class="k">$(for</span> d in <span class="nv">$domain_set</span><span class="p">;</span> <span class="k">do</span> <span class="nb">echo</span> <span class="s2">&#34;-d </span><span class="nv">$d</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">done)</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        --cert-name <span class="nv">$primary</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        --non-interactive
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span></code></pre></div><h2 id="complete-production-setup">Complete Production Setup <a class="anchor" data-pagefind-ignore href="#complete-production-setup" aria-label="Link to this section">#</a></h2>
<p>Method 3 with host routing and security headers.</p>
<h3 id="haproxy-configuration-2">HAProxy Configuration <a class="anchor" data-pagefind-ignore href="#haproxy-configuration-2" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Part</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>global</code> ssl settings</td>
					<td>TLS 1.2 minimum, modern ciphers, for client (<code>bind</code>) and backend (<code>server</code>) sides</td>
			</tr>
			<tr>
					<td><code>listen stats</code></td>
					<td>Stats page and <code>/metrics</code> on 8404; change <code>admin:changeme</code></td>
			</tr>
			<tr>
					<td><code>http_frontend</code></td>
					<td>ACME challenges to <code>acme_backend</code>, everything else 301 to HTTPS</td>
			</tr>
			<tr>
					<td><code>https_frontend</code></td>
					<td>All certificates from <code>/etc/haproxy/certs/</code>, security headers, <code>X-Forwarded-Proto</code>, routing by Host</td>
			</tr>
			<tr>
					<td><code>app_servers</code></td>
					<td>Sticky sessions with the <code>SERVERID</code> cookie</td>
			</tr>
	</tbody>
</table>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy"># /etc/haproxy/haproxy.cfg

global
    log /dev/log local0
    log /dev/log local1 notice
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
    stats timeout 30s
    user haproxy
    group haproxy
    daemon
    
    maxconn 50000
    nbthread 4
    
    # Modern SSL settings
    ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305
    ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
    ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets
    ssl-default-server-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
    ssl-default-server-options ssl-min-ver TLSv1.2 no-tls-tickets
    tune.ssl.default-dh-param 2048

defaults
    log global
    mode http
    option httplog
    option dontlognull
    option forwardfor
    option http-server-close
    timeout connect 5s
    timeout client  50s
    timeout server  50s
    timeout http-request 10s
    timeout http-keep-alive 10s

# Stats
listen stats
    bind *:8404
    stats enable
    stats uri /stats
    stats refresh 10s
    stats auth admin:changeme
    http-request use-service prometheus-exporter if { path /metrics }

# HTTP Frontend
frontend http_frontend
    bind *:80
    
    # ACME challenges
    acl is_acme path_beg /.well-known/acme-challenge/
    use_backend acme_backend if is_acme
    
    # Redirect to HTTPS with 301
    http-request redirect scheme https code 301 unless is_acme

# HTTPS Frontend
frontend https_frontend
    bind *:443 ssl crt /etc/haproxy/certs/ strict-sni alpn h2,http/1.1
    
    # Security headers
    http-response set-header Strict-Transport-Security &#34;max-age=63072000; includeSubDomains; preload&#34;
    http-response set-header X-Content-Type-Options &#34;nosniff&#34;
    http-response set-header X-Frame-Options &#34;SAMEORIGIN&#34;
    http-response set-header X-XSS-Protection &#34;1; mode=block&#34;
    
    # Log SSL info
    http-request capture req.hdr(Host) len 50
    http-request set-header X-Forwarded-Proto https
    http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
    http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
    
    # Route based on host
    use_backend api_servers if { hdr(host) -i api.example.com }
    use_backend app_servers if { hdr(host) -i app.example.com }
    default_backend web_servers

# ACME challenge backend
backend acme_backend
    server acme 127.0.0.1:8080

# Web servers
backend web_servers
    balance roundrobin
    option httpchk GET /health
    http-check expect status 200
    server web1 192.168.1.10:8080 check inter 5s
    server web2 192.168.1.11:8080 check inter 5s

# API servers
backend api_servers
    balance leastconn
    option httpchk GET /api/health
    http-check expect status 200
    server api1 192.168.1.20:8080 check inter 5s
    server api2 192.168.1.21:8080 check inter 5s

# App servers
backend app_servers
    balance roundrobin
    option httpchk GET /health
    cookie SERVERID insert indirect nocache
    server app1 192.168.1.30:8080 check cookie app1
    server app2 192.168.1.31:8080 check cookie app2
</code></pre><h3 id="complete-deployment-script">Complete Deployment Script <a class="anchor" data-pagefind-ignore href="#complete-deployment-script" aria-label="Link to this section">#</a></h3>
<p>Sets up the challenge server as a systemd service on port 8080 and requests a certificate for each domain given as argument:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/setup-haproxy-letsencrypt.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Run this with HAProxy already up (it needs at least one certificate in</span>
</span></span><span class="line"><span class="cl"><span class="c1"># /etc/haproxy/certs, see the initial request above) and the deploy hook below in place.</span>
</span></span><span class="line"><span class="cl"><span class="nv">DOMAINS</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$@</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">EMAIL</span><span class="o">=</span><span class="s2">&#34;admin@example.com&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_CERT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/certs&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">WEBROOT</span><span class="o">=</span><span class="s2">&#34;/var/www/letsencrypt&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create directories</span>
</span></span><span class="line"><span class="cl">mkdir -p <span class="nv">$HAPROXY_CERT_DIR</span>
</span></span><span class="line"><span class="cl">mkdir -p <span class="nv">$WEBROOT</span>/.well-known/acme-challenge
</span></span><span class="line"><span class="cl">chown -R www-data:www-data <span class="nv">$WEBROOT</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create ACME challenge server</span>
</span></span><span class="line"><span class="cl">cat &gt; /etc/systemd/system/acme-challenge.service <span class="s">&lt;&lt; &#39;EOF&#39;
</span></span></span><span class="line"><span class="cl"><span class="s">[Unit]
</span></span></span><span class="line"><span class="cl"><span class="s">Description=ACME Challenge Server
</span></span></span><span class="line"><span class="cl"><span class="s">After=network.target
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[Service]
</span></span></span><span class="line"><span class="cl"><span class="s">Type=simple
</span></span></span><span class="line"><span class="cl"><span class="s">User=www-data
</span></span></span><span class="line"><span class="cl"><span class="s">WorkingDirectory=/var/www/letsencrypt
</span></span></span><span class="line"><span class="cl"><span class="s">ExecStart=/usr/bin/python3 -m http.server 8080
</span></span></span><span class="line"><span class="cl"><span class="s">Restart=always
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[Install]
</span></span></span><span class="line"><span class="cl"><span class="s">WantedBy=multi-user.target
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">systemctl daemon-reload
</span></span><span class="line"><span class="cl">systemctl <span class="nb">enable</span> acme-challenge
</span></span><span class="line"><span class="cl">systemctl start acme-challenge
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Request certificates</span>
</span></span><span class="line"><span class="cl"><span class="k">for</span> domain in <span class="nv">$DOMAINS</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;Requesting certificate for </span><span class="nv">$domain</span><span class="s2">...&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    certbot certonly <span class="se">\
</span></span></span><span class="line"><span class="cl">        --webroot <span class="se">\
</span></span></span><span class="line"><span class="cl">        -w <span class="nv">$WEBROOT</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        -d <span class="nv">$domain</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        --email <span class="nv">$EMAIL</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        --agree-tos <span class="se">\
</span></span></span><span class="line"><span class="cl">        --non-interactive <span class="se">\
</span></span></span><span class="line"><span class="cl">        --deploy-hook /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Create HAProxy certificate</span>
</span></span><span class="line"><span class="cl">    cat /etc/letsencrypt/live/<span class="nv">$domain</span>/fullchain.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">        /etc/letsencrypt/live/<span class="nv">$domain</span>/privkey.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">        &gt; <span class="nv">$HAPROXY_CERT_DIR</span>/<span class="nv">$domain</span>.pem
</span></span><span class="line"><span class="cl">    chmod <span class="m">600</span> <span class="nv">$HAPROXY_CERT_DIR</span>/<span class="nv">$domain</span>.pem
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload HAProxy</span>
</span></span><span class="line"><span class="cl">systemctl reload haproxy
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Setup complete!&#34;</span>
</span></span></code></pre></div><h3 id="deploy-hook-script">Deploy Hook Script <a class="anchor" data-pagefind-ignore href="#deploy-hook-script" aria-label="Link to this section">#</a></h3>
<p>The production version of the hook: runtime update first, reload as fallback, everything logged to <code>/var/log/certbot-haproxy.log</code>. It uses <code>RENEWED_LINEAGE</code>, the live directory of the renewed certificate.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_CERT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/certs&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_SOCKET</span><span class="o">=</span><span class="s2">&#34;/run/haproxy/admin.sock&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">LOG_FILE</span><span class="o">=</span><span class="s2">&#34;/var/log/certbot-haproxy.log&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">log<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;</span><span class="k">$(</span>date <span class="s1">&#39;+%Y-%m-%d %H:%M:%S&#39;</span><span class="k">)</span><span class="s2"> - </span><span class="nv">$1</span><span class="s2">&#34;</span> &gt;&gt; <span class="nv">$LOG_FILE</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">update_haproxy_cert<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">    <span class="nb">local</span> <span class="nv">domain</span><span class="o">=</span><span class="nv">$1</span>
</span></span><span class="line"><span class="cl">    <span class="nb">local</span> <span class="nv">cert_path</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$HAPROXY_CERT_DIR</span><span class="s2">/</span><span class="nv">$domain</span><span class="s2">.pem&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">local</span> <span class="nv">le_cert</span><span class="o">=</span><span class="s2">&#34;/etc/letsencrypt/live/</span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Combine certificates</span>
</span></span><span class="line"><span class="cl">    cat <span class="s2">&#34;</span><span class="nv">$le_cert</span><span class="s2">/fullchain.pem&#34;</span> <span class="s2">&#34;</span><span class="nv">$le_cert</span><span class="s2">/privkey.pem&#34;</span> &gt; <span class="s2">&#34;</span><span class="nv">$cert_path</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    chmod <span class="m">600</span> <span class="s2">&#34;</span><span class="nv">$cert_path</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Try runtime update first (HAProxy 2.4+)</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="o">[</span> -S <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="nb">echo</span> <span class="s2">&#34;show ssl cert </span><span class="nv">$cert_path</span><span class="s2">&#34;</span> <span class="p">|</span> socat stdio <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span> 2&gt;/dev/null <span class="p">|</span> grep -q <span class="s2">&#34;</span><span class="nv">$cert_path</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">            <span class="c1"># Certificate exists, update in-place: payload first, commit in a</span>
</span></span><span class="line"><span class="cl">            <span class="c1"># separate session (HAProxy 3.2 and later ignore a commit sent after the payload)</span>
</span></span><span class="line"><span class="cl">            <span class="o">{</span>
</span></span><span class="line"><span class="cl">                <span class="nb">echo</span> <span class="s2">&#34;set ssl cert </span><span class="nv">$cert_path</span><span class="s2"> &lt;&lt;&#34;</span>
</span></span><span class="line"><span class="cl">                cat <span class="s2">&#34;</span><span class="nv">$cert_path</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">                <span class="nb">echo</span> <span class="s2">&#34;&#34;</span>
</span></span><span class="line"><span class="cl">            <span class="o">}</span> <span class="p">|</span> socat stdio <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span> 2&gt;/dev/null
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="k">if</span> <span class="nb">echo</span> <span class="s2">&#34;commit ssl cert </span><span class="nv">$cert_path</span><span class="s2">&#34;</span> <span class="p">|</span> socat stdio <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span> 2&gt;/dev/null <span class="p">|</span> grep -q <span class="s2">&#34;Success&#34;</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">                log <span class="s2">&#34;Updated certificate for </span><span class="nv">$domain</span><span class="s2"> via runtime API&#34;</span>
</span></span><span class="line"><span class="cl">                <span class="k">return</span> <span class="m">0</span>
</span></span><span class="line"><span class="cl">            <span class="k">fi</span>
</span></span><span class="line"><span class="cl">        <span class="k">fi</span>
</span></span><span class="line"><span class="cl">    <span class="k">fi</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Fallback to reload</span>
</span></span><span class="line"><span class="cl">    systemctl reload haproxy
</span></span><span class="line"><span class="cl">    log <span class="s2">&#34;Reloaded HAProxy for </span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Process the renewed certificate (RENEWED_LINEAGE is /etc/letsencrypt/live/&lt;name&gt;;</span>
</span></span><span class="line"><span class="cl"><span class="c1"># RENEWED_DOMAINS lists every name on it, which may not have a live directory of its own)</span>
</span></span><span class="line"><span class="cl"><span class="nv">domain</span><span class="o">=</span><span class="k">$(</span>basename <span class="s2">&#34;</span><span class="nv">$RENEWED_LINEAGE</span><span class="s2">&#34;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">log <span class="s2">&#34;Processing renewal for </span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">update_haproxy_cert <span class="s2">&#34;</span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h2 id="testing-and-verification">Testing and Verification <a class="anchor" data-pagefind-ignore href="#testing-and-verification" aria-label="Link to this section">#</a></h2>
<p>Check what clients actually get, then test the renewal path before it runs for real.</p>
<h3 id="test-certificate">Test Certificate <a class="anchor" data-pagefind-ignore href="#test-certificate" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check certificate</span>
</span></span><span class="line"><span class="cl">openssl s_client -connect example.com:443 -servername example.com &lt; /dev/null 2&gt;/dev/null <span class="p">|</span> openssl x509 -text -noout <span class="p">|</span> head -20
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify chain (s_client checks the served chain against the system trust store)</span>
</span></span><span class="line"><span class="cl">openssl s_client -connect example.com:443 -servername example.com -verify_return_error &lt; /dev/null 2&gt;<span class="p">&amp;</span><span class="m">1</span> <span class="p">|</span> grep <span class="s2">&#34;Verify return code&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check expiration</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="p">|</span> openssl s_client -connect example.com:443 -servername example.com 2&gt;/dev/null <span class="p">|</span> openssl x509 -noout -dates
</span></span></code></pre></div><h3 id="ssl-labs-test">SSL Labs Test <a class="anchor" data-pagefind-ignore href="#ssl-labs-test" aria-label="Link to this section">#</a></h3>
<p>A full external grade of your TLS configuration.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">curl -s <span class="s2">&#34;https://api.ssllabs.com/api/v3/analyze?host=example.com&amp;publish=off&amp;all=done&#34;</span>
</span></span></code></pre></div><h3 id="test-renewal">Test Renewal <a class="anchor" data-pagefind-ignore href="#test-renewal" aria-label="Link to this section">#</a></h3>
<p>Runs the whole renewal against the staging server without replacing certificates.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">certbot renew --dry-run
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<h3 id="common-issues">Common Issues <a class="anchor" data-pagefind-ignore href="#common-issues" aria-label="Link to this section">#</a></h3>
<ol>
<li><strong>Permission denied on socket</strong>:</li>
</ol>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">chmod <span class="m">660</span> /run/haproxy/admin.sock
</span></span><span class="line"><span class="cl">chown haproxy:haproxy /run/haproxy/admin.sock
</span></span></code></pre></div><ol start="2">
<li><strong>Certificate not found</strong>:</li>
</ol>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check certificate directory</span>
</span></span><span class="line"><span class="cl">ls -la /etc/haproxy/certs/
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify HAProxy can load them (it reads certificates as root before</span>
</span></span><span class="line"><span class="cl"><span class="c1"># dropping privileges, so root-only 600 files are fine)</span>
</span></span><span class="line"><span class="cl">haproxy -c -f /etc/haproxy/haproxy.cfg
</span></span></code></pre></div><ol start="3">
<li><strong>ACME challenge fails</strong>:</li>
</ol>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Verify challenge server is running</span>
</span></span><span class="line"><span class="cl">curl http://localhost:8080/.well-known/acme-challenge/test
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check HAProxy routing</span>
</span></span><span class="line"><span class="cl">curl -H <span class="s2">&#34;Host: example.com&#34;</span> http://localhost/.well-known/acme-challenge/test
</span></span></code></pre></div><ol start="4">
<li><strong>SNI not matching</strong>:</li>
</ol>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Test specific SNI</span>
</span></span><span class="line"><span class="cl">curl -v --resolve example.com:443:127.0.0.1 https://example.com/
</span></span></code></pre></div><h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Private keys.</strong> The combined PEM files contain the key: keep them mode 600, as the scripts do.</li>
<li><strong>DNS API credentials.</strong> <code>cloudflare.ini</code> or AWS keys can change your DNS; restrict their scope and file permissions.</li>
<li><strong>Stats page.</strong> Change <code>stats auth admin:changeme</code> and firewall port 8404.</li>
<li><strong>HSTS preload.</strong> Once preloaded, browsers refuse HTTP for the domain and its subdomains for a long time; enable it deliberately.</li>
</ul>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-haproxy-letsencrypt" rel="noopener">pderuiter/blog-haproxy-letsencrypt</a>. It creates an HAProxy VM on Proxmox, requests the certificates with certbot over HTTP-01 and installs the complete production setup from this post, with the runtime API deploy hook and the renewal timer; point your domains at the VM, run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code> (try it against the Let&rsquo;s Encrypt staging server first).</p>
<h2 id="next-steps">Next Steps <a class="anchor" data-pagefind-ignore href="#next-steps" aria-label="Link to this section">#</a></h2>
<p>Next in the series: debugging HTTP headers in HAProxy, for troubleshooting web application issues.</p>
<h2 id="summary">Summary <a class="anchor" data-pagefind-ignore href="#summary" aria-label="Link to this section">#</a></h2>
<p>Key takeaways for HAProxy with Let&rsquo;s Encrypt:</p>
<ul>
<li>Combine fullchain.pem and privkey.pem for HAProxy certificates</li>
<li>Use HTTP-01 challenges for standard domains, DNS-01 for wildcards</li>
<li>Implement zero-downtime certificate updates with HAProxy&rsquo;s runtime API</li>
<li>Set up automated renewal with systemd timers or cron</li>
<li>Use proper TLS settings for security (TLS 1.2+, strong ciphers)</li>
<li>Always enable HSTS for production sites</li>
</ul>
<p>With this setup, certificates renew and load themselves without manual work.</p>
]]></content:encoded></item><item><title>Configuring Traefik with Let's Encrypt on Docker</title><link>https://blog.bsdserver.nl/configuring-traefik-with-lets-encrypt-on-docker/</link><guid isPermaLink="false">693b529e79eb54000160a4e2</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Thu, 11 Dec 2025 23:24:14 +0000</pubDate><description>Traefik isn't just a reverse proxy; it's a powerful, dynamic edge router that makes managing your container-based infrastructure easier and more efficient.</description><category>Docker</category><category>Traefik</category><category>Let's Encrypt</category><category>DevOps</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/traefik-letsencrypt-docker.png" medium="image"/><content:encoded><![CDATA[<p>Running several web containers on one Docker host means a reverse proxy in front of them, plus a TLS certificate for every hostname. Doing that by hand means editing proxy configs and renewing certificates for each new container.</p>
<p>This post sets up Traefik on a Docker host. It routes to containers based on their labels, gets Let&rsquo;s Encrypt certificates through a DNS-01 challenge at TransIP, protects its dashboard with basic auth, and exposes Prometheus metrics.</p>
<h2 id="why-traefik">Why Traefik? <a class="anchor" data-pagefind-ignore href="#why-traefik" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Docker-aware</strong>: it watches the Docker socket and picks up containers as they start, configured by labels.</li>
<li><strong>Built-in ACME</strong>: requests and renews Let&rsquo;s Encrypt certificates itself.</li>
<li><strong>DNS-01 support</strong>: works for hosts that are not reachable from the internet, and for wildcards.</li>
<li><strong>Metrics included</strong>: Prometheus metrics without an extra exporter.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> when containers come and go on a Docker host and each needs its own hostname and certificate.</li>
<li><strong>Skip it</strong> for one static site; a plain Nginx or Caddy config is simpler. On Kubernetes, see the <a href="https://blog.bsdserver.nl/provisioning-tls-certificates-with-traefik-cert-manager-and-acme-dns-in-kubernetes/">cert-manager and ACME-DNS post</a>.</li>
</ul>
<h2 id="how-it-works">How it works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Traefik container</td>
					<td>Docker host</td>
					<td>Listens on 80/443, routes requests to containers, serves the dashboard and metrics.</td>
			</tr>
			<tr>
					<td>Docker socket</td>
					<td>Docker host</td>
					<td>Read-only source of the containers and their labels.</td>
			</tr>
			<tr>
					<td>TransIP API</td>
					<td>TransIP</td>
					<td>Traefik creates the <code>_acme-challenge</code> TXT record there to prove domain ownership.</td>
			</tr>
			<tr>
					<td><code>acme.json</code></td>
					<td>Docker host</td>
					<td>Stores the ACME account and the issued certificates.</td>
			</tr>
	</tbody>
</table>
<p>The flow: a container starts with <code>traefik.*</code> labels → Traefik sees it on the Docker socket → creates a router → requests a certificate from Let&rsquo;s Encrypt → proves ownership with a TXT record via the TransIP API → stores the certificate in <code>acme.json</code> and serves HTTPS.</p>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<ul>
<li>A server or VM running Docker and Docker Compose</li>
<li>A domain registered through Transip</li>
<li>Access to Transip API credentials</li>
</ul>
<h2 id="1-directory-structure">1. Directory Structure <a class="anchor" data-pagefind-ignore href="#1-directory-structure" aria-label="Link to this section">#</a></h2>
<p>A project directory with a <code>config</code> folder for the Traefik config, the TransIP key and the certificate store.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">mkdir traefik-docker <span class="o">&amp;&amp;</span> <span class="nb">cd</span> traefik-docker
</span></span><span class="line"><span class="cl">mkdir config
</span></span><span class="line"><span class="cl">touch config/acme.json
</span></span><span class="line"><span class="cl">chmod <span class="m">600</span> config/acme.json
</span></span></code></pre></div><p>Create <code>acme.json</code> up front. If it doesn&rsquo;t exist, Docker creates a <em>directory</em> with that name for the bind mount, and Traefik then skips the resolver with <code>permissions 755 for acme.json are too open, please use 600</code>.</p>
<h2 id="2-docker-compose-file">2. Docker Compose File <a class="anchor" data-pagefind-ignore href="#2-docker-compose-file" aria-label="Link to this section">#</a></h2>
<p>The Compose file runs Traefik itself. Its own labels define the dashboard router, which doubles as the first test of the certificate resolver.</p>
<ul>
<li><code>ports</code>: 80 and 443 on the host, the two entry points.</li>
<li><code>TRANSIP_*</code> variables: credentials for the DNS challenge (see below).</li>
<li><code>docker.sock</code> read-only: Traefik only reads container information.</li>
<li><code>acme.json</code>: mounted read-write, Traefik writes certificates to it.</li>
<li><code>traefik.http.routers.dashboard.*</code> labels: route <code>traefik.yourdomain.com</code> to the built-in dashboard (<code>api@internal</code>), behind the <code>auth</code> middleware, with a certificate from the <code>transip</code> resolver.</li>
<li><code>traefik-network</code>: a named network. Put the containers Traefik should reach on it.</li>
</ul>
<p>Create <code>docker-compose.yml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">services</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">traefik</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l">traefik:v2.11</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">container_name</span><span class="p">:</span><span class="w"> </span><span class="l">traefik</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">restart</span><span class="p">:</span><span class="w"> </span><span class="l">always</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;80:80&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;443:443&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">environment</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">TRANSIP_ACCOUNT_NAME=your_transip_account_name</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">TRANSIP_PRIVATE_KEY_PATH=/transip.key</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">volumes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;/var/run/docker.sock:/var/run/docker.sock:ro&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;./config/traefik.yml:/traefik.yml:ro&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;./config/acme.json:/acme.json&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;./config/transip.key:/transip.key:ro&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;traefik.enable=true&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;traefik.http.routers.dashboard.rule=Host(`traefik.yourdomain.com`)&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;traefik.http.routers.dashboard.service=api@internal&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;traefik.http.routers.dashboard.middlewares=auth&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;traefik.http.middlewares.auth.basicauth.users=admin:$$apr1$$...$$...P/&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;traefik.http.routers.dashboard.tls=true&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;traefik.http.routers.dashboard.tls.certresolver=transip&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">networks</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">traefik-network</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">networks</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">traefik-network</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">traefik-network</span><span class="w">
</span></span></span></code></pre></div><p>Two things to get right:</p>
<ul>
<li><strong>TransIP credentials</strong>: the API authenticates with a key pair, not a single API key. Generate one in the TransIP control panel, save the private key as <code>config/transip.key</code> (<code>chmod 600</code>), and pass its path in <code>TRANSIP_PRIVATE_KEY_PATH</code>. With only an API key variable, Traefik logs <code>transip: some credentials information are missing: TRANSIP_PRIVATE_KEY_PATH</code> and never gets a certificate.</li>
<li><strong>Image version</strong>: pin at least <code>v2.11</code>. Older v2 releases such as <code>v2.10</code> use Docker API 1.24, which Docker Engine 29 refuses (<code>client version 1.24 is too old. Minimum supported API version is 1.44</code>), so Traefik never sees your containers.</li>
</ul>
<h2 id="3-traefik-configuration">3. Traefik Configuration <a class="anchor" data-pagefind-ignore href="#3-traefik-configuration" aria-label="Link to this section">#</a></h2>
<p>The static configuration: entry points, the certificate resolver, the Docker provider and metrics. Changes here need a container restart.</p>
<table>
	<thead>
			<tr>
					<th>Section</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>api.dashboard</code></td>
					<td>Enables the dashboard, served through the <code>api@internal</code> service.</td>
			</tr>
			<tr>
					<td><code>entryPoints</code></td>
					<td><code>web</code> on :80 and <code>websecure</code> on :443.</td>
			</tr>
			<tr>
					<td><code>certificatesResolvers.transip</code></td>
					<td>ACME resolver named <code>transip</code>: DNS-01 via the TransIP provider, certificates stored in <code>acme.json</code>. Routers refer to it by name.</td>
			</tr>
			<tr>
					<td><code>log.level: DEBUG</code></td>
					<td>Verbose, useful while you watch the first certificate come in. Lower it afterwards.</td>
			</tr>
			<tr>
					<td><code>providers.docker</code></td>
					<td>Reads containers from the socket. <code>exposedByDefault: false</code> routes only containers with <code>traefik.enable=true</code>.</td>
			</tr>
			<tr>
					<td><code>metrics.prometheus</code></td>
					<td>Prometheus metrics on the <code>web</code> entry point, labelled per entry point and per service.</td>
			</tr>
	</tbody>
</table>
<p>Create <code>config/traefik.yml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">api</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">dashboard</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">entryPoints</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">web</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">address</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;:80&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">websecure</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">address</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;:443&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">certificatesResolvers</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">transip</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">acme</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">email</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;your_email@example.com&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">storage</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;acme.json&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">dnsChallenge</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">provider</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;transip&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">delayBeforeCheck</span><span class="p">:</span><span class="w"> </span><span class="m">0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">log</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">level</span><span class="p">:</span><span class="w"> </span><span class="l">DEBUG</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">providers</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">docker</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">endpoint</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;unix:///var/run/docker.sock&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">exposedByDefault</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metrics</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">prometheus</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">entryPoint</span><span class="p">:</span><span class="w"> </span><span class="l">web</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">addEntryPointsLabels</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">addServicesLabels</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span></code></pre></div><h2 id="4-securing-the-dashboard-with-basic-authentication">4. Securing the Dashboard with Basic Authentication <a class="anchor" data-pagefind-ignore href="#4-securing-the-dashboard-with-basic-authentication" aria-label="Link to this section">#</a></h2>
<p>The dashboard shows every router and service, so it should not be open. The <code>auth</code> middleware in the Compose labels needs an htpasswd hash.</p>
<p>Generate a username and password hash:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">htpasswd -nb admin securepassword
</span></span></code></pre></div><p>Replace <code>securepassword</code> with a strong password. Place the generated hash in the Docker Compose label, doubling every <code>$</code> (<code>$apr1$</code> becomes <code>$$apr1$$</code>) so Compose doesn&rsquo;t treat it as a variable:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">htpasswd -nb admin securepassword <span class="p">|</span> sed -e <span class="s1">&#39;s/\$/\$\$/g&#39;</span>
</span></span></code></pre></div><h2 id="5-starting-traefik">5. Starting Traefik <a class="anchor" data-pagefind-ignore href="#5-starting-traefik" aria-label="Link to this section">#</a></h2>
<p>Start the stack in the background:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">docker compose up -d
</span></span></code></pre></div><h2 id="6-verify-your-setup">6. Verify Your Setup <a class="anchor" data-pagefind-ignore href="#6-verify-your-setup" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Access the Dashboard</strong>: Navigate to <code>https://traefik.yourdomain.com</code></li>
<li><strong>Verify SSL</strong>: Check the logs to confirm certificate issuance:</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">docker logs traefik
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>permissions 755 for acme.json are too open</code></td>
					<td><code>acme.json</code> was created as a directory or with the wrong mode. Create the file first, <code>chmod 600</code>.</td>
			</tr>
			<tr>
					<td><code>some credentials information are missing: TRANSIP_PRIVATE_KEY_PATH</code></td>
					<td>TransIP needs the account name and the private key file, not an API key.</td>
			</tr>
			<tr>
					<td><code>client version 1.24 is too old</code></td>
					<td>Traefik older than v2.11 on Docker Engine 29. Use <code>traefik:v2.11</code> or newer.</td>
			</tr>
			<tr>
					<td>Dashboard login fails</td>
					<td><code>$</code> in the hash not doubled in the Compose label.</td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Docker socket</strong>: read-only, but it still exposes all container information to Traefik. Keep the Traefik image up to date.</li>
<li><strong>Secrets on disk</strong>: <code>acme.json</code> (private keys) and <code>transip.key</code> (DNS write access to your domains) both at mode 600.</li>
<li><strong>Metrics on port 80</strong>: with <code>entryPoint: web</code>, the <code>/metrics</code> path is reachable by anyone who can reach port 80. Firewall it or use a separate entry point.</li>
<li><strong>Dashboard</strong>: keep it behind the <code>auth</code> middleware with a strong password.</li>
</ul>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-traefik-letsencrypt-docker" rel="noopener">pderuiter/blog-traefik-letsencrypt-docker</a>. It creates an Ubuntu 24.04 VM, installs Docker, and deploys this Traefik stack with the TransIP resolver and the protected dashboard. Run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>Traefik now terminates TLS with DNS-validated Let&rsquo;s Encrypt certificates, protects its dashboard, and exposes metrics for Prometheus. To publish a container, put it on <code>traefik-network</code> and give it <code>traefik.enable=true</code> plus a router rule and the <code>transip</code> cert resolver.</p>
]]></content:encoded></item></channel></rss>