<?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>TLS | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/tls/</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/tls/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title>HAProxy mTLS: Securing API Access with Mutual TLS Authentication</title><link>https://blog.bsdserver.nl/haproxy-mtls-securing-api-access-with-mutual-tls-authentication/</link><guid isPermaLink="false">693b755d79eb54000160a60f</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:52:29 +0000</pubDate><description>Mutual TLS (mTLS) provides strong authentication by requiring both client and server to present certificates.</description><category>HAProxy</category><category>mTLS</category><category>Security</category><category>TLS</category><category>Certificates</category><category>API</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/haproxy-mtls.png" medium="image"/><content:encoded><![CDATA[<p>Mutual TLS (mTLS) provides strong authentication by requiring both client and server to present certificates. API keys and passwords can leak and be replayed; a client certificate proves identity during the TLS handshake, before any request reaches your application.</p>
<p>This guide builds a small internal CA, configures HAProxy to require client certificates, passes the certificate identity to the backends, authorizes by CN, OU or fingerprint, and revokes certificates with a CRL.</p>
<h2 id="what-is-mtls">What is mTLS? <a class="anchor" data-pagefind-ignore href="#what-is-mtls" aria-label="Link to this section">#</a></h2>
<p>In standard TLS, only the server presents a certificate. With mTLS:</p>
<ol>
<li>Server presents its certificate to the client</li>
<li>Client verifies the server certificate</li>
<li>Client presents its certificate to the server</li>
<li>Server verifies the client certificate</li>
</ol>
<p>Both parties are authenticated. HAProxy does the client check, so the backends do not need any TLS code.</p>
<h2 id="why-mtls">Why mTLS? <a class="anchor" data-pagefind-ignore href="#why-mtls" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Service-to-service communication</strong>: Microservices authenticating each other</li>
<li><strong>API security</strong>: Authenticating API clients without passwords</li>
<li><strong>Zero-trust networks</strong>: Verifying identity at every connection</li>
<li><strong>IoT devices</strong>: Authenticating embedded devices</li>
<li><strong>B2B integrations</strong>: Partner API access with certificate-based auth</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 machine clients you control or issue certificates to: services, devices, partners.</li>
<li><strong>Skip it</strong> for public websites and end users in browsers. Installing certificates on user devices is painful; use OAuth or sessions instead.</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>Internal CA</td>
					<td>A locked-down host (here: the HAProxy host)</td>
					<td>Signs server and client certificates, publishes the CRL.</td>
			</tr>
			<tr>
					<td>HAProxy</td>
					<td>Load balancer</td>
					<td>Terminates TLS, checks the client certificate against the CA and CRL, applies ACLs, adds identity headers.</td>
			</tr>
			<tr>
					<td>Backends</td>
					<td>App servers</td>
					<td>Receive plain HTTP plus <code>X-Client-*</code> headers.</td>
			</tr>
			<tr>
					<td>Clients</td>
					<td>Services, devices, partners</td>
					<td>Present a certificate signed by the CA.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client connects with its certificate → HAProxy verifies it against <code>ca-file</code> and <code>crl-file</code> → ACLs on CN/OU allow or deny → request goes to a backend with the client identity in headers.</p>
<h2 id="certificate-infrastructure-setup">Certificate Infrastructure Setup <a class="anchor" data-pagefind-ignore href="#certificate-infrastructure-setup" aria-label="Link to this section">#</a></h2>
<h3 id="create-a-certificate-authority-ca">Create a Certificate Authority (CA) <a class="anchor" data-pagefind-ignore href="#create-a-certificate-authority-ca" aria-label="Link to this section">#</a></h3>
<p>Your own CA decides who is a valid client: HAProxy trusts every certificate it signs. Use a private CA, never a public one, or anyone with a public certificate gets in.</p>
<p>What the <code>openssl.cnf</code> sections do:</p>
<table>
	<thead>
			<tr>
					<th>Section</th>
					<th>Use</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>CA_default</code></td>
					<td>Paths, 365-day default validity, 30-day CRL validity. <code>copy_extensions = copy</code> keeps the SAN from the CSR.</td>
			</tr>
			<tr>
					<td><code>policy_strict</code></td>
					<td>Only <code>commonName</code> is required in requests.</td>
			</tr>
			<tr>
					<td><code>v3_ca</code></td>
					<td>Extensions for the CA certificate itself.</td>
			</tr>
			<tr>
					<td><code>usr_cert</code></td>
					<td>Client certificates: <code>extendedKeyUsage = clientAuth</code>.</td>
			</tr>
			<tr>
					<td><code>server_cert</code></td>
					<td>Server certificates: <code>extendedKeyUsage = serverAuth</code>.</td>
			</tr>
	</tbody>
</table>
<p>The CA key is encrypted with a passphrase (<code>-aes256</code>) and the CA certificate is valid for 10 years.</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 CA directory structure</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/haproxy/ca/<span class="o">{</span>certs,crl,newcerts,private,csr<span class="o">}</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">700</span> /etc/haproxy/ca/private
</span></span><span class="line"><span class="cl">touch /etc/haproxy/ca/index.txt
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="m">1000</span> &gt; /etc/haproxy/ca/serial
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create CA configuration</span>
</span></span><span class="line"><span class="cl">cat &gt; /etc/haproxy/ca/openssl.cnf <span class="s">&lt;&lt; &#39;EOF&#39;
</span></span></span><span class="line"><span class="cl"><span class="s">[ca]
</span></span></span><span class="line"><span class="cl"><span class="s">default_ca = CA_default
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[CA_default]
</span></span></span><span class="line"><span class="cl"><span class="s">dir               = /etc/haproxy/ca
</span></span></span><span class="line"><span class="cl"><span class="s">certs             = $dir/certs
</span></span></span><span class="line"><span class="cl"><span class="s">crl_dir           = $dir/crl
</span></span></span><span class="line"><span class="cl"><span class="s">new_certs_dir     = $dir/newcerts
</span></span></span><span class="line"><span class="cl"><span class="s">database          = $dir/index.txt
</span></span></span><span class="line"><span class="cl"><span class="s">serial            = $dir/serial
</span></span></span><span class="line"><span class="cl"><span class="s">private_key       = $dir/private/ca.key
</span></span></span><span class="line"><span class="cl"><span class="s">certificate       = $dir/certs/ca.crt
</span></span></span><span class="line"><span class="cl"><span class="s">default_md        = sha256
</span></span></span><span class="line"><span class="cl"><span class="s">default_days      = 365
</span></span></span><span class="line"><span class="cl"><span class="s">default_crl_days  = 30
</span></span></span><span class="line"><span class="cl"><span class="s">copy_extensions   = copy
</span></span></span><span class="line"><span class="cl"><span class="s">preserve          = no
</span></span></span><span class="line"><span class="cl"><span class="s">policy            = policy_strict
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[policy_strict]
</span></span></span><span class="line"><span class="cl"><span class="s">countryName             = optional
</span></span></span><span class="line"><span class="cl"><span class="s">stateOrProvinceName     = optional
</span></span></span><span class="line"><span class="cl"><span class="s">localityName            = optional
</span></span></span><span class="line"><span class="cl"><span class="s">organizationName        = optional
</span></span></span><span class="line"><span class="cl"><span class="s">organizationalUnitName  = optional
</span></span></span><span class="line"><span class="cl"><span class="s">commonName              = supplied
</span></span></span><span class="line"><span class="cl"><span class="s">emailAddress            = optional
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[req]
</span></span></span><span class="line"><span class="cl"><span class="s">default_bits        = 4096
</span></span></span><span class="line"><span class="cl"><span class="s">distinguished_name  = req_distinguished_name
</span></span></span><span class="line"><span class="cl"><span class="s">string_mask         = utf8only
</span></span></span><span class="line"><span class="cl"><span class="s">default_md          = sha256
</span></span></span><span class="line"><span class="cl"><span class="s">x509_extensions     = v3_ca
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[req_distinguished_name]
</span></span></span><span class="line"><span class="cl"><span class="s">countryName                     = Country Name (2 letter code)
</span></span></span><span class="line"><span class="cl"><span class="s">stateOrProvinceName             = State or Province Name
</span></span></span><span class="line"><span class="cl"><span class="s">localityName                    = Locality Name
</span></span></span><span class="line"><span class="cl"><span class="s">organizationName                = Organization Name
</span></span></span><span class="line"><span class="cl"><span class="s">organizationalUnitName          = Organizational Unit Name
</span></span></span><span class="line"><span class="cl"><span class="s">commonName                      = Common Name
</span></span></span><span class="line"><span class="cl"><span class="s">emailAddress                    = Email Address
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[v3_ca]
</span></span></span><span class="line"><span class="cl"><span class="s">subjectKeyIdentifier = hash
</span></span></span><span class="line"><span class="cl"><span class="s">authorityKeyIdentifier = keyid:always,issuer
</span></span></span><span class="line"><span class="cl"><span class="s">basicConstraints = critical, CA:true
</span></span></span><span class="line"><span class="cl"><span class="s">keyUsage = critical, digitalSignature, cRLSign, keyCertSign
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[usr_cert]
</span></span></span><span class="line"><span class="cl"><span class="s">basicConstraints = CA:FALSE
</span></span></span><span class="line"><span class="cl"><span class="s">nsCertType = client, email
</span></span></span><span class="line"><span class="cl"><span class="s">nsComment = &#34;Client Certificate&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">subjectKeyIdentifier = hash
</span></span></span><span class="line"><span class="cl"><span class="s">authorityKeyIdentifier = keyid,issuer
</span></span></span><span class="line"><span class="cl"><span class="s">keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
</span></span></span><span class="line"><span class="cl"><span class="s">extendedKeyUsage = clientAuth, emailProtection
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[server_cert]
</span></span></span><span class="line"><span class="cl"><span class="s">basicConstraints = CA:FALSE
</span></span></span><span class="line"><span class="cl"><span class="s">nsCertType = server
</span></span></span><span class="line"><span class="cl"><span class="s">nsComment = &#34;Server Certificate&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">subjectKeyIdentifier = hash
</span></span></span><span class="line"><span class="cl"><span class="s">authorityKeyIdentifier = keyid,issuer:always
</span></span></span><span class="line"><span class="cl"><span class="s">keyUsage = critical, digitalSignature, keyEncipherment
</span></span></span><span class="line"><span class="cl"><span class="s">extendedKeyUsage = serverAuth
</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"><span class="c1"># Generate CA private key</span>
</span></span><span class="line"><span class="cl">openssl genrsa -aes256 -out /etc/haproxy/ca/private/ca.key <span class="m">4096</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">400</span> /etc/haproxy/ca/private/ca.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate CA certificate</span>
</span></span><span class="line"><span class="cl">openssl req -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key /etc/haproxy/ca/private/ca.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  -new -x509 -days <span class="m">3650</span> -sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -extensions v3_ca <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -subj <span class="s2">&#34;/C=US/ST=State/L=City/O=MyOrg/CN=MyOrg CA&#34;</span>
</span></span></code></pre></div><h3 id="generate-server-certificate">Generate Server Certificate <a class="anchor" data-pagefind-ignore href="#generate-server-certificate" aria-label="Link to this section">#</a></h3>
<p>HAProxy presents this certificate to clients on the mTLS port. Clients verify it against the same CA, so they know they talk to the real API. The bind line loads certificate and key from one combined PEM file.</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"># Generate server key</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/haproxy/certs
</span></span><span class="line"><span class="cl">openssl genrsa -out /etc/haproxy/certs/server.key <span class="m">2048</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate server CSR (clients such as Go and Python require the SAN)</span>
</span></span><span class="line"><span class="cl">openssl req -new <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key /etc/haproxy/certs/server.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out /etc/haproxy/ca/csr/server.csr <span class="se">\
</span></span></span><span class="line"><span class="cl">  -subj <span class="s2">&#34;/CN=api.example.com&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -addext <span class="s2">&#34;subjectAltName=DNS:api.example.com&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Sign server certificate with CA</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -extensions server_cert <span class="se">\
</span></span></span><span class="line"><span class="cl">  -days <span class="m">365</span> -notext -md sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -in /etc/haproxy/ca/csr/server.csr <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out /etc/haproxy/certs/server.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -batch
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create combined PEM for HAProxy</span>
</span></span><span class="line"><span class="cl">cat /etc/haproxy/certs/server.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">    /etc/haproxy/certs/server.key <span class="se">\
</span></span></span><span class="line"><span class="cl">    &gt; /etc/haproxy/certs/server.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">600</span> /etc/haproxy/certs/server.pem
</span></span></code></pre></div><h3 id="generate-client-certificate">Generate Client Certificate <a class="anchor" data-pagefind-ignore href="#generate-client-certificate" aria-label="Link to this section">#</a></h3>
<p>Every client gets its own certificate, so you can authorize and revoke them one by one. The script takes a name (becomes the CN) and an optional OU (default <code>internal</code>); both are used in the ACLs later.</p>
<table>
	<thead>
			<tr>
					<th>Output</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>.key</code> + <code>.crt</code></td>
					<td>curl, Python, Go, Node.js</td>
			</tr>
			<tr>
					<td><code>.pem</code></td>
					<td>Tools that want certificate and key in one file</td>
			</tr>
			<tr>
					<td><code>.p12</code></td>
					<td>Browsers and Java; password <code>changeme</code>, change it</td>
			</tr>
	</tbody>
</table>
<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/generate-client-cert.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">CLIENT_NAME</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$1</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">CLIENT_OU</span><span class="o">=</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">2</span><span class="k">:-</span><span class="nv">internal</span><span class="si">}</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> -z <span class="s2">&#34;</span><span class="nv">$CLIENT_NAME</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="nb">echo</span> <span class="s2">&#34;Usage: </span><span class="nv">$0</span><span class="s2"> &lt;client-name&gt; [organizational-unit]&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">exit</span> <span class="m">1</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="nv">CA_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/ca&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">OUTPUT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/clients/</span><span class="nv">$CLIENT_NAME</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">mkdir -p <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</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"># Generate client key</span>
</span></span><span class="line"><span class="cl">openssl genrsa -out <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="m">2048</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate client CSR</span>
</span></span><span class="line"><span class="cl">openssl req -new <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/csr/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.csr&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -subj <span class="s2">&#34;/OU=</span><span class="nv">$CLIENT_OU</span><span class="s2">/CN=</span><span class="nv">$CLIENT_NAME</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"># Sign client certificate</span>
</span></span><span class="line"><span class="cl">openssl ca -config <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/openssl.cnf&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -extensions usr_cert <span class="se">\
</span></span></span><span class="line"><span class="cl">  -days <span class="m">365</span> -notext -md sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -in <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/csr/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.csr&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -batch
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create combined PEM (for applications that need it)</span>
</span></span><span class="line"><span class="cl">cat <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    &gt; <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</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"># Create PKCS12 bundle (for browsers and some clients)</span>
</span></span><span class="line"><span class="cl">openssl pkcs12 -export <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.p12&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -inkey <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -in <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -certfile <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/certs/ca.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -passout pass:changeme
</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;Client certificate generated in </span><span class="nv">$OUTPUT_DIR</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Files: </span><span class="nv">$CLIENT_NAME</span><span class="s2">.key, </span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt, </span><span class="nv">$CLIENT_NAME</span><span class="s2">.pem, </span><span class="nv">$CLIENT_NAME</span><span class="s2">.p12&#34;</span>
</span></span></code></pre></div><h2 id="basic-mtls-configuration">Basic mTLS Configuration <a class="anchor" data-pagefind-ignore href="#basic-mtls-configuration" aria-label="Link to this section">#</a></h2>
<p>Two bind options switch mTLS on:</p>
<ul>
<li><code>ca-file</code>: the CA that client certificates must be signed by.</li>
<li><code>verify</code>: <code>required</code> rejects the handshake without a valid certificate; <code>optional</code> lets it through and you decide in ACLs.</li>
</ul>
<table>
	<thead>
			<tr>
					<th>Mode</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>verify required</code></td>
					<td>Endpoints only certificate holders may reach</td>
			</tr>
			<tr>
					<td><code>verify optional</code></td>
					<td>One endpoint serving both anonymous and authenticated clients</td>
			</tr>
	</tbody>
</table>
<h3 id="required-mtls">Required mTLS <a class="anchor" data-pagefind-ignore href="#required-mtls" aria-label="Link to this section">#</a></h3>
<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
    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

frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Client certificate is required - connections without valid cert are rejected
    default_backend api_servers

backend api_servers
    server api1 192.168.1.10:8080 check
    server api2 192.168.1.11:8080 check
</code></pre><h3 id="optional-mtls-certificate-if-available">Optional mTLS (Certificate if Available) <a class="anchor" data-pagefind-ignore href="#optional-mtls-certificate-if-available" aria-label="Link to this section">#</a></h3>
<p>Clients with a valid certificate go to <code>authenticated_api</code>, clients without one to <code>public_api</code>, and an invalid certificate gets a 403.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_optional
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify optional
    
    # Check if client provided valid certificate
    # (ssl_c_verify is also 0 when no certificate was sent, so combine it with ssl_fc_has_crt)
    acl client_cert_valid ssl_c_verify 0
    acl client_cert_provided ssl_fc_has_crt
    
    # Reject invalid certificates
    http-request deny if client_cert_provided !client_cert_valid
    
    # Route based on certificate status
    use_backend authenticated_api if client_cert_provided client_cert_valid
    use_backend public_api unless client_cert_provided

backend authenticated_api
    server api1 192.168.1.10:8080 check

backend public_api
    server public1 192.168.1.20:8080 check
</code></pre><h2 id="passing-client-certificate-info-to-backend">Passing Client Certificate Info to Backend <a class="anchor" data-pagefind-ignore href="#passing-client-certificate-info-to-backend" aria-label="Link to this section">#</a></h2>
<p>The backend sees plain HTTP from HAProxy, not the certificate. Add headers so the application knows which client called.</p>
<h3 id="certificate-details-as-headers">Certificate Details as Headers <a class="anchor" data-pagefind-ignore href="#certificate-details-as-headers" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>ssl_c_s_dn(cn)</code>: the client name, the usual identity for application logic.</li>
<li><code>ssl_c_serial</code> / <code>ssl_c_sha1</code>: unique per certificate, useful for audit logs.</li>
<li><code>%{+Q}</code>: quotes the value, since DNs contain commas and spaces.</li>
</ul>
<p><code>set-header</code> overwrites any <code>X-Client-*</code> header a client sends itself, so clients cannot fake them.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Client certificate subject (DN)
    http-request set-header X-Client-DN %{+Q}[ssl_c_s_dn]
    
    # Client certificate common name
    http-request set-header X-Client-CN %{+Q}[ssl_c_s_dn(cn)]
    
    # Certificate serial number
    http-request set-header X-Client-Serial %[ssl_c_serial,hex]
    
    # Certificate fingerprint (SHA1)
    http-request set-header X-Client-Fingerprint %[ssl_c_sha1,hex]
    
    # Certificate validity dates
    http-request set-header X-Client-NotBefore %[ssl_c_notbefore]
    http-request set-header X-Client-NotAfter %[ssl_c_notafter]
    
    # Issuer DN
    http-request set-header X-Client-Issuer %{+Q}[ssl_c_i_dn]
    
    # Verification status (0 = success)
    http-request set-header X-Client-Verify %[ssl_c_verify]
    
    default_backend api_servers
</code></pre><h3 id="full-certificate-as-header-base64">Full Certificate as Header (Base64) <a class="anchor" data-pagefind-ignore href="#full-certificate-as-header-base64" aria-label="Link to this section">#</a></h3>
<p>Use this when the application must parse the certificate itself, for example to read custom extensions.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Pass entire certificate (DER format, base64 encoded)
    http-request set-header X-Client-Cert %[ssl_c_der,base64]
    
    default_backend api_servers
</code></pre><h2 id="certificate-based-authorization">Certificate-Based Authorization <a class="anchor" data-pagefind-ignore href="#certificate-based-authorization" aria-label="Link to this section">#</a></h2>
<p>A valid certificate proves who the client is, not what it may do. ACLs on certificate fields add authorization.</p>
<table>
	<thead>
			<tr>
					<th>Match on</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>CN</td>
					<td>Individual services or clients</td>
			</tr>
			<tr>
					<td>OU</td>
					<td>Groups of clients (internal, partner, admin)</td>
			</tr>
			<tr>
					<td>Fingerprint</td>
					<td>An explicit allowlist of exact certificates</td>
			</tr>
	</tbody>
</table>
<h3 id="route-by-client-cn">Route by Client CN <a class="anchor" data-pagefind-ignore href="#route-by-client-cn" aria-label="Link to this section">#</a></h3>
<p>Each named client gets its own backend; everyone else goes to <code>api_backend</code>.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # ACLs based on client certificate CN
    acl cn_admin ssl_c_s_dn(cn) -i admin-service
    acl cn_api ssl_c_s_dn(cn) -i api-client
    acl cn_monitoring ssl_c_s_dn(cn) -i monitoring
    
    # Route to different backends
    use_backend admin_backend if cn_admin
    use_backend monitoring_backend if cn_monitoring
    default_backend api_backend
</code></pre><h3 id="restrict-access-by-certificate-ou">Restrict Access by Certificate OU <a class="anchor" data-pagefind-ignore href="#restrict-access-by-certificate-ou" aria-label="Link to this section">#</a></h3>
<p>Paths are locked to a group: <code>/admin</code> only for the <code>administrators</code> OU, <code>/api/partner</code> only for <code>partner-api</code>.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Check organizational unit
    acl ou_internal ssl_c_s_dn(ou) -i internal-services
    acl ou_partner ssl_c_s_dn(ou) -i partner-api
    acl ou_admin ssl_c_s_dn(ou) -i administrators
    
    # Restrict admin endpoints
    acl admin_path path_beg /admin
    http-request deny if admin_path !ou_admin
    
    # Partner access restrictions
    acl partner_path path_beg /api/partner
    http-request deny if partner_path !ou_partner
    
    default_backend api_servers
</code></pre><h3 id="whitelist-specific-certificates">Whitelist Specific Certificates <a class="anchor" data-pagefind-ignore href="#whitelist-specific-certificates" aria-label="Link to this section">#</a></h3>
<p>The strictest option: only certificates whose SHA1 fingerprint is in the file get through, even if the CA signed others.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Define allowed certificate fingerprints
    acl allowed_cert ssl_c_sha1,hex -f /etc/haproxy/allowed-certs.txt
    
    # Reject certificates not in whitelist
    http-request deny unless allowed_cert
    
    default_backend api_servers
</code></pre><p>Create the whitelist file. A renewed certificate has a new fingerprint, so update the file when you reissue.</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/haproxy/allowed-certs.txt</span>
</span></span><span class="line"><span class="cl"><span class="c1"># One SHA1 fingerprint per line, uppercase hex without colons:</span>
</span></span><span class="line"><span class="cl"><span class="c1">#   openssl x509 -in client.crt -noout -fingerprint -sha1 | cut -d= -f2 | tr -d :</span>
</span></span><span class="line"><span class="cl">A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0
</span></span><span class="line"><span class="cl">9T8S7R6Q5P4O3N2M1L0K9J8I7H6G5F4E3D2C1B0A
</span></span></code></pre></div><h2 id="certificate-revocation">Certificate Revocation <a class="anchor" data-pagefind-ignore href="#certificate-revocation" aria-label="Link to this section">#</a></h2>
<p>A stolen or retired client certificate stays valid until it expires. A CRL lists revoked serial numbers; HAProxy rejects them during the handshake.</p>
<h3 id="using-crl-certificate-revocation-list">Using CRL (Certificate Revocation List) <a class="anchor" data-pagefind-ignore href="#using-crl-certificate-revocation-list" aria-label="Link to this section">#</a></h3>
<p>Revoke the certificate, regenerate the CRL, then load it with <code>crl-file</code> on the bind line.</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"># Generate initial CRL</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -gencrl -out /etc/haproxy/ca/crl/ca.crl
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Revoke a certificate</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -revoke /etc/haproxy/clients/bad-client/bad-client.crt
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Regenerate CRL</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -gencrl -out /etc/haproxy/ca/crl/ca.crl
</span></span></code></pre></div><p>HAProxy reads the CRL at startup, so reload after each change.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    # HAProxy has no line continuation: keep the bind on one line
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt crl-file /etc/haproxy/ca/crl/ca.crl verify required
    
    default_backend api_servers
</code></pre><h3 id="automated-crl-updates">Automated CRL Updates <a class="anchor" data-pagefind-ignore href="#automated-crl-updates" aria-label="Link to this section">#</a></h3>
<p>A CRL expires after <code>default_crl_days</code> (30). An expired CRL makes HAProxy reject every client, so regenerate it on a schedule.</p>
<p>The CA key is encrypted, and cron cannot type its passphrase. Store the passphrase in a file that only root can read, so the script can pass it to openssl with <code>-passin</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="c1"># Same passphrase as the one protecting ca.key</span>
</span></span><span class="line"><span class="cl">install -m <span class="m">0400</span> /dev/null /etc/haproxy/ca/private/ca.pass
</span></span><span class="line"><span class="cl"><span class="nb">read</span> -rsp <span class="s1">&#39;CA key passphrase: &#39;</span> P <span class="o">&amp;&amp;</span> <span class="nb">printf</span> <span class="s1">&#39;%s\n&#39;</span> <span class="s2">&#34;</span><span class="nv">$P</span><span class="s2">&#34;</span> &gt; /etc/haproxy/ca/private/ca.pass<span class="p">;</span> <span class="nb">unset</span> P<span class="p">;</span> <span class="nb">echo</span>
</span></span></code></pre></div><p>Anyone with root on this machine can now sign certificates with your CA, so keep the CA host locked down.</p>
<p>The script writes to a temporary file first, so a failed run never leaves HAProxy with a broken CRL.</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/update-crl.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -euo pipefail
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">CA_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/ca&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">CRL_FILE</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/crl/ca.crl&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">PASS_FILE</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/private/ca.pass&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Regenerate CRL; if openssl fails the script stops here and HAProxy keeps the current CRL</span>
</span></span><span class="line"><span class="cl">openssl ca -config <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/openssl.cnf&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -gencrl -passin <span class="s2">&#34;file:</span><span class="nv">$PASS_FILE</span><span class="s2">&#34;</span> -out <span class="s2">&#34;</span><span class="nv">$CRL_FILE</span><span class="s2">.new&#34;</span>
</span></span><span class="line"><span class="cl">mv <span class="s2">&#34;</span><span class="nv">$CRL_FILE</span><span class="s2">.new&#34;</span> <span class="s2">&#34;</span><span class="nv">$CRL_FILE</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"># Reload HAProxy</span>
</span></span><span class="line"><span class="cl">systemctl reload haproxy
</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">700</span> /usr/local/bin/update-crl.sh
</span></span></code></pre></div><p>Schedule with cron, in root&rsquo;s crontab (<code>crontab -e</code> as root):</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"># Update CRL every hour</span>
</span></span><span class="line"><span class="cl"><span class="m">0</span> * * * * /usr/local/bin/update-crl.sh
</span></span></code></pre></div><h2 id="complete-production-configuration">Complete Production Configuration <a class="anchor" data-pagefind-ignore href="#complete-production-configuration" aria-label="Link to this section">#</a></h2>
<p>Everything combined. The layout:</p>
<table>
	<thead>
			<tr>
					<th>Frontend / listen</th>
					<th>Port</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>stats</code></td>
					<td>8404</td>
					<td>Stats page and Prometheus <code>/metrics</code></td>
			</tr>
			<tr>
					<td><code>public_https</code></td>
					<td>443</td>
					<td>Public site with a public certificate; <code>/api</code> is redirected to 8443</td>
			</tr>
			<tr>
					<td><code>mtls_api</code></td>
					<td>8443</td>
					<td>mTLS with CRL, identity headers, CN/OU authorization</td>
			</tr>
	</tbody>
</table>
<p>The authorization rules in <code>mtls_api</code>:</p>
<ul>
<li><code>/api/admin</code> only for CN <code>admin-service</code>.</li>
<li>CNs containing <code>readonly</code> cannot use POST, PUT, DELETE or PATCH.</li>
<li>Only OU <code>internal</code> or <code>partner</code> gets in at all; partners go to <code>partner_api</code>.</li>
</ul>
<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 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
    option forwardfor
    timeout connect 5s
    timeout client  50s
    timeout server  50s

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

# Public HTTPS (no client cert required)
frontend public_https
    # public.pem: your publicly trusted certificate (for example Let&#39;s Encrypt), not one from the internal CA
    bind *:443 ssl crt /etc/haproxy/certs/public.pem alpn h2,http/1.1
    
    # Route to mTLS frontend for API paths
    acl api_path path_beg /api
    use_backend mtls_redirect if api_path
    
    default_backend public_web

# mTLS API endpoint
frontend mtls_api
    bind *:8443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt crl-file /etc/haproxy/ca/crl/ca.crl verify required alpn h2,http/1.1
    
    # Log client certificate info
    capture request header X-Client-CN len 50
    log-format &#34;%ci:%cp [%tr] %ft %b/%s %ST %B %TR/%Tw/%Tc/%Tr/%Ta client_cn:%{+Q}[ssl_c_s_dn(cn)] %r&#34;
    
    # Add client info headers
    http-request set-header X-Client-CN %{+Q}[ssl_c_s_dn(cn)]
    http-request set-header X-Client-DN %{+Q}[ssl_c_s_dn]
    http-request set-header X-Client-Serial %[ssl_c_serial,hex]
    http-request set-header X-Client-Verify %[ssl_c_verify]
    http-request set-header X-Client-Fingerprint %[ssl_c_sha1,hex]
    
    # Certificate-based authorization
    acl cn_admin ssl_c_s_dn(cn) -i admin-service
    acl cn_readonly ssl_c_s_dn(cn) -m sub readonly
    acl ou_internal ssl_c_s_dn(ou) -i internal
    acl ou_partner ssl_c_s_dn(ou) -i partner
    
    # Path-based ACLs
    acl admin_path path_beg /api/admin
    acl write_method method POST PUT DELETE PATCH
    
    # Authorization rules
    http-request deny if admin_path !cn_admin
    http-request deny if write_method cn_readonly
    http-request deny if !ou_internal !ou_partner
    
    # Route based on certificate
    use_backend admin_api if cn_admin
    use_backend partner_api if ou_partner
    default_backend internal_api

# Redirect to mTLS port
backend mtls_redirect
    http-request redirect code 301 location https://%[req.hdr(Host)]:8443%[capture.req.uri]

backend public_web
    balance roundrobin
    server web1 192.168.1.10:8080 check
    server web2 192.168.1.11:8080 check

backend internal_api
    balance leastconn
    option httpchk GET /health
    http-check expect status 200
    server api1 192.168.1.20:8080 check
    server api2 192.168.1.21:8080 check

backend admin_api
    option httpchk GET /health
    server admin1 192.168.1.30:8080 check

backend partner_api
    balance roundrobin
    option httpchk GET /health
    server partner1 192.168.1.40:8080 check
    server partner2 192.168.1.41:8080 check
</code></pre><h2 id="testing-mtls">Testing mTLS <a class="anchor" data-pagefind-ignore href="#testing-mtls" aria-label="Link to this section">#</a></h2>
<p>Test both sides: a request with a certificate must work, one without must fail.</p>
<h3 id="test-with-curl">Test with curl <a class="anchor" data-pagefind-ignore href="#test-with-curl" 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"># Test with client certificate</span>
</span></span><span class="line"><span class="cl">curl -v <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cert /etc/haproxy/clients/api-client/api-client.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  --key /etc/haproxy/clients/api-client/api-client.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cacert /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://api.example.com:8443/api/status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test with combined PEM</span>
</span></span><span class="line"><span class="cl">curl -v <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cert /etc/haproxy/clients/api-client/api-client.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cacert /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://api.example.com:8443/api/status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test without certificate (should fail)</span>
</span></span><span class="line"><span class="cl">curl -v <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cacert /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://api.example.com:8443/api/status
</span></span></code></pre></div><h3 id="test-with-openssl">Test with openssl <a class="anchor" data-pagefind-ignore href="#test-with-openssl" aria-label="Link to this section">#</a></h3>
<p><code>s_client</code> shows the handshake: the server certificate, whether HAProxy asked for a client certificate, and the verify result.</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"># Connect and show certificate exchange</span>
</span></span><span class="line"><span class="cl">openssl s_client <span class="se">\
</span></span></span><span class="line"><span class="cl">  -connect api.example.com:8443 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -cert /etc/haproxy/clients/api-client/api-client.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key /etc/haproxy/clients/api-client/api-client.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  -CAfile /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -verify_return_error
</span></span></code></pre></div><h2 id="client-configuration-examples">Client Configuration Examples <a class="anchor" data-pagefind-ignore href="#client-configuration-examples" aria-label="Link to this section">#</a></h2>
<p>Every client needs the same three files: its certificate, its key, and the CA certificate to verify HAProxy.</p>
<h3 id="python-requests">Python requests <a class="anchor" data-pagefind-ignore href="#python-requests" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">requests</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">response</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="s1">&#39;https://api.example.com:8443/api/data&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="n">cert</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;/path/to/client.crt&#39;</span><span class="p">,</span> <span class="s1">&#39;/path/to/client.key&#39;</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">    <span class="n">verify</span><span class="o">=</span><span class="s1">&#39;/path/to/ca.crt&#39;</span>
</span></span><span class="line"><span class="cl"><span class="p">)</span>
</span></span></code></pre></div><h3 id="nodejs">Node.js <a class="anchor" data-pagefind-ignore href="#nodejs" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-javascript" data-lang="javascript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">https</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;https&#39;</span><span class="p">);</span>
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">fs</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;fs&#39;</span><span class="p">);</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">options</span> <span class="o">=</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">hostname</span><span class="o">:</span> <span class="s1">&#39;api.example.com&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">port</span><span class="o">:</span> <span class="mi">8443</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">path</span><span class="o">:</span> <span class="s1">&#39;/api/data&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">method</span><span class="o">:</span> <span class="s1">&#39;GET&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">cert</span><span class="o">:</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="s1">&#39;/path/to/client.crt&#39;</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">  <span class="nx">key</span><span class="o">:</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="s1">&#39;/path/to/client.key&#39;</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">  <span class="nx">ca</span><span class="o">:</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="s1">&#39;/path/to/ca.crt&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="p">};</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">req</span> <span class="o">=</span> <span class="nx">https</span><span class="p">.</span><span class="nx">request</span><span class="p">(</span><span class="nx">options</span><span class="p">,</span> <span class="p">(</span><span class="nx">res</span><span class="p">)</span> <span class="p">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="c1">// Handle response
</span></span></span><span class="line"><span class="cl"><span class="p">});</span>
</span></span></code></pre></div><h3 id="go">Go <a class="anchor" data-pagefind-ignore href="#go" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go"><span class="line"><span class="cl"><span class="kn">package</span><span class="w"> </span><span class="nx">main</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="kn">import</span><span class="w"> </span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;crypto/tls&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;crypto/x509&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;io/ioutil&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;net/http&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">)</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="kd">func</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">cert</span><span class="p">,</span><span class="w"> </span><span class="nx">_</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">tls</span><span class="p">.</span><span class="nf">LoadX509KeyPair</span><span class="p">(</span><span class="s">&#34;client.crt&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;client.key&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">caCert</span><span class="p">,</span><span class="w"> </span><span class="nx">_</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">ioutil</span><span class="p">.</span><span class="nf">ReadFile</span><span class="p">(</span><span class="s">&#34;ca.crt&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">caCertPool</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">x509</span><span class="p">.</span><span class="nf">NewCertPool</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">caCertPool</span><span class="p">.</span><span class="nf">AppendCertsFromPEM</span><span class="p">(</span><span class="nx">caCert</span><span class="p">)</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="w">    </span><span class="nx">client</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="o">&amp;</span><span class="nx">http</span><span class="p">.</span><span class="nx">Client</span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nx">Transport</span><span class="p">:</span><span class="w"> </span><span class="o">&amp;</span><span class="nx">http</span><span class="p">.</span><span class="nx">Transport</span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nx">TLSClientConfig</span><span class="p">:</span><span class="w"> </span><span class="o">&amp;</span><span class="nx">tls</span><span class="p">.</span><span class="nx">Config</span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nx">Certificates</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span><span class="nx">tls</span><span class="p">.</span><span class="nx">Certificate</span><span class="p">{</span><span class="nx">cert</span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nx">RootCAs</span><span class="p">:</span><span class="w">      </span><span class="nx">caCertPool</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</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="w">    </span><span class="nx">resp</span><span class="p">,</span><span class="w"> </span><span class="nx">_</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">client</span><span class="p">.</span><span class="nf">Get</span><span class="p">(</span><span class="s">&#34;https://api.example.com:8443/api/data&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// Handle response</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">}</span><span class="w">
</span></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-errors">Common Errors <a class="anchor" data-pagefind-ignore href="#common-errors" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Error</th>
					<th>Cause</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>tlsv1 alert unknown ca</code></td>
					<td>Client certificate not signed by the CA in <code>ca-file</code></td>
			</tr>
			<tr>
					<td><code>SSL certificate verify failed</code></td>
					<td>CA certificate mismatch</td>
			</tr>
			<tr>
					<td><code>tlsv13 alert certificate required</code> (TLS 1.2: handshake failure)</td>
					<td>Client didn&rsquo;t provide certificate when required</td>
			</tr>
			<tr>
					<td><code>ssl/tls alert certificate revoked</code></td>
					<td>Certificate is in CRL</td>
			</tr>
	</tbody>
</table>
<h3 id="debug-commands">Debug Commands <a class="anchor" data-pagefind-ignore href="#debug-commands" 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"># Verify certificate chain</span>
</span></span><span class="line"><span class="cl">openssl verify -CAfile ca.crt client.crt
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check certificate details</span>
</span></span><span class="line"><span class="cl">openssl x509 -in client.crt -text -noout
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check CRL contents</span>
</span></span><span class="line"><span class="cl">openssl crl -in ca.crl -text -noout
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test SSL connection with debug</span>
</span></span><span class="line"><span class="cl">openssl s_client -connect api.example.com:8443 -debug
</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>Protect the CA key.</strong> Whoever has it can mint valid client certificates. Keep it encrypted and the CA host locked down.</li>
<li><strong>Short client lifetimes.</strong> 365 days here; shorter limits the damage of a leaked key.</li>
<li><strong>Keep the CRL fresh.</strong> Run the hourly update; an expired CRL locks everyone out.</li>
<li><strong>Do not trust client headers.</strong> Always overwrite <code>X-Client-*</code> in HAProxy, as above, and make backends reachable only through HAProxy.</li>
<li><strong>Change the PKCS12 password</strong> from <code>changeme</code> in the client script.</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-mtls" rel="noopener">pderuiter/blog-haproxy-mtls</a>. It creates an HAProxy VM on Proxmox, builds the internal CA with server and client certificates, and configures the complete production configuration from this post with certificate-based authorization and the hourly CRL update; put the CA passphrase in <code>vault.yml</code>, run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</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: the HAProxy Data Plane API for dynamic configuration management.</p>
<h2 id="summary">Summary <a class="anchor" data-pagefind-ignore href="#summary" aria-label="Link to this section">#</a></h2>
<p>Key points for HAProxy mTLS:</p>
<ul>
<li>Use <code>verify required</code> for mandatory client certificates</li>
<li>Use <code>verify optional</code> for mixed authentication</li>
<li>Pass certificate details to backends via headers</li>
<li>Implement authorization based on CN, OU, or fingerprint</li>
<li>Maintain CRL for certificate revocation</li>
<li>Generate unique certificates for each client/service</li>
<li>Test thoroughly with curl and openssl</li>
</ul>
<p>mTLS gives strong mutual authentication without passwords, a good fit for service-to-service communication and API access.</p>
]]></content:encoded></item><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>Securing DNS Traffic with DNS over TLS (DoT) on BIND</title><link>https://blog.bsdserver.nl/securing-dns-traffic-with-dns-over-tls-dot-on-bind/</link><guid isPermaLink="false">693b6eb479eb54000160a5a5</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:24:04 +0000</pubDate><description>Traditional DNS queries travel in plaintext, exposing your browsing habits to network observers.</description><category>BIND</category><category>DNS</category><category>DNS over TLS</category><category>TLS</category><category>Security</category><category>Encryption</category><category>Homelab</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/securing-dns-with-DoT.png" medium="image"/><content:encoded><![CDATA[<p>Traditional DNS queries travel in plaintext, exposing your browsing habits to network observers. Anyone on the path can read them, and can change the answers.</p>
<p>DNS over TLS (DoT) encrypts DNS traffic between clients and resolvers, providing privacy and preventing tampering. This post covers implementing DoT on BIND 9 in two roles: as a DoT server for your clients, and as a forwarder that sends its own queries upstream over DoT.</p>
<h2 id="why-dot">Why DoT? <a class="anchor" data-pagefind-ignore href="#why-dot" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Privacy</strong>: ISPs and network observers cannot see DNS queries</li>
<li><strong>Integrity</strong>: Prevents DNS query/response manipulation</li>
<li><strong>Authentication</strong>: Server identity verified via TLS certificates</li>
<li><strong>Compliance</strong>: Helps meet data protection requirements</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 DNS crosses networks you do not trust: Wi-Fi, branch links, the path to a public resolver, or mobile clients using your resolver.</li>
<li><strong>Skip it</strong> on a trusted LAN segment between a client and a resolver next to it. It adds certificates to manage and TCP connections to carry, for little gain.</li>
</ul>
<h3 id="dot-vs-doh">DoT vs DoH <a class="anchor" data-pagefind-ignore href="#dot-vs-doh" aria-label="Link to this section">#</a></h3>
<p>Both encrypt DNS with TLS. The difference is the port, and with it who can see and block the traffic.</p>
<table>
	<thead>
			<tr>
					<th>Feature</th>
					<th>DNS over TLS (DoT)</th>
					<th>DNS over HTTPS (DoH)</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Port</td>
					<td>853 (dedicated)</td>
					<td>443 (shared with HTTPS)</td>
			</tr>
			<tr>
					<td>Protocol</td>
					<td>TLS directly</td>
					<td>HTTP/2 over TLS</td>
			</tr>
			<tr>
					<td>Blockable</td>
					<td>Easily (port 853)</td>
					<td>Harder to distinguish</td>
			</tr>
			<tr>
					<td>Performance</td>
					<td>Better (simpler)</td>
					<td>Slightly more overhead</td>
			</tr>
			<tr>
					<td>Use case</td>
					<td>Network operators</td>
					<td>End users/browsers</td>
			</tr>
	</tbody>
</table>
<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>
<p>DoT wraps standard DNS queries in TLS encryption:</p>
<ol>
<li>Client initiates TLS connection to port 853</li>
<li>TLS handshake establishes encrypted channel</li>
<li>DNS queries and responses flow encrypted</li>
<li>Connection may persist for multiple queries</li>
</ol>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>DoT client</td>
					<td>Laptop, phone, or a local stub (systemd-resolved, Stubby)</td>
					<td>Opens TLS to port 853, checks the server certificate, sends queries.</td>
			</tr>
			<tr>
					<td>BIND DoT listener</td>
					<td>Your resolver</td>
					<td>Terminates TLS with the <code>tls</code> block&rsquo;s certificate and answers as usual.</td>
			</tr>
			<tr>
					<td>BIND DoT forwarder (optional)</td>
					<td>Your resolver</td>
					<td>Sends its own queries to an upstream DoT resolver and checks that server&rsquo;s certificate.</td>
			</tr>
			<tr>
					<td>Upstream resolver</td>
					<td>Cloudflare, Google, Quad9</td>
					<td>Resolves the queries you forward.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client → TLS on 853 → BIND → cache, or recursion / DoT forwarder → answer back over the same TLS connection.</p>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<p>Before configuring DoT, ensure you have:</p>
<ol>
<li>BIND 9.18+ (native DoT listener; forwarding over DoT needs BIND 9.20+) or BIND with stunnel/nginx</li>
<li>Valid TLS certificate (Let&rsquo;s Encrypt works well)</li>
<li>Port 853 accessible through firewall</li>
<li>A working recursive resolver setup</li>
</ol>
<h2 id="native-dot-in-bind-918">Native DoT in BIND 9.18+ <a class="anchor" data-pagefind-ignore href="#native-dot-in-bind-918" aria-label="Link to this section">#</a></h2>
<p>BIND 9.18 and later include native DNS over TLS support (it was developed in the 9.17 development branch). No proxy is needed: a named <code>tls</code> block holds the certificate, and <code>listen-on port 853 tls &lt;name&gt;</code> opens the listener.</p>
<h3 id="basic-dot-listener-configuration">Basic DoT Listener Configuration <a class="anchor" data-pagefind-ignore href="#basic-dot-listener-configuration" aria-label="Link to this section">#</a></h3>
<p>This keeps the plain listener on port 53 and adds a TLS listener on 853 next to it.</p>
<ul>
<li><code>listen-on port 853 tls local-tls</code>: the DoT listener, using the <code>tls local-tls</code> block below.</li>
<li><code>tcp-clients</code>: maximum concurrent TCP connections, DoT included. Raise it, because every DoT client holds a connection open.</li>
<li><code>tcp-keepalive-timeout</code>: how long an idle connection stays open for clients that use EDNS keepalive. In units of 100 ms.</li>
<li><code>dhparam-file</code>: optional, only used by DHE cipher suites.</li>
<li><code>protocols</code> and <code>ciphers</code>: TLS 1.2 and 1.3 only, with ECDHE suites for forward secrecy.</li>
<li><code>prefer-server-ciphers</code>: the server&rsquo;s cipher order wins over the client&rsquo;s.</li>
<li><code>session-tickets</code>: lets clients resume a TLS session without a full handshake.</li>
</ul>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf.options

options {
    directory &#34;/var/cache/bind&#34;;
    
    // Standard DNS listener
    listen-on { 127.0.0.1; 192.168.1.1; };
    listen-on-v6 { ::1; };
    
    // DNS over TLS listener
    listen-on port 853 tls local-tls { 127.0.0.1; 192.168.1.1; };
    listen-on-v6 port 853 tls local-tls { ::1; };
    
    // Resolver settings
    recursion yes;
    allow-recursion { localhost; 192.168.0.0/16; };
    
    dnssec-validation auto;
    
    // Performance tuning for DoT
    tcp-clients 1000;
    tcp-keepalive-timeout 300;    // units of 100 ms: 300 = 30 seconds
};

// TLS configuration
tls local-tls {
    cert-file &#34;/etc/bind/tls/cert.pem&#34;;
    key-file &#34;/etc/bind/tls/key.pem&#34;;
    
    // Optional: Diffie-Hellman parameters for forward secrecy
    dhparam-file &#34;/etc/bind/tls/dhparam.pem&#34;;
    
    // TLS protocol settings
    protocols { TLSv1.2; TLSv1.3; };
    
    // Strong cipher suites
    ciphers &#34;ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305&#34;;
    
    // Prefer server cipher order
    prefer-server-ciphers yes;
    
    // Session resumption
    session-tickets yes;
};
</code></pre><p>Check the file with <code>named-checkconf</code> before reloading.</p>
<h3 id="generating-tls-certificates">Generating TLS Certificates <a class="anchor" data-pagefind-ignore href="#generating-tls-certificates" aria-label="Link to this section">#</a></h3>
<p>BIND needs a certificate whose name matches the hostname your clients use (<code>dns.example.com</code> here).</p>
<table>
	<thead>
			<tr>
					<th>Option</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Let&rsquo;s Encrypt</td>
					<td>Anything clients outside your lab use. Clients that verify the certificate trust it out of the box.</td>
			</tr>
			<tr>
					<td>Self-signed</td>
					<td>Testing only. Clients must skip verification or trust your certificate by hand.</td>
			</tr>
	</tbody>
</table>
<h4 id="using-lets-encrypt">Using Let&rsquo;s Encrypt <a class="anchor" data-pagefind-ignore href="#using-lets-encrypt" aria-label="Link to this section">#</a></h4>
<p>The standalone method briefly runs its own web server on port 80, so that port must be free and reachable. BIND runs as user <code>bind</code> and cannot read the files under <code>/etc/letsencrypt</code>, so copy them to <code>/etc/bind/tls</code> with the right owner.</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 certbot</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"># Obtain certificate (standalone method)</span>
</span></span><span class="line"><span class="cl">certbot certonly --standalone -d dns.example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create directory for BIND</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/bind/tls
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Copy certificates with correct permissions</span>
</span></span><span class="line"><span class="cl">cp /etc/letsencrypt/live/dns.example.com/fullchain.pem /etc/bind/tls/cert.pem
</span></span><span class="line"><span class="cl">cp /etc/letsencrypt/live/dns.example.com/privkey.pem /etc/bind/tls/key.pem
</span></span><span class="line"><span class="cl">chown bind:bind /etc/bind/tls/*.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/bind/tls/*.pem
</span></span></code></pre></div><h4 id="auto-renewal-hook">Auto-renewal Hook <a class="anchor" data-pagefind-ignore href="#auto-renewal-hook" aria-label="Link to this section">#</a></h4>
<p>Let&rsquo;s Encrypt certificates last 90 days. certbot runs scripts in <code>renewal-hooks/deploy/</code> after each successful renewal; this one copies the new files and reloads BIND.</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/bind-tls.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">DOMAIN</span><span class="o">=</span><span class="s2">&#34;dns.example.com&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">BIND_TLS_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/bind/tls&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Copy new certificates</span>
</span></span><span class="line"><span class="cl">cp /etc/letsencrypt/live/<span class="nv">$DOMAIN</span>/fullchain.pem <span class="nv">$BIND_TLS_DIR</span>/cert.pem
</span></span><span class="line"><span class="cl">cp /etc/letsencrypt/live/<span class="nv">$DOMAIN</span>/privkey.pem <span class="nv">$BIND_TLS_DIR</span>/key.pem
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set permissions</span>
</span></span><span class="line"><span class="cl">chown bind:bind <span class="nv">$BIND_TLS_DIR</span>/*.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> <span class="nv">$BIND_TLS_DIR</span>/*.pem
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload BIND</span>
</span></span><span class="line"><span class="cl">rndc reload
</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;BIND TLS certificates updated&#34;</span>
</span></span></code></pre></div><p>Make the hook executable, certbot skips hooks that are not:</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/bind-tls.sh
</span></span></code></pre></div><h4 id="self-signed-certificate-testing-only">Self-Signed Certificate (Testing Only) <a class="anchor" data-pagefind-ignore href="#self-signed-certificate-testing-only" aria-label="Link to this section">#</a></h4>
<p>Creates a key, a certificate valid for a year and DH parameters in <code>/etc/bind/tls</code>, with the same names and permissions as above.</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"># Generate self-signed certificate for testing</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">mkdir -p /etc/bind/tls
</span></span><span class="line"><span class="cl"><span class="nb">cd</span> /etc/bind/tls
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate private key</span>
</span></span><span class="line"><span class="cl">openssl genrsa -out key.pem <span class="m">4096</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate certificate signing request</span>
</span></span><span class="line"><span class="cl">openssl req -new -key key.pem -out cert.csr <span class="se">\
</span></span></span><span class="line"><span class="cl">    -subj <span class="s2">&#34;/CN=dns.example.com/O=Example/C=US&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Self-sign certificate (valid for 365 days)</span>
</span></span><span class="line"><span class="cl">openssl x509 -req -days <span class="m">365</span> -in cert.csr <span class="se">\
</span></span></span><span class="line"><span class="cl">    -signkey key.pem -out cert.pem
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate DH parameters (optional but recommended)</span>
</span></span><span class="line"><span class="cl">openssl dhparam -out dhparam.pem <span class="m">2048</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set permissions</span>
</span></span><span class="line"><span class="cl">chown bind:bind *.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> *.pem
</span></span></code></pre></div><h2 id="dot-forwarding-configuration">DoT Forwarding Configuration <a class="anchor" data-pagefind-ignore href="#dot-forwarding-configuration" aria-label="Link to this section">#</a></h2>
<p>The other direction: BIND sends its own upstream queries over DoT. Use it when you forward to a public resolver and do not want your ISP to see those queries. This needs BIND 9.20+.</p>
<ul>
<li><code>forward only</code>: never fall back to plain recursion. If the DoT forwarders fail, clients get SERVFAIL.</li>
<li><code>forwarders port 853 tls upstream-dot</code>: send queries to these servers over TLS, checked with the <code>upstream-dot</code> block.</li>
<li><code>ca-file</code>: the CA bundle used to verify the upstream certificate.</li>
<li><code>remote-hostname</code>: the name that must be in the upstream certificate. Without it, the connection is encrypted but you do not know who you are talking to.</li>
</ul>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf.options

options {
    directory &#34;/var/cache/bind&#34;;
    
    // Listen for queries from local network
    listen-on { 127.0.0.1; 192.168.1.1; };
    listen-on-v6 { ::1; };
    
    recursion yes;
    allow-recursion { localhost; 192.168.0.0/16; };
    
    // Forward all queries via DoT (BIND 9.20+)
    forward only;
    forwarders port 853 tls upstream-dot {
        1.1.1.1;          // Cloudflare
        1.0.0.1;          // Cloudflare secondary
    };
    
    dnssec-validation auto;
};

// TLS configuration for upstream servers
tls upstream-dot {
    // CA bundle for verifying upstream certificates
    ca-file &#34;/etc/ssl/certs/ca-certificates.crt&#34;;
    
    // Hostname verification (important for security)
    remote-hostname &#34;cloudflare-dns.com&#34;;
    
    // Only use TLS 1.2 and 1.3
    protocols { TLSv1.2; TLSv1.3; };
};
</code></pre><p><code>remote-hostname</code> is checked against every server that uses this <code>tls</code> block, so only list servers that present that certificate name. Adding Google or Quad9 here makes their certificate checks fail, and with <code>forward only</code> the resolver then returns SERVFAIL. BIND 9.18 does not accept <code>tls</code> on <code>forwarders</code> at all; it is a syntax error there.</p>
<h3 id="multiple-upstream-providers-with-different-tls-settings">Multiple Upstream Providers with Different TLS Settings <a class="anchor" data-pagefind-ignore href="#multiple-upstream-providers-with-different-tls-settings" aria-label="Link to this section">#</a></h3>
<p>The fix for that limitation: one <code>tls</code> block per provider, each with its own <code>remote-hostname</code>. A forward zone can then use a different provider than the global forwarders.</p>
<table>
	<thead>
			<tr>
					<th>Setting</th>
					<th>Behaviour when the forwarders fail</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>forward only</code></td>
					<td>SERVFAIL</td>
					<td>Queries must never leave unencrypted</td>
			</tr>
			<tr>
					<td><code>forward first</code></td>
					<td>BIND resolves the query itself, from the root servers, without TLS</td>
					<td>Availability matters more than privacy</td>
			</tr>
	</tbody>
</table>
<pre tabindex="0"><code class="language-named" data-lang="named">// Different TLS configs for different providers
tls cloudflare-tls {
    ca-file &#34;/etc/ssl/certs/ca-certificates.crt&#34;;
    remote-hostname &#34;cloudflare-dns.com&#34;;
};

tls google-tls {
    ca-file &#34;/etc/ssl/certs/ca-certificates.crt&#34;;
    remote-hostname &#34;dns.google&#34;;
};

tls quad9-tls {
    ca-file &#34;/etc/ssl/certs/ca-certificates.crt&#34;;
    remote-hostname &#34;dns.quad9.net&#34;;
};

options {
    // Primary: Cloudflare
    forwarders port 853 tls cloudflare-tls {
        1.1.1.1;
        1.0.0.1;
    };
    
    forward first;  // Fall back to root servers if forwarders fail
};

// Alternative: Split forwarding by zone
zone &#34;example.com&#34; {
    type forward;
    forward only;
    forwarders port 853 tls google-tls { 8.8.8.8; };
};
</code></pre><h2 id="dot-with-stunnel-for-older-bind-versions">DoT with stunnel (For Older BIND Versions) <a class="anchor" data-pagefind-ignore href="#dot-with-stunnel-for-older-bind-versions" aria-label="Link to this section">#</a></h2>
<p>If running BIND &lt; 9.18 (or BIND 9.18, which cannot forward over DoT), use stunnel as a TLS wrapper. stunnel handles the TLS; BIND keeps talking plain DNS on the local host.</p>
<h3 id="stunnel-server-configuration">stunnel Server Configuration <a class="anchor" data-pagefind-ignore href="#stunnel-server-configuration" aria-label="Link to this section">#</a></h3>
<p>Accepts DoT on port 853 and passes the decrypted queries to BIND on <code>127.0.0.1:53</code>. Use this for the listener side on BIND &lt; 9.18.</p>
<ul>
<li><code>accept</code> / <code>connect</code>: the TLS port, and where the plain queries go.</li>
<li><code>options = NO_SSLv2</code> / <code>NO_SSLv3</code> and <code>sslVersion</code>: keep old protocols out.</li>
</ul>
<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/stunnel/dns-dot.conf</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">; Global settings</span>
</span></span><span class="line"><span class="cl"><span class="na">setuid</span> <span class="o">=</span> <span class="s">stunnel4</span>
</span></span><span class="line"><span class="cl"><span class="na">setgid</span> <span class="o">=</span> <span class="s">stunnel4</span>
</span></span><span class="line"><span class="cl"><span class="na">pid</span> <span class="o">=</span> <span class="s">/var/run/stunnel4/dns-dot.pid</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">; Logging</span>
</span></span><span class="line"><span class="cl"><span class="na">output</span> <span class="o">=</span> <span class="s">/var/log/stunnel4/dns-dot.log</span>
</span></span><span class="line"><span class="cl"><span class="na">debug</span> <span class="o">=</span> <span class="s">notice</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">; DoT server - accepts TLS connections, forwards to local BIND</span>
</span></span><span class="line"><span class="cl"><span class="k">[dns-dot-server]</span>
</span></span><span class="line"><span class="cl"><span class="na">accept</span> <span class="o">=</span> <span class="s">853</span>
</span></span><span class="line"><span class="cl"><span class="na">connect</span> <span class="o">=</span> <span class="s">127.0.0.1:53</span>
</span></span><span class="line"><span class="cl"><span class="na">cert</span> <span class="o">=</span> <span class="s">/etc/stunnel/cert.pem</span>
</span></span><span class="line"><span class="cl"><span class="na">key</span> <span class="o">=</span> <span class="s">/etc/stunnel/key.pem</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">; TLS options</span>
</span></span><span class="line"><span class="cl"><span class="na">options</span> <span class="o">=</span> <span class="s">NO_SSLv2</span>
</span></span><span class="line"><span class="cl"><span class="na">options</span> <span class="o">=</span> <span class="s">NO_SSLv3</span>
</span></span><span class="line"><span class="cl"><span class="na">options</span> <span class="o">=</span> <span class="s">SINGLE_DH_USE</span>
</span></span><span class="line"><span class="cl"><span class="na">options</span> <span class="o">=</span> <span class="s">SINGLE_ECDH_USE</span>
</span></span><span class="line"><span class="cl"><span class="na">ciphers</span> <span class="o">=</span> <span class="s">ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">; Protocol version</span>
</span></span><span class="line"><span class="cl"><span class="na">sslVersion</span> <span class="o">=</span> <span class="s">TLSv1.2</span>
</span></span></code></pre></div><h3 id="stunnel-client-configuration-dot-forwarding">stunnel Client Configuration (DoT Forwarding) <a class="anchor" data-pagefind-ignore href="#stunnel-client-configuration-dot-forwarding" aria-label="Link to this section">#</a></h3>
<p>The forwarding side. Each section gives one upstream DoT server a local plain address (<code>127.0.0.2</code>, <code>127.0.0.3</code>) that BIND can forward to.</p>
<ul>
<li><code>client = yes</code>: stunnel opens the TLS connection instead of accepting it.</li>
<li><code>verifyChain</code>, <code>CAfile</code>, <code>checkHost</code>: verify the upstream certificate and its name, like <code>remote-hostname</code> in BIND.</li>
</ul>
<p>Because each section has its own <code>checkHost</code>, mixing providers works here.</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/stunnel/dns-dot-client.conf</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[dns-dot-cloudflare]</span>
</span></span><span class="line"><span class="cl"><span class="c1">; Local plain DNS listener</span>
</span></span><span class="line"><span class="cl"><span class="na">accept</span> <span class="o">=</span> <span class="s">127.0.0.2:53</span>
</span></span><span class="line"><span class="cl"><span class="c1">; Remote DoT server</span>
</span></span><span class="line"><span class="cl"><span class="na">connect</span> <span class="o">=</span> <span class="s">1.1.1.1:853</span>
</span></span><span class="line"><span class="cl"><span class="na">client</span> <span class="o">=</span> <span class="s">yes</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">; Verify server certificate</span>
</span></span><span class="line"><span class="cl"><span class="na">verifyChain</span> <span class="o">=</span> <span class="s">yes</span>
</span></span><span class="line"><span class="cl"><span class="na">CAfile</span> <span class="o">=</span> <span class="s">/etc/ssl/certs/ca-certificates.crt</span>
</span></span><span class="line"><span class="cl"><span class="na">checkHost</span> <span class="o">=</span> <span class="s">cloudflare-dns.com</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[dns-dot-google]</span>
</span></span><span class="line"><span class="cl"><span class="na">accept</span> <span class="o">=</span> <span class="s">127.0.0.3:53</span>
</span></span><span class="line"><span class="cl"><span class="na">connect</span> <span class="o">=</span> <span class="s">8.8.8.8:853</span>
</span></span><span class="line"><span class="cl"><span class="na">client</span> <span class="o">=</span> <span class="s">yes</span>
</span></span><span class="line"><span class="cl"><span class="na">verifyChain</span> <span class="o">=</span> <span class="s">yes</span>
</span></span><span class="line"><span class="cl"><span class="na">CAfile</span> <span class="o">=</span> <span class="s">/etc/ssl/certs/ca-certificates.crt</span>
</span></span><span class="line"><span class="cl"><span class="na">checkHost</span> <span class="o">=</span> <span class="s">dns.google</span>
</span></span></code></pre></div><p>Then configure BIND to forward to stunnel. The <code>server</code> statements make BIND use TCP towards the proxies:</p>
<pre tabindex="0"><code class="language-named" data-lang="named">// Forward to local stunnel proxies
options {
    forwarders {
        127.0.0.2;  // stunnel -&gt; Cloudflare DoT
        127.0.0.3;  // stunnel -&gt; Google DoT
    };
    forward only;
};

// stunnel only accepts TCP, so make BIND use TCP towards it
server 127.0.0.2 { tcp-only yes; };
server 127.0.0.3 { tcp-only yes; };
</code></pre><h2 id="performance-optimization">Performance Optimization <a class="anchor" data-pagefind-ignore href="#performance-optimization" aria-label="Link to this section">#</a></h2>
<p>DoT runs over TCP with a TLS handshake per connection. Performance comes down to keeping connections open and reusing them.</p>
<h3 id="connection-pooling">Connection Pooling <a class="anchor" data-pagefind-ignore href="#connection-pooling" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>tcp-keepalive-timeout 600</code>: idle connections stay open for 60 seconds, so a client can send its next query without a new handshake.</li>
<li><code>tcp-clients 2000</code>: room for more open connections. Each costs memory, so size it to your client count.</li>
</ul>
<p>The TCP fast open comment is only a reminder: it is a kernel setting, not a BIND option.</p>
<pre tabindex="0"><code class="language-named" data-lang="named">options {
    // Keep TCP/TLS connections open longer (units of 100 ms: 600 = 60 seconds)
    tcp-keepalive-timeout 600;
    
    // Allow more concurrent TCP/TLS connections
    tcp-clients 2000;
    
    // Enable TCP fast open if supported
    // (kernel must support it: sysctl net.ipv4.tcp_fastopen=3)
};
</code></pre><h3 id="query-pipelining">Query Pipelining <a class="anchor" data-pagefind-ignore href="#query-pipelining" aria-label="Link to this section">#</a></h3>
<p>Modern DoT clients can send multiple queries over a single TLS connection. On the BIND side the one TLS setting that helps is <code>session-tickets</code>: a client that does reconnect resumes its session instead of doing a full handshake.</p>
<pre tabindex="0"><code class="language-named" data-lang="named">tls local-tls {
    cert-file &#34;/etc/bind/tls/cert.pem&#34;;
    key-file &#34;/etc/bind/tls/key.pem&#34;;
    
    // Enable session resumption for faster reconnects
    session-tickets yes;
};
</code></pre><h3 id="monitoring-dot-performance">Monitoring DoT Performance <a class="anchor" data-pagefind-ignore href="#monitoring-dot-performance" aria-label="Link to this section">#</a></h3>
<p>Quick checks from a client: a DoT query with <code>kdig</code> and with <code>dog</code>, and the TLS protocol and cipher the server negotiates.</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"># Test DoT response time</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">DOT_SERVER</span><span class="o">=</span><span class="s2">&#34;dns.example.com&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test with kdig (knot-dnsutils)</span>
</span></span><span class="line"><span class="cl">kdig +tls @<span class="nv">$DOT_SERVER</span> example.com A
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Measure TLS handshake time</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="p">|</span> openssl s_client -connect <span class="nv">$DOT_SERVER</span>:853 2&gt;<span class="p">&amp;</span><span class="m">1</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    grep -E <span class="s2">&#34;(Verify return|Protocol|Cipher)&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test with dog (modern dig alternative)</span>
</span></span><span class="line"><span class="cl">dog --tls @<span class="nv">$DOT_SERVER</span> example.com A
</span></span></code></pre></div><h2 id="firewall-configuration">Firewall Configuration <a class="anchor" data-pagefind-ignore href="#firewall-configuration" aria-label="Link to this section">#</a></h2>
<p>Open TCP 853 inbound for clients and outbound if you forward over DoT. Both versions below also limit each source address to about 100 new DoT connections a minute, so one client cannot exhaust <code>tcp-clients</code>. The rate limit must come before the accept rule.</p>
<h3 id="iptables-rules">iptables Rules <a class="anchor" data-pagefind-ignore href="#iptables-rules" 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="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># Allow DoT traffic</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Rate limiting to prevent abuse (must come before the ACCEPT rule)</span>
</span></span><span class="line"><span class="cl">iptables -A INPUT -p tcp --dport <span class="m">853</span> -m state --state NEW <span class="se">\
</span></span></span><span class="line"><span class="cl">    -m recent --set --name DOT
</span></span><span class="line"><span class="cl">iptables -A INPUT -p tcp --dport <span class="m">853</span> -m state --state NEW <span class="se">\
</span></span></span><span class="line"><span class="cl">    -m recent --update --seconds <span class="m">60</span> --hitcount <span class="m">100</span> --name DOT -j DROP
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Allow incoming DoT (port 853)</span>
</span></span><span class="line"><span class="cl">iptables -A INPUT -p tcp --dport <span class="m">853</span> -j ACCEPT
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Allow outgoing DoT to upstream resolvers</span>
</span></span><span class="line"><span class="cl">iptables -A OUTPUT -p tcp --dport <span class="m">853</span> -j ACCEPT
</span></span></code></pre></div><h3 id="nftables-rules">nftables Rules <a class="anchor" data-pagefind-ignore href="#nftables-rules" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-nftables" data-lang="nftables">#!/usr/sbin/nft -f

table inet filter {
    chain input {
        type filter hook input priority 0; policy accept;

        # Rate limit new DoT connections (must come before the accept)
        tcp dport 853 ct state new meter dot-meter { ip saddr limit rate over 100/minute } drop

        # Allow DoT
        tcp dport 853 accept
    }
    
    chain output {
        type filter hook output priority 0; policy accept;

        # Allow outgoing DoT
        tcp dport 853 accept
    }
}
</code></pre><h2 id="client-configuration">Client Configuration <a class="anchor" data-pagefind-ignore href="#client-configuration" aria-label="Link to this section">#</a></h2>
<p>A client must know two things: the resolver&rsquo;s address and the name in its certificate. Without the name it cannot verify the server.</p>
<table>
	<thead>
			<tr>
					<th>Client</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>systemd-resolved</td>
					<td>Linux desktops and servers that already use it</td>
			</tr>
			<tr>
					<td>Android Private DNS</td>
					<td>Phones (needs a hostname, not an IP)</td>
			</tr>
			<tr>
					<td>Stubby</td>
					<td>Any system: a local stub that speaks plain DNS to apps and DoT upstream</td>
			</tr>
	</tbody>
</table>
<h3 id="systemd-resolved">systemd-resolved <a class="anchor" data-pagefind-ignore href="#systemd-resolved" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>DNS=192.168.1.1#dns.example.com</code>: the address, and after <code>#</code> the name to verify in the certificate.</li>
<li><code>DNSOverTLS=yes</code>: strict mode. If TLS fails, resolution fails. <code>opportunistic</code> falls back to plain DNS instead.</li>
<li><code>DNSSEC=yes</code>: validate answers as well.</li>
</ul>
<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/resolved.conf</span>
</span></span><span class="line"><span class="cl"><span class="k">[Resolve]</span>
</span></span><span class="line"><span class="cl"><span class="na">DNS</span><span class="o">=</span><span class="s">192.168.1.1#dns.example.com</span>
</span></span><span class="line"><span class="cl"><span class="na">DNSOverTLS</span><span class="o">=</span><span class="s">yes</span>
</span></span><span class="line"><span class="cl"><span class="na">DNSSEC</span><span class="o">=</span><span class="s">yes</span>
</span></span></code></pre></div><h3 id="android-private-dns">Android Private DNS <a class="anchor" data-pagefind-ignore href="#android-private-dns" aria-label="Link to this section">#</a></h3>
<ol>
<li>Settings -&gt; Network &amp; Internet -&gt; Advanced -&gt; Private DNS</li>
<li>Enter: <code>dns.example.com</code></li>
</ol>
<h3 id="stubby-general-purpose-dot-client">Stubby (General-Purpose DoT Client) <a class="anchor" data-pagefind-ignore href="#stubby-general-purpose-dot-client" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>dns_transport_list: GETDNS_TRANSPORT_TLS</code> with <code>tls_authentication: GETDNS_AUTHENTICATION_REQUIRED</code>: TLS only, with a valid certificate. No plain fallback.</li>
<li><code>tls_query_padding_blocksize</code>: pads queries to a fixed block size, so their length gives less away.</li>
<li><code>listen_addresses</code>: where local applications (or a local BIND) send plain queries.</li>
<li><code>tls_auth_name</code>: the name checked in the resolver&rsquo;s certificate.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># /etc/stubby/stubby.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">resolution_type</span><span class="p">:</span><span class="w"> </span><span class="l">GETDNS_RESOLUTION_STUB</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">dns_transport_list</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="l">GETDNS_TRANSPORT_TLS</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">tls_authentication</span><span class="p">:</span><span class="w"> </span><span class="l">GETDNS_AUTHENTICATION_REQUIRED</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">tls_query_padding_blocksize</span><span class="p">:</span><span class="w"> </span><span class="m">128</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">edns_client_subnet_private</span><span class="p">:</span><span class="w"> </span><span class="m">1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">idle_timeout</span><span class="p">:</span><span class="w"> </span><span class="m">10000</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">listen_addresses</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="m">127.0.0.1</span>@<span class="m">53000</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">upstream_recursive_servers</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_data</span><span class="p">:</span><span class="w"> </span><span class="m">192.168.1.1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">tls_auth_name</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;dns.example.com&#34;</span><span class="w">
</span></span></span></code></pre></div><h2 id="complete-production-configuration">Complete Production Configuration <a class="anchor" data-pagefind-ignore href="#complete-production-configuration" aria-label="Link to this section">#</a></h2>
<p>Here&rsquo;s a complete DoT-enabled resolver configuration. It combines the pieces above and adds:</p>
<ul>
<li><code>acl trusted</code> with <code>allow-query</code> and <code>allow-recursion</code>: only your networks may use the resolver, over port 53 or 853.</li>
<li><code>version none</code> and <code>hostname none</code>: do not reveal the BIND version or host name to <code>CHAOS</code> queries.</li>
<li>Upstream DoT forwarding, commented out. Enable it on BIND 9.20+.</li>
<li>A <code>tls_log</code> channel for the <code>network</code> category, for connection problems.</li>
</ul>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf

acl trusted {
    localhost;
    192.168.0.0/16;
    10.0.0.0/8;
};

options {
    directory &#34;/var/cache/bind&#34;;
    
    // Standard DNS
    listen-on { 127.0.0.1; 192.168.1.1; };
    listen-on-v6 { ::1; };
    
    // DNS over TLS
    listen-on port 853 tls dot-server { 127.0.0.1; 192.168.1.1; };
    listen-on-v6 port 853 tls dot-server { ::1; };
    
    // Access control
    allow-query { trusted; };
    allow-recursion { trusted; };
    recursion yes;
    
    // DNSSEC
    dnssec-validation auto;
    
    // Performance
    tcp-clients 2000;
    tcp-keepalive-timeout 600;    // units of 100 ms: 600 = 60 seconds
    
    // Security
    version none;
    hostname none;
    
    // Forward to upstream DoT (optional, BIND 9.20+)
    // forwarders port 853 tls upstream-dot { 1.1.1.1; 1.0.0.1; };
    // forward first;
};

// Server TLS configuration
tls dot-server {
    cert-file &#34;/etc/bind/tls/cert.pem&#34;;
    key-file &#34;/etc/bind/tls/key.pem&#34;;
    dhparam-file &#34;/etc/bind/tls/dhparam.pem&#34;;
    protocols { TLSv1.2; TLSv1.3; };
    ciphers &#34;ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305&#34;;
    prefer-server-ciphers yes;
    session-tickets yes;
};

// Upstream DoT configuration (for forwarding)
tls upstream-dot {
    ca-file &#34;/etc/ssl/certs/ca-certificates.crt&#34;;
    remote-hostname &#34;cloudflare-dns.com&#34;;
    protocols { TLSv1.2; TLSv1.3; };
};

logging {
    channel tls_log {
        file &#34;/var/log/named/tls.log&#34; versions 5 size 10m;
        severity info;
        print-time yes;
        print-category yes;
    };
    category network { tls_log; };
};
</code></pre><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<h3 id="test-dot-connectivity">Test DoT Connectivity <a class="anchor" data-pagefind-ignore href="#test-dot-connectivity" aria-label="Link to this section">#</a></h3>
<p>Start from the client: does a DoT query work, and what does the TLS handshake show?</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"># Test with kdig</span>
</span></span><span class="line"><span class="cl">kdig +tls @dns.example.com example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test with openssl</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> -e <span class="s2">&#34;\x00\x1e\x00\x00\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x07example\x03com\x00\x00\x01\x00\x01&#34;</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    openssl s_client -connect dns.example.com:853 -quiet
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verbose TLS handshake</span>
</span></span><span class="line"><span class="cl">openssl s_client -connect dns.example.com:853 -status -tlsextdebug
</span></span></code></pre></div><h3 id="common-issues">Common Issues <a class="anchor" data-pagefind-ignore href="#common-issues" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
					<th>Check</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Client reports a certificate error</td>
					<td>Expired certificate, missing intermediate, or wrong name</td>
					<td>Certificate commands below</td>
			</tr>
			<tr>
					<td>BIND does not start after adding <code>tls</code></td>
					<td>BIND cannot read the key or certificate</td>
					<td>Permission commands below</td>
			</tr>
			<tr>
					<td>Connection refused on 853</td>
					<td>No listener, or the firewall drops it</td>
					<td>Connection commands below</td>
			</tr>
			<tr>
					<td>SERVFAIL with DoT forwarding</td>
					<td><code>remote-hostname</code> does not match an upstream&rsquo;s certificate</td>
					<td>One <code>tls</code> block per provider</td>
			</tr>
	</tbody>
</table>
<p><strong>Certificate errors:</strong></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"># Check certificate validity</span>
</span></span><span class="line"><span class="cl">openssl x509 -in /etc/bind/tls/cert.pem -text -noout <span class="p">|</span> grep -A2 Validity
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify certificate chain (cert.pem is the full chain, pass it as -untrusted for the intermediate)</span>
</span></span><span class="line"><span class="cl">openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted /etc/bind/tls/cert.pem /etc/bind/tls/cert.pem
</span></span></code></pre></div><p><strong>Permission errors:</strong></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"># Ensure BIND can read certificates</span>
</span></span><span class="line"><span class="cl">ls -la /etc/bind/tls/
</span></span><span class="line"><span class="cl">chown bind:bind /etc/bind/tls/*.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/bind/tls/*.pem
</span></span></code></pre></div><p><strong>Connection refused:</strong></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"># Check if BIND is listening on 853</span>
</span></span><span class="line"><span class="cl">ss -tlnp <span class="p">|</span> grep <span class="m">853</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check firewall</span>
</span></span><span class="line"><span class="cl">iptables -L INPUT -n <span class="p">|</span> grep <span class="m">853</span>
</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>Use valid certificates</strong>: self-signed certificates don&rsquo;t provide authentication.</li>
<li><strong>Enable DNSSEC</strong>: DoT encrypts transport, DNSSEC authenticates content.</li>
<li><strong>Restrict TLS versions</strong>: only allow TLS 1.2 and 1.3.</li>
<li><strong>Monitor certificate expiry</strong>: set up alerts before certificates expire.</li>
<li><strong>Use strong cipher suites</strong>: prefer ECDHE for forward secrecy.</li>
<li><strong>Rate limit connections</strong>: prevent DoS attacks on port 853.</li>
<li><strong>Log TLS events</strong>: monitor for connection failures and attacks.</li>
<li><strong>Mind <code>forward first</code></strong>: when the DoT forwarders fail, queries leave unencrypted.</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-bind-dot-secure" rel="noopener">pderuiter/blog-bind-dot-secure</a>. It creates an Ubuntu 24.04 VM on Proxmox and configures BIND with the DoT listener from the complete configuration above, with optional DoT forwarding to Cloudflare (BIND 9.20 from the ISC packages) and the nftables rate limit; run <code>terraform apply</code> and 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>With BIND 9.18+ the DoT listener is native; DoT forwarding needs 9.20+. On older versions, stunnel does the TLS for BIND.</p>
<p>Key takeaways:</p>
<ul>
<li>Use valid TLS certificates from a trusted CA</li>
<li>Enable both server-side DoT (for clients) and client-side DoT (for upstream forwarding)</li>
<li>Set <code>remote-hostname</code> per upstream provider</li>
<li>Monitor and maintain certificate renewals</li>
</ul>
<p>The next post will cover DNS over HTTPS (DoH), which provides similar encryption using HTTPS and is increasingly supported by browsers and applications.</p>
]]></content:encoded></item></channel></rss>