From 9da37e57a3e43a229f3246e64b6b115b4f4f6b79 Mon Sep 17 00:00:00 2001 From: Lars Kiesow Date: Sun, 25 Jan 2026 11:10:06 +0100 Subject: [PATCH] Improve documentation of PROXY protocol listener This patch improves the documentation of the caddy.listeners.proxy_protocol to clarify some unexpected behavior. Most notably, the previous documentation stated that `Allow` will *allow/require* PROXY headers. The require in this tripped me up since Caddy will always accept clients in this list regardless, if they are using PROXY protocol or not. --- modules/caddyhttp/proxyprotocol/listenerwrapper.go | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/modules/caddyhttp/proxyprotocol/listenerwrapper.go b/modules/caddyhttp/proxyprotocol/listenerwrapper.go index f1d170c38..607dd0f5a 100644 --- a/modules/caddyhttp/proxyprotocol/listenerwrapper.go +++ b/modules/caddyhttp/proxyprotocol/listenerwrapper.go @@ -41,12 +41,16 @@ type ListenerWrapper struct { Timeout caddy.Duration `json:"timeout,omitempty"` // Allow is an optional list of CIDR ranges to - // allow/require PROXY headers from. + // allow PROXY headers from. + // Note that while the PROXY protocol is allowed, + // it is not required to be used by clients in this range. Allow []string `json:"allow,omitempty"` allow []netip.Prefix // Deny is an optional list of CIDR ranges to // deny PROXY headers from. + // Connections without PROXY headers from clients + // in this range are still allowed. Deny []string `json:"deny,omitempty"` deny []netip.Prefix @@ -63,7 +67,7 @@ type ListenerWrapper struct { // // - USE: address from PROXY header // - // - REJECT: connection when PROXY header is sent + // - REJECT: connection when PROXY header is sent. // Note: even though the first read on the connection returns an error if // a PROXY header is present, subsequent reads do not. It is the task of // the code using the connection to handle that case properly.