<?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>HTTP headers | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/headers/</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/headers/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title>HAProxy HTTP Headers Debugging: A Complete Troubleshooting Guide</title><link>https://blog.bsdserver.nl/haproxy-http-headers-debugging-a-complete-troubleshooting-guide/</link><guid isPermaLink="false">693b73ab79eb54000160a5fe</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:45:15 +0000</pubDate><description>When applications misbehave behind a load balancer, HTTP headers are often the culprit.</description><category>HAProxy</category><category>HTTP</category><category>Debugging</category><category>HTTP headers</category><category>Troubleshooting</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/haproxy-http-headers-debugging.png" medium="image"/><content:encoded><![CDATA[<p>When applications misbehave behind a load balancer, HTTP headers are often the culprit. Redirect loops, wrong client IPs in logs, lost sessions and blocked browser requests usually trace back to a header that is missing, wrong or doubled.</p>
<p>This guide shows how to see the headers HAProxy receives and sends, and how to set, remove and route on them. It ends with a complete debug configuration you can drop on a test load balancer.</p>
<h2 id="why-header-debugging-matters">Why Header Debugging Matters <a class="anchor" data-pagefind-ignore href="#why-header-debugging-matters" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Header</th>
					<th>Carries</th>
					<th>Typical symptom when wrong</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>X-Forwarded-For</code></td>
					<td>Client IP</td>
					<td>The app logs the load balancer&rsquo;s IP</td>
			</tr>
			<tr>
					<td><code>X-Forwarded-Proto</code></td>
					<td><code>http</code> or <code>https</code></td>
					<td>Redirect loops, <code>http://</code> links behind TLS</td>
			</tr>
			<tr>
					<td><code>Host</code></td>
					<td>The requested site</td>
					<td>Wrong virtual host or backend</td>
			</tr>
			<tr>
					<td><code>Cookie</code> / <code>Set-Cookie</code></td>
					<td>Sessions, persistence</td>
					<td>Users logged out, sticky sessions lost</td>
			</tr>
			<tr>
					<td><code>Cache-Control</code>, <code>ETag</code></td>
					<td>Caching</td>
					<td>Stale or uncached content</td>
			</tr>
			<tr>
					<td>CORS, CSP, HSTS</td>
					<td>Browser security policies</td>
					<td>The browser blocks requests</td>
			</tr>
			<tr>
					<td><code>Authorization</code></td>
					<td>Credentials</td>
					<td>Unexpected 401s</td>
			</tr>
	</tbody>
</table>
<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> while troubleshooting, and in staging: captures, debug endpoints and <code>haproxy -d</code> show exactly what passes through.</li>
<li><strong>Skip it</strong> in production beyond a few captured headers. Debug endpoints and full header logs expose cookies and tokens.</li>
</ul>
<h2 id="how-it-works">How it works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<p>HAProxy processes headers at fixed points. Knowing which rule runs where explains most &ldquo;my header is not there&rdquo; problems.</p>
<table>
	<thead>
			<tr>
					<th>Directive</th>
					<th>Runs on</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>capture request/response header</code></td>
					<td>Requests and responses, frontend only</td>
					<td>Writing chosen headers to the log</td>
			</tr>
			<tr>
					<td><code>http-request</code></td>
					<td>Requests, before they go to a backend</td>
					<td>Setting, removing and routing on request headers; returning answers directly</td>
			</tr>
			<tr>
					<td><code>http-response</code></td>
					<td>Responses from the servers</td>
					<td>Security headers, removing <code>Server</code></td>
			</tr>
			<tr>
					<td><code>http-after-response</code></td>
					<td>Every response, also HAProxy&rsquo;s own (<code>http-request return</code>, errors)</td>
					<td>Headers that must be on every answer</td>
			</tr>
	</tbody>
</table>
<p>The flow: client → frontend (<code>capture</code>, <code>http-request</code>) → backend → server → <code>http-response</code> → <code>http-after-response</code> → client.</p>
<p>The debugging tools in this post:</p>
<table>
	<thead>
			<tr>
					<th>Tool</th>
					<th>Shows</th>
					<th>Use it when</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Header captures in the log</td>
					<td>Chosen headers per request</td>
					<td>Always on, also in production</td>
			</tr>
			<tr>
					<td><code>haproxy -d</code></td>
					<td>All traffic, live</td>
					<td>In a lab only: the service is stopped</td>
			</tr>
			<tr>
					<td>Debug backend (netcat, Python)</td>
					<td>Headers as the server receives them</td>
					<td>Checking what HAProxy adds or changes</td>
			</tr>
			<tr>
					<td><code>http-request return</code> endpoint</td>
					<td>Headers as HAProxy sees them</td>
					<td>A quick check with curl</td>
			</tr>
			<tr>
					<td>Lua service</td>
					<td>Every request header</td>
					<td>You do not know which header matters</td>
			</tr>
	</tbody>
</table>
<h2 id="logging-headers">Logging Headers <a class="anchor" data-pagefind-ignore href="#logging-headers" aria-label="Link to this section">#</a></h2>
<h3 id="basic-http-logging">Basic HTTP Logging <a class="anchor" data-pagefind-ignore href="#basic-http-logging" aria-label="Link to this section">#</a></h3>
<p><code>option httplog</code> turns on the HTTP log format: one line per request with timers, status and bytes.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">defaults
    mode http
    option httplog
    log global
</code></pre><h3 id="detailed-custom-logging">Detailed Custom Logging <a class="anchor" data-pagefind-ignore href="#detailed-custom-logging" aria-label="Link to this section">#</a></h3>
<p><code>capture request header</code> and <code>capture response header</code> add chosen headers to each log line, cut at <code>len</code> characters. Captures only work in a frontend.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Capture specific headers for logging
    capture request header Host len 50
    capture request header User-Agent len 100
    capture request header X-Forwarded-For len 50
    capture request header Authorization len 100
    capture request header Content-Type len 50
    
    capture response header Content-Type len 50
    capture response header Location len 200
    capture response header Set-Cookie len 100
    
    default_backend web_servers
</code></pre><h3 id="custom-log-format-with-headers">Custom Log Format with Headers <a class="anchor" data-pagefind-ignore href="#custom-log-format-with-headers" aria-label="Link to this section">#</a></h3>
<p>A custom <code>log-format</code> decides where the captured headers appear in the line.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Define captures
    capture request header Host len 50
    capture request header X-Request-ID len 50
    capture response header X-Response-Time len 20
    
    # Custom log format
    log-format &#34;%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs %{+Q}r&#34;
    
    default_backend web_servers
</code></pre><p>Log format variables:</p>
<ul>
<li><code>%hr</code>: Captured request headers</li>
<li><code>%hs</code>: Captured response headers</li>
<li><code>%{+Q}r</code>: Quoted HTTP request line</li>
<li><code>%ST</code>: HTTP status code</li>
<li><code>%TR</code>: Request receive time</li>
<li><code>%Ta</code>: Total active time</li>
</ul>
<h3 id="logging-all-headers">Logging All Headers <a class="anchor" data-pagefind-ignore href="#logging-all-headers" aria-label="Link to this section">#</a></h3>
<p><code>req.hdrs</code> is the complete request header block. Capture it on a separate debug frontend, not on production traffic: lines get long and include cookies and credentials.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend debug_frontend
    bind *:8080
    mode http
    
    # Log all request headers
    http-request capture req.hdrs len 1024
    
    # Log format with all headers
    log-format &#34;%ci [%t] %r headers:{%[capture.req.hdr(0)]}&#34;
    
    default_backend web_servers
</code></pre><h2 id="inspecting-headers-in-real-time">Inspecting Headers in Real-Time <a class="anchor" data-pagefind-ignore href="#inspecting-headers-in-real-time" aria-label="Link to this section">#</a></h2>
<h3 id="using-the-stats-socket">Using the Stats Socket <a class="anchor" data-pagefind-ignore href="#using-the-stats-socket" aria-label="Link to this section">#</a></h3>
<p><code>show sess</code> lists the sessions HAProxy holds right now. Use it for hanging or slow requests.</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"># Show current sessions with header info</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show sess&#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 detailed session info</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show sess &lt;session_id&gt;&#34;</span> <span class="p">|</span> socat stdio /run/haproxy/admin.sock
</span></span></code></pre></div><h3 id="debug-mode">Debug Mode <a class="anchor" data-pagefind-ignore href="#debug-mode" aria-label="Link to this section">#</a></h3>
<p>Run HAProxy in debug mode to see all traffic. It runs in the foreground, so the service has to stop first: use this in a lab only.</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 service</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"># Run in foreground with debug</span>
</span></span><span class="line"><span class="cl">haproxy -d -f /etc/haproxy/haproxy.cfg
</span></span></code></pre></div><p>This outputs all headers to stdout.</p>
<h3 id="divert-traffic-for-debugging">Divert Traffic for Debugging <a class="anchor" data-pagefind-ignore href="#divert-traffic-for-debugging" aria-label="Link to this section">#</a></h3>
<p>Send part of the traffic to a small debug server that prints what it receives. That shows the request exactly as a backend gets it, after all HAProxy rules.</p>
<ul>
<li><code>use_backend debug_backend if { path_beg /api }</code>: only <code>/api</code> goes to the debug server.</li>
<li><code>X-Mirror true</code>: a marker header, so you can see it arrive.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Send /api traffic to a debug backend instead of the real servers
    # (this diverts the requests; HAProxy does not copy them)
    http-request set-header X-Mirror true
    use_backend debug_backend if { path_beg /api }
    
    default_backend web_servers

backend debug_backend
    server debug 127.0.0.1:9999
</code></pre><p>Run a simple debug server on port 9999. netcat prints the raw request; the Python version prints path and headers and also answers <code>POST</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"># Using netcat (prints the request, answers with a fixed 200 OK)</span>
</span></span><span class="line"><span class="cl"><span class="k">while</span> true<span class="p">;</span> <span class="k">do</span> <span class="nb">printf</span> <span class="s1">&#39;HTTP/1.1 200 OK\r\nContent-Length: 3\r\nConnection: close\r\n\r\nOK\n&#39;</span> <span class="p">|</span> nc -l -p <span class="m">9999</span> -q 1<span class="p">;</span> <span class="k">done</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Using Python</span>
</span></span><span class="line"><span class="cl">python3 -c <span class="s2">&#34;
</span></span></span><span class="line"><span class="cl"><span class="s2">import http.server
</span></span></span><span class="line"><span class="cl"><span class="s2">class Handler(http.server.BaseHTTPRequestHandler):
</span></span></span><span class="line"><span class="cl"><span class="s2">    def do_GET(self):
</span></span></span><span class="line"><span class="cl"><span class="s2">        print(f&#39;Path: {self.path}&#39;)
</span></span></span><span class="line"><span class="cl"><span class="s2">        print(&#39;Headers:&#39;)
</span></span></span><span class="line"><span class="cl"><span class="s2">        for h, v in self.headers.items():
</span></span></span><span class="line"><span class="cl"><span class="s2">            print(f&#39;  {h}: {v}&#39;)
</span></span></span><span class="line"><span class="cl"><span class="s2">        self.send_response(200)
</span></span></span><span class="line"><span class="cl"><span class="s2">        self.end_headers()
</span></span></span><span class="line"><span class="cl"><span class="s2">        self.wfile.write(b&#39;OK&#39;)
</span></span></span><span class="line"><span class="cl"><span class="s2">    do_POST = do_GET
</span></span></span><span class="line"><span class="cl"><span class="s2">http.server.HTTPServer((&#39;&#39;, 9999), Handler).serve_forever()
</span></span></span><span class="line"><span class="cl"><span class="s2">&#34;</span>
</span></span></code></pre></div><h2 id="adding-and-modifying-request-headers">Adding and Modifying Request Headers <a class="anchor" data-pagefind-ignore href="#adding-and-modifying-request-headers" aria-label="Link to this section">#</a></h2>
<p><code>set-header</code> replaces any existing header with that name. The value can be fixed text or a sample in <code>%[...]</code>.</p>
<h3 id="setting-headers">Setting Headers <a class="anchor" data-pagefind-ignore href="#setting-headers" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Add static header
    http-request set-header X-Forwarded-Proto http
    
    # Add header from variable
    http-request set-header X-Client-IP %[src]
    
    # Add header with the name of the HAProxy node
    http-request set-header X-Proxy-Node %[hostname]
    
    # Add timestamp
    http-request set-header X-Request-Start %[date()]
    
    default_backend web_servers
</code></pre><h3 id="common-forwarding-headers">Common Forwarding Headers <a class="anchor" data-pagefind-ignore href="#common-forwarding-headers" aria-label="Link to this section">#</a></h3>
<p>These tell the server who the client is and how it connected. The server only sees HAProxy&rsquo;s address otherwise.</p>
<ul>
<li><code>X-Forwarded-For</code>: overwritten with the client IP. The commented lines append instead, for when another proxy sits in front of HAProxy.</li>
<li><code>X-Forwarded-Proto</code>: fixed per frontend, <code>http</code> on port 80 and <code>https</code> on 443. Apps use it to build correct links and redirects.</li>
<li><code>X-Forwarded-Host</code> and <code>X-Forwarded-Port</code>: the original host and port, for apps that build absolute URLs.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # X-Forwarded-For (client IP)
    http-request set-header X-Forwarded-For %[src]
    
    # Or append to existing (use instead of the line above)
    # http-request set-header X-Forwarded-For %[req.hdr(X-Forwarded-For)],%[src] if { req.hdr(X-Forwarded-For) -m found }
    # http-request set-header X-Forwarded-For %[src] unless { req.hdr(X-Forwarded-For) -m found }
    
    # X-Real-IP
    http-request set-header X-Real-IP %[src]
    
    # X-Forwarded-Proto
    http-request set-header X-Forwarded-Proto http
    
    # X-Forwarded-Host
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]
    
    # X-Forwarded-Port
    http-request set-header X-Forwarded-Port %[dst_port]
    
    default_backend web_servers

frontend https_frontend
    bind *:443 ssl crt /etc/haproxy/certs/
    
    http-request set-header X-Forwarded-For %[src]
    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]
    http-request set-header X-Forwarded-Port 443
    
    default_backend web_servers
</code></pre><h3 id="adding-request-id-for-tracing">Adding Request ID for Tracing <a class="anchor" data-pagefind-ignore href="#adding-request-id-for-tracing" aria-label="Link to this section">#</a></h3>
<p>A request ID follows one request through HAProxy, the server and its logs.</p>
<ul>
<li><code>unique-id-format</code>: builds the ID from client and frontend address and port, a timestamp, a request counter and the process ID, in hex (<code>%{+X}o</code>).</li>
<li><code>unique-id-header X-Request-ID</code>: sends it to the server.</li>
<li>The <code>uuid()</code> alternative keeps an ID the client or an upstream proxy already set.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Generate unique request ID (unique-id-header adds it to every request)
    unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
    unique-id-header X-Request-ID
    
    # Or use UUID format (instead of the two lines above, which always add a header)
    # http-request set-header X-Request-ID %[uuid()] unless { req.hdr(X-Request-ID) -m found }
    
    default_backend web_servers
</code></pre><h3 id="conditional-header-setting">Conditional Header Setting <a class="anchor" data-pagefind-ignore href="#conditional-header-setting" aria-label="Link to this section">#</a></h3>
<p>Add <code>if</code> or <code>unless</code> with an ACL to set a header only for some requests: by path, client network or user agent.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Set header based on path
    http-request set-header X-API-Version v2 if { path_beg /api/v2 }
    http-request set-header X-API-Version v1 if { path_beg /api/v1 }
    
    # Set header based on client IP
    acl internal_net src 192.168.0.0/16 10.0.0.0/8
    http-request set-header X-Internal-Request true if internal_net
    
    # Set header based on user agent
    acl is_mobile req.hdr(User-Agent) -m sub -i mobile android iphone
    http-request set-header X-Device-Type mobile if is_mobile
    http-request set-header X-Device-Type desktop unless is_mobile
    
    default_backend web_servers
</code></pre><h2 id="modifying-response-headers">Modifying Response Headers <a class="anchor" data-pagefind-ignore href="#modifying-response-headers" aria-label="Link to this section">#</a></h2>
<h3 id="adding-security-headers">Adding Security Headers <a class="anchor" data-pagefind-ignore href="#adding-security-headers" aria-label="Link to this section">#</a></h3>
<p>Set these once on the load balancer instead of in every application.</p>
<table>
	<thead>
			<tr>
					<th>Header</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>Strict-Transport-Security</code></td>
					<td>Browsers use HTTPS only, here for two years and all subdomains</td>
			</tr>
			<tr>
					<td><code>Content-Security-Policy</code></td>
					<td>Where scripts, styles and other content may come from</td>
			</tr>
			<tr>
					<td><code>X-Content-Type-Options nosniff</code></td>
					<td>Browsers trust the <code>Content-Type</code> instead of guessing</td>
			</tr>
			<tr>
					<td><code>X-Frame-Options SAMEORIGIN</code></td>
					<td>Only your own site may show the page in a frame</td>
			</tr>
			<tr>
					<td><code>X-XSS-Protection</code></td>
					<td>For old browsers only; current browsers ignore it</td>
			</tr>
			<tr>
					<td><code>Referrer-Policy</code></td>
					<td>How much of the URL goes to other sites</td>
			</tr>
			<tr>
					<td><code>Permissions-Policy</code></td>
					<td>Turns off browser features such as camera and location</td>
			</tr>
	</tbody>
</table>
<p>Test the CSP with your application before you enable it: a policy that is too strict breaks pages.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:443 ssl crt /etc/haproxy/certs/
    
    # HSTS
    http-response set-header Strict-Transport-Security &#34;max-age=63072000; includeSubDomains; preload&#34;
    
    # Content Security Policy
    http-response set-header Content-Security-Policy &#34;default-src &#39;self&#39;; script-src &#39;self&#39; &#39;unsafe-inline&#39;; style-src &#39;self&#39; &#39;unsafe-inline&#39;&#34;
    
    # X-Content-Type-Options
    http-response set-header X-Content-Type-Options nosniff
    
    # X-Frame-Options
    http-response set-header X-Frame-Options SAMEORIGIN
    
    # X-XSS-Protection
    http-response set-header X-XSS-Protection &#34;1; mode=block&#34;
    
    # Referrer Policy
    http-response set-header Referrer-Policy strict-origin-when-cross-origin
    
    # Permissions Policy
    http-response set-header Permissions-Policy &#34;geolocation=(), microphone=(), camera=()&#34;
    
    default_backend web_servers
</code></pre><h3 id="cors-headers">CORS Headers <a class="anchor" data-pagefind-ignore href="#cors-headers" aria-label="Link to this section">#</a></h3>
<p>Browsers send a preflight <code>OPTIONS</code> request before cross-origin API calls. HAProxy answers it directly with a 204 and adds the CORS headers.</p>
<ul>
<li><code>set-var(txn.cors_origin)</code>: saves <code>Origin</code>, because response rules cannot read request headers.</li>
<li><code>http-after-response</code>: also adds the headers to HAProxy&rsquo;s own 204, which <code>http-response</code> would skip.</li>
<li><code>Access-Control-Allow-Origin &quot;*&quot;</code>: any site may call the API. Use the next example to allow only some.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Handle CORS preflight
    # (store Origin in a variable: request headers are not available in response rules)
    http-request set-var(txn.cors_origin) req.hdr(Origin)
    acl is_options method OPTIONS
    acl is_cors_request var(txn.cors_origin) -m found
    
    # Return 204 for preflight
    http-request return status 204 if is_options is_cors_request
    
    # Add CORS headers to responses (http-after-response also covers the 204 above)
    http-after-response set-header Access-Control-Allow-Origin &#34;*&#34; if is_cors_request
    http-after-response set-header Access-Control-Allow-Methods &#34;GET, POST, PUT, DELETE, OPTIONS&#34; if is_cors_request
    http-after-response set-header Access-Control-Allow-Headers &#34;Content-Type, Authorization, X-Requested-With&#34; if is_cors_request
    http-after-response set-header Access-Control-Max-Age &#34;86400&#34; if is_cors_request
    
    default_backend web_servers
</code></pre><h3 id="conditional-cors-by-origin">Conditional CORS by Origin <a class="anchor" data-pagefind-ignore href="#conditional-cors-by-origin" aria-label="Link to this section">#</a></h3>
<p>Only listed origins get the CORS headers, with their own origin echoed back. <code>Allow-Credentials true</code> lets the browser send cookies, which is not allowed together with <code>*</code>.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Define allowed origins (stored in a variable so response rules can use it)
    http-request set-var(txn.origin) req.hdr(Origin)
    acl allowed_origin var(txn.origin) -m str -i https://example.com https://app.example.com
    
    # Echo back the allowed origin
    http-response set-header Access-Control-Allow-Origin %[var(txn.origin)] if allowed_origin
    http-response set-header Access-Control-Allow-Credentials true if allowed_origin
    
    default_backend web_servers
</code></pre><h2 id="deleting-headers">Deleting Headers <a class="anchor" data-pagefind-ignore href="#deleting-headers" aria-label="Link to this section">#</a></h2>
<h3 id="remove-sensitive-headers">Remove Sensitive Headers <a class="anchor" data-pagefind-ignore href="#remove-sensitive-headers" aria-label="Link to this section">#</a></h3>
<p>Clients can send <code>X-Forwarded-For</code> and friends themselves. Delete them first, then set your own trusted values, so the server never trusts a forged client IP.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Remove potentially dangerous headers from requests
    http-request del-header X-Forwarded-For
    http-request del-header X-Real-IP
    http-request del-header X-Forwarded-Proto
    http-request del-header X-Forwarded-Host
    
    # Now add our own trusted values
    http-request set-header X-Forwarded-For %[src]
    http-request set-header X-Forwarded-Proto http
    
    default_backend web_servers
</code></pre><h3 id="remove-headers-from-responses">Remove Headers from Responses <a class="anchor" data-pagefind-ignore href="#remove-headers-from-responses" aria-label="Link to this section">#</a></h3>
<p>Version headers tell attackers which software to target; debug headers leak internals. Remove them in the backend.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend web_servers
    # Remove server version headers
    http-response del-header Server
    http-response del-header X-Powered-By
    http-response del-header X-AspNet-Version
    http-response del-header X-AspNetMvc-Version
    
    # Remove debug headers
    http-response del-header X-Debug-Token
    http-response del-header X-Debug-Token-Link
    
    server web1 192.168.1.10:8080 check
</code></pre><h2 id="header-based-routing">Header-Based Routing <a class="anchor" data-pagefind-ignore href="#header-based-routing" aria-label="Link to this section">#</a></h2>
<p>ACLs on headers pick the backend. The first <code>use_backend</code> that matches wins; <code>default_backend</code> takes the rest.</p>
<table>
	<thead>
			<tr>
					<th>Route by</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>Host</code></td>
					<td>Several sites or services on one IP</td>
			</tr>
			<tr>
					<td>A custom header (<code>X-Version</code>)</td>
					<td>API versions, testing a new backend with selected clients</td>
			</tr>
			<tr>
					<td><code>Accept</code></td>
					<td>Separate backends per response format</td>
			</tr>
	</tbody>
</table>
<h3 id="route-by-host-header">Route by Host Header <a class="anchor" data-pagefind-ignore href="#route-by-host-header" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # ACLs based on Host header
    acl host_api hdr(host) -i api.example.com
    acl host_admin hdr(host) -i admin.example.com
    acl host_www hdr(host) -i www.example.com example.com
    
    use_backend api_servers if host_api
    use_backend admin_servers if host_admin
    use_backend www_servers if host_www
    
    default_backend www_servers
</code></pre><h3 id="route-by-custom-header">Route by Custom Header <a class="anchor" data-pagefind-ignore href="#route-by-custom-header" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Route based on X-Version header
    acl version_v2 req.hdr(X-Version) -i v2
    acl version_v1 req.hdr(X-Version) -i v1
    
    use_backend api_v2 if version_v2
    use_backend api_v1 if version_v1
    
    default_backend api_v2
</code></pre><h3 id="route-by-accept-header">Route by Accept Header <a class="anchor" data-pagefind-ignore href="#route-by-accept-header" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    acl accepts_json req.hdr(Accept) -m sub application/json
    acl accepts_xml req.hdr(Accept) -m sub application/xml
    
    use_backend json_api if accepts_json
    use_backend xml_api if accepts_xml
    
    default_backend json_api
</code></pre><h2 id="debugging-specific-issues">Debugging Specific Issues <a class="anchor" data-pagefind-ignore href="#debugging-specific-issues" aria-label="Link to this section">#</a></h2>
<h3 id="session-persistence-problems">Session Persistence Problems <a class="anchor" data-pagefind-ignore href="#session-persistence-problems" aria-label="Link to this section">#</a></h3>
<p>Users that bounce between servers lose their session. <code>cookie SERVERID insert</code> makes HAProxy set a cookie naming the server, so the next request goes to the same one.</p>
<ul>
<li><code>indirect</code>: the cookie is not passed on to the server.</li>
<li><code>nocache</code>: marks responses with the cookie as not cacheable, so a shared cache does not hand it to other users.</li>
<li>The captures log the cookies in both directions: is the cookie set, and does the browser send it back?</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend web_servers
    balance roundrobin
    cookie SERVERID insert indirect nocache
    
    server web1 192.168.1.10:8080 cookie s1 check
    server web2 192.168.1.11:8080 cookie s2 check

frontend http_frontend
    bind *:80
    
    # Log cookie info (capture only works in a frontend)
    capture cookie SERVERID len 32
    
    # Capture cookies for debugging
    capture request header Cookie len 200
    capture response header Set-Cookie len 200
    
    # Log format showing cookies
    log-format &#34;%ci [%t] %r Cookie:{%[capture.req.hdr(0)]} Set-Cookie:{%[capture.res.hdr(0)]}&#34;
    
    default_backend web_servers
</code></pre><h3 id="authentication-header-issues">Authentication Header Issues <a class="anchor" data-pagefind-ignore href="#authentication-header-issues" aria-label="Link to this section">#</a></h3>
<p>For 401 problems: does the <code>Authorization</code> header arrive, and what kind is it? The debug headers <code>X-Auth-Debug</code> and <code>X-Auth-Type</code> tell the server (and your debug backend) without logging the token itself.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Capture auth header (be careful with logging sensitive data!)
    capture request header Authorization len 100
    
    # Check if auth header exists
    acl has_auth req.hdr(Authorization) -m found
    acl valid_bearer req.hdr(Authorization) -m beg Bearer
    
    # Add debug header
    http-request set-header X-Auth-Debug has_auth if has_auth
    http-request set-header X-Auth-Debug missing unless has_auth
    http-request set-header X-Auth-Type bearer if valid_bearer
    http-request set-header X-Auth-Type other if has_auth !valid_bearer
    
    default_backend web_servers
</code></pre><h3 id="content-type-mismatches">Content-Type Mismatches <a class="anchor" data-pagefind-ignore href="#content-type-mismatches" aria-label="Link to this section">#</a></h3>
<p>Copies the request and response <code>Content-Type</code> into extra headers and the log. Useful when a client and a server disagree about JSON, form data or encoding.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Capture content types
    capture request header Content-Type len 50
    capture response header Content-Type len 50
    
    # Add debug info
    http-request set-header X-Request-Content-Type %[req.hdr(Content-Type)]
    http-response set-header X-Response-Content-Type %[res.hdr(Content-Type)]
    
    default_backend web_servers
</code></pre><h3 id="caching-issues">Caching Issues <a class="anchor" data-pagefind-ignore href="#caching-issues" aria-label="Link to this section">#</a></h3>
<p>Captures the cache headers in both directions. The backend rules turn caching off completely; use that only while you debug, as it puts the full load on the servers.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Capture cache headers
    capture response header Cache-Control len 100
    capture response header ETag len 50
    capture request header If-None-Match len 50
    capture request header If-Modified-Since len 50
    
    default_backend web_servers

backend web_servers
    # Force no caching for debugging
    http-response set-header Cache-Control &#34;no-store, no-cache, must-revalidate&#34;
    http-response del-header ETag
    http-response del-header Last-Modified
    
    server web1 192.168.1.10:8080 check
</code></pre><h2 id="creating-a-debug-endpoint">Creating a Debug Endpoint <a class="anchor" data-pagefind-ignore href="#creating-a-debug-endpoint" aria-label="Link to this section">#</a></h2>
<p><code>http-request return</code> answers from HAProxy itself, without a backend. <code>lf-string</code> fills in samples like <code>%[src]</code> per request. Requests to the path get the debug answer; everything else goes to the servers as usual.</p>
<h3 id="echo-all-headers">Echo All Headers <a class="anchor" data-pagefind-ignore href="#echo-all-headers" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    # Debug endpoint that returns request info
    acl is_debug path /debug/headers
    
    http-request return status 200 content-type &#34;text/plain&#34; lf-string &#34;Client IP: %[src]\nMethod: %[method]\nPath: %[path]\nQuery: %[query]\nHost: %[req.hdr(Host)]\nUser-Agent: %[req.hdr(User-Agent)]\nAccept: %[req.hdr(Accept)]\nContent-Type: %[req.hdr(Content-Type)]\nAuthorization: %[req.hdr(Authorization)]\nX-Forwarded-For: %[req.hdr(X-Forwarded-For)]\nCookies: %[req.hdr(Cookie)]&#34; if is_debug
    
    default_backend web_servers
</code></pre><h3 id="json-debug-response">JSON Debug Response <a class="anchor" data-pagefind-ignore href="#json-debug-response" aria-label="Link to this section">#</a></h3>
<p>The same as JSON, for scripts and monitoring tools.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend http_frontend
    bind *:80
    
    acl is_debug path /debug/info
    
    http-request return status 200 content-type &#34;application/json&#34; lf-string &#39;{&#34;client_ip&#34;:&#34;%[src]&#34;,&#34;method&#34;:&#34;%[method]&#34;,&#34;path&#34;:&#34;%[path]&#34;,&#34;host&#34;:&#34;%[req.hdr(Host)]&#34;,&#34;user_agent&#34;:&#34;%[req.hdr(User-Agent)]&#34;,&#34;timestamp&#34;:&#34;%[date]&#34;}&#39; if is_debug
    
    default_backend web_servers
</code></pre><h2 id="lua-scripting-for-advanced-debugging">Lua Scripting for Advanced Debugging <a class="anchor" data-pagefind-ignore href="#lua-scripting-for-advanced-debugging" aria-label="Link to this section">#</a></h2>
<p>The debug endpoints above only show headers you name. A small Lua service prints every header, whatever it is called.</p>
<h3 id="install-lua-support">Install Lua Support <a class="anchor" data-pagefind-ignore href="#install-lua-support" aria-label="Link to this section">#</a></h3>
<p>Debian and Ubuntu build HAProxy with Lua included, there is no separate package. Check it with:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">haproxy -vv <span class="p">|</span> grep -i lua
</span></span></code></pre></div><h3 id="header-dump-lua-script">Header Dump Lua Script <a class="anchor" data-pagefind-ignore href="#header-dump-lua-script" aria-label="Link to this section">#</a></h3>
<p><code>core.register_service</code> defines an HTTP service HAProxy can answer with. It loops over all request headers, adds connection info, and returns it as plain text.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-lua" data-lang="lua"><span class="line"><span class="cl"><span class="c1">-- /etc/haproxy/lua/debug-headers.lua</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">core.register_service</span><span class="p">(</span><span class="s2">&#34;debug_headers&#34;</span><span class="p">,</span> <span class="s2">&#34;http&#34;</span><span class="p">,</span> <span class="kr">function</span><span class="p">(</span><span class="n">applet</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="kd">local</span> <span class="n">response</span> <span class="o">=</span> <span class="s2">&#34;Request Headers:</span><span class="se">\n</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="n">response</span> <span class="o">=</span> <span class="n">response</span> <span class="o">..</span> <span class="s2">&#34;================</span><span class="se">\n</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">-- Get all request headers</span>
</span></span><span class="line"><span class="cl">    <span class="kd">local</span> <span class="n">headers</span> <span class="o">=</span> <span class="n">applet.headers</span>
</span></span><span class="line"><span class="cl">    <span class="kr">for</span> <span class="n">name</span><span class="p">,</span> <span class="n">values</span> <span class="kr">in</span> <span class="n">pairs</span><span class="p">(</span><span class="n">headers</span><span class="p">)</span> <span class="kr">do</span>
</span></span><span class="line"><span class="cl">        <span class="kr">for</span> <span class="n">_</span><span class="p">,</span> <span class="n">value</span> <span class="kr">in</span> <span class="n">pairs</span><span class="p">(</span><span class="n">values</span><span class="p">)</span> <span class="kr">do</span>
</span></span><span class="line"><span class="cl">            <span class="n">response</span> <span class="o">=</span> <span class="n">response</span> <span class="o">..</span> <span class="n">name</span> <span class="o">..</span> <span class="s2">&#34;: &#34;</span> <span class="o">..</span> <span class="n">value</span> <span class="o">..</span> <span class="s2">&#34;</span><span class="se">\n</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="kr">end</span>
</span></span><span class="line"><span class="cl">    <span class="kr">end</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">response</span> <span class="o">..</span> <span class="s2">&#34;</span><span class="se">\n</span><span class="s2">Connection Info:</span><span class="se">\n</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="n">response</span> <span class="o">=</span> <span class="n">response</span> <span class="o">..</span> <span class="s2">&#34;================</span><span class="se">\n</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="n">response</span> <span class="o">=</span> <span class="n">response</span> <span class="o">..</span> <span class="s2">&#34;Client IP: &#34;</span> <span class="o">..</span> <span class="n">applet.sf</span><span class="p">:</span><span class="n">src</span><span class="p">()</span> <span class="o">..</span> <span class="s2">&#34;</span><span class="se">\n</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="n">response</span> <span class="o">=</span> <span class="n">response</span> <span class="o">..</span> <span class="s2">&#34;Client Port: &#34;</span> <span class="o">..</span> <span class="n">applet.sf</span><span class="p">:</span><span class="n">src_port</span><span class="p">()</span> <span class="o">..</span> <span class="s2">&#34;</span><span class="se">\n</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="n">response</span> <span class="o">=</span> <span class="n">response</span> <span class="o">..</span> <span class="s2">&#34;Server IP: &#34;</span> <span class="o">..</span> <span class="n">applet.sf</span><span class="p">:</span><span class="n">dst</span><span class="p">()</span> <span class="o">..</span> <span class="s2">&#34;</span><span class="se">\n</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="n">response</span> <span class="o">=</span> <span class="n">response</span> <span class="o">..</span> <span class="s2">&#34;Server Port: &#34;</span> <span class="o">..</span> <span class="n">applet.sf</span><span class="p">:</span><span class="n">dst_port</span><span class="p">()</span> <span class="o">..</span> <span class="s2">&#34;</span><span class="se">\n</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="n">response</span> <span class="o">=</span> <span class="n">response</span> <span class="o">..</span> <span class="s2">&#34;Method: &#34;</span> <span class="o">..</span> <span class="n">applet.method</span> <span class="o">..</span> <span class="s2">&#34;</span><span class="se">\n</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="n">response</span> <span class="o">=</span> <span class="n">response</span> <span class="o">..</span> <span class="s2">&#34;Path: &#34;</span> <span class="o">..</span> <span class="n">applet.path</span> <span class="o">..</span> <span class="s2">&#34;</span><span class="se">\n</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="n">response</span> <span class="o">=</span> <span class="n">response</span> <span class="o">..</span> <span class="s2">&#34;Query: &#34;</span> <span class="o">..</span> <span class="p">(</span><span class="n">applet.qs</span> <span class="ow">or</span> <span class="s2">&#34;&#34;</span><span class="p">)</span> <span class="o">..</span> <span class="s2">&#34;</span><span class="se">\n</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="n">applet</span><span class="p">:</span><span class="n">set_status</span><span class="p">(</span><span class="mi">200</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">applet</span><span class="p">:</span><span class="n">add_header</span><span class="p">(</span><span class="s2">&#34;Content-Type&#34;</span><span class="p">,</span> <span class="s2">&#34;text/plain&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">applet</span><span class="p">:</span><span class="n">add_header</span><span class="p">(</span><span class="s2">&#34;Content-Length&#34;</span><span class="p">,</span> <span class="n">string.len</span><span class="p">(</span><span class="n">response</span><span class="p">))</span>
</span></span><span class="line"><span class="cl">    <span class="n">applet</span><span class="p">:</span><span class="n">start_response</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="n">applet</span><span class="p">:</span><span class="n">send</span><span class="p">(</span><span class="n">response</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="kr">end</span><span class="p">)</span>
</span></span></code></pre></div><h3 id="use-in-haproxy-config">Use in HAProxy Config <a class="anchor" data-pagefind-ignore href="#use-in-haproxy-config" aria-label="Link to this section">#</a></h3>
<p><code>lua-load</code> loads the script at startup; <code>use-service lua.debug_headers</code> answers <code>/debug/headers</code> with it.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">global
    # HAProxy 3.1+: also set &#34;tune.lua.bool-sample-conversion normal&#34; before lua-load
    lua-load /etc/haproxy/lua/debug-headers.lua

frontend http_frontend
    bind *:80
    
    acl is_debug path /debug/headers
    http-request use-service lua.debug_headers if is_debug
    
    default_backend web_servers
</code></pre><h2 id="complete-debug-configuration">Complete Debug Configuration <a class="anchor" data-pagefind-ignore href="#complete-debug-configuration" aria-label="Link to this section">#</a></h2>
<p>Everything above in one file, for a test or staging load balancer.</p>
<table>
	<thead>
			<tr>
					<th>Part</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>log ... debug</code>, captures, <code>log-format</code></td>
					<td>Logs chosen headers per request; <code>Authorization</code> cut to 20 characters, enough to see the type</td>
			</tr>
			<tr>
					<td><code>unique-id-*</code></td>
					<td>Request ID to the server and back in <code>X-Request-ID</code></td>
			</tr>
			<tr>
					<td><code>del-header</code> + <code>set-header</code></td>
					<td>Trusted forwarding headers only</td>
			</tr>
			<tr>
					<td><code>/debug/headers</code>, <code>/debug/json</code></td>
					<td>Debug endpoints</td>
			</tr>
			<tr>
					<td>Backend <code>http-response</code> rules</td>
					<td>Hide <code>Server</code>/<code>X-Powered-By</code>, add the server name, request ID and response time</td>
			</tr>
	</tbody>
</table>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy"># /etc/haproxy/haproxy.cfg

global
    log /dev/log local0 debug
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
    user haproxy
    group haproxy
    daemon
    
    # Enable Lua for advanced debugging
    # lua-load /etc/haproxy/lua/debug-headers.lua

defaults
    log global
    mode http
    option httplog
    option dontlognull
    # no &#34;option forwardfor&#34;: X-Forwarded-For is set explicitly below
    timeout connect 5s
    timeout client  50s
    timeout server  50s

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

frontend http_frontend
    bind *:80
    
    # Generate unique request ID
    unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
    unique-id-header X-Request-ID
    
    # Capture headers for logging
    capture request header Host len 50
    capture request header User-Agent len 100
    capture request header X-Forwarded-For len 50
    capture request header Authorization len 20
    capture request header Content-Type len 50
    capture request header Cookie len 100
    capture request header X-Request-ID len 50
    
    capture response header Content-Type len 50
    capture response header Location len 200
    capture response header Set-Cookie len 100
    capture response header Cache-Control len 50
    
    # Detailed log format
    log-format &#34;%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq {%hrl} {%hsl} %{+Q}r&#34;
    
    # Remove potentially spoofed headers
    http-request del-header X-Forwarded-For
    http-request del-header X-Real-IP
    http-request del-header X-Forwarded-Proto
    
    # Add trusted forwarding headers
    http-request set-header X-Forwarded-For %[src]
    http-request set-header X-Real-IP %[src]
    http-request set-header X-Forwarded-Proto http
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]
    http-request set-header X-Forwarded-Port %[dst_port]
    
    # Debug endpoints
    acl is_debug_headers path /debug/headers
    acl is_debug_json path /debug/json
    
    http-request return status 200 content-type &#34;text/plain&#34; lf-string &#34;Client: %[src]:%[src_port]\nHost: %[req.hdr(Host)]\nMethod: %[method]\nPath: %[path]\nQuery: %[query]\nProtocol: %[req.ver]\nUser-Agent: %[req.hdr(User-Agent)]\nAccept: %[req.hdr(Accept)]\nContent-Type: %[req.hdr(Content-Type)]\nX-Request-ID: %[unique-id]\nCookies: %[req.hdr(Cookie)]&#34; if is_debug_headers
    
    http-request return status 200 content-type &#34;application/json&#34; lf-string &#39;{&#34;client_ip&#34;:&#34;%[src]&#34;,&#34;host&#34;:&#34;%[req.hdr(Host)]&#34;,&#34;method&#34;:&#34;%[method]&#34;,&#34;path&#34;:&#34;%[path]&#34;,&#34;request_id&#34;:&#34;%[unique-id]&#34;}&#39; if is_debug_json
    
    default_backend web_servers

backend web_servers
    balance roundrobin
    option httpchk GET /health
    
    # Remove server identification from responses
    http-response del-header Server
    http-response del-header X-Powered-By
    
    # Add debug headers to response
    http-response set-header X-Backend-Server %s
    http-response set-header X-Request-ID %[unique-id]
    http-response set-header X-Response-Time %Ta
    
    server web1 192.168.1.10:8080 check
    server web2 192.168.1.11:8080 check
</code></pre><h2 id="quick-debugging-commands">Quick Debugging Commands <a class="anchor" data-pagefind-ignore href="#quick-debugging-commands" aria-label="Link to this section">#</a></h2>
<p>Start with <code>curl -v</code> (headers in both directions), then the debug endpoint, then the logs. Sending your own <code>X-Forwarded-For</code> shows whether HAProxy passes a forged client IP on.</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"># Watch HAProxy logs in real-time</span>
</span></span><span class="line"><span class="cl">tail -f /var/log/haproxy.log <span class="p">|</span> grep http_frontend
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test with curl and show headers</span>
</span></span><span class="line"><span class="cl">curl -v http://example.com/
</span></span><span class="line"><span class="cl">curl -H <span class="s2">&#34;X-Custom: test&#34;</span> http://example.com/debug/headers
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test from specific IP (if accessible)</span>
</span></span><span class="line"><span class="cl">curl -H <span class="s2">&#34;X-Forwarded-For: 1.2.3.4&#34;</span> http://example.com/debug/headers
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check HAProxy session info</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show sess&#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 backend status</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show stat&#34;</span> <span class="p">|</span> socat stdio /run/haproxy/admin.sock <span class="p">|</span> cut -d<span class="s1">&#39;,&#39;</span> -f1,2,18
</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>Logs hold secrets.</strong> Captured <code>Authorization</code> and <code>Cookie</code> headers end up in log files. Keep captures short (like <code>len 20</code>), or leave them out in production.</li>
<li><strong>Debug endpoints are public</strong> on the frontend they are on. Restrict them to your network with an ACL, or remove them after debugging.</li>
<li><strong>Never trust client forwarding headers.</strong> Delete them before you set your own.</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-http-headers" rel="noopener">pderuiter/blog-haproxy-http-headers</a>. It creates an HAProxy VM on Proxmox with the complete debug configuration from this post, header capture, request IDs, debug endpoints and the optional Lua header dump; run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code> (add <code>-e @../tests/demo-vars.yml</code> for two demo backends that echo the headers they receive).</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: <a href="https://blog.bsdserver.nl/haproxy-mtls-securing-api-access-with-mutual-tls-authentication/">mTLS for securing API access</a>, building on the TLS knowledge from previous posts.</p>
<h2 id="summary">Summary <a class="anchor" data-pagefind-ignore href="#summary" aria-label="Link to this section">#</a></h2>
<ul>
<li>Use <code>capture request/response header</code> for logging</li>
<li>Create debug endpoints with <code>http-request return</code></li>
<li>Remove untrusted headers before adding your own</li>
<li>Use <code>http-request/response set-header</code> for manipulation</li>
<li>Add X-Request-ID for tracing across services</li>
<li>Use Lua for advanced header inspection</li>
<li>Always secure sensitive header logging in production</li>
</ul>
]]></content:encoded></item></channel></rss>