From 0641703a79a75b4d4a943910e1a3d011c10d928f Mon Sep 17 00:00:00 2001
From: Valery Piashchynski <piashchynski.valery@gmail.com>
Date: Thu, 4 Jun 2026 08:37:19 +0200
Subject: [PATCH] docs: document proxy_ip_parser trusted_headers

Document the new http.trusted_headers option: an ordered allowlist of headers
used to resolve the client IP (first non-empty match wins), the default order
when unset, and custom-header support.
---
 http/proxy.md | 40 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/http/proxy.md b/http/proxy.md
index 26de1c5..beb9855 100644
--- a/http/proxy.md
+++ b/http/proxy.md
@@ -1,9 +1,18 @@
 # Proxy IP parser
 
-This middleware parses the following headers: `X-Forwarded-*`, `Forwarded`, `True-Client-IP`, and `X-Real-IP`.
+This middleware resolves the real client IP from proxy headers when a request arrives
+through a trusted subnet. By default it consults, in order: `Forwarded`, `X-Forwarded-For`,
+`X-Real-IP`, `True-Client-IP`, and `CF-Connecting-IP`. The set and order of headers can be
+customized with `trusted_headers`.
 
 ## Description
-When the proxy is trusted, the leftmost IP address is used as `RemoteAddr`. Otherwise, `RemoteAddr` is not changed.
+
+When the immediate peer is within one of the `trusted_subnets`, the middleware resolves the
+client IP from the configured headers — the first non-empty match wins — and sets it as
+`RemoteAddr`. Otherwise `RemoteAddr` is left unchanged.
+
+The middleware is active only when `trusted_subnets` is configured; without it, forwarding
+headers are never trusted.
 
 ## Usage
 
@@ -33,3 +42,30 @@ http:
 ```
 
 {% endcode %}
+
+## Trusted headers
+
+`trusted_headers` is an ordered allowlist of the headers used to resolve the client IP. The
+middleware checks them in order and uses the first non-empty value; headers that are not
+listed are ignored, and custom headers are supported. When `trusted_headers` is omitted, the
+default order is used: `Forwarded`, `X-Forwarded-For`, `X-Real-IP`, `True-Client-IP`,
+`CF-Connecting-IP`.
+
+For example, to trust only `X-Real-IP` and Cloudflare's `CF-Connecting-IP` while ignoring
+`X-Forwarded-*`:
+
+{% code title=".rr.yaml" %}
+
+```yaml
+http:
+  trusted_subnets: [ "10.0.0.0/8", "127.0.0.0/8" ]
+  trusted_headers: [ "X-Real-IP", "CF-Connecting-IP" ]
+```
+
+{% endcode %}
+
+{% hint style="info" %}
+`X-Forwarded-For` uses the left-most address from its comma-separated list, and `Forwarded`
+is parsed per [RFC 7239](https://datatracker.ietf.org/doc/html/rfc7239) (`for=`). All other
+headers, including custom ones, are taken verbatim.
+{% endhint %}