From 2c6f20fbc3fa5a4094075422e9c002fd936648c4 Mon Sep 17 00:00:00 2001
From: ahmzaa <hamza@ahmza.com>
Date: Sat, 25 Jul 2026 05:03:12 +0100
Subject: [PATCH] docs: show dynamic cloudflare trusted_proxies as primary
 example

caddy-cf now bundles WeidiDeng/caddy-cloudflare-ip, so document
'trusted_proxies cloudflare { interval 12h; timeout 15s }' as the
primary (auto-refreshing) approach, with the static-list method noted
as the fallback for builds without the plugin. Also explains
client_ip_headers (Cf-Connecting-Ip preferred, X-Forwarded-For fallback).
---
 docs/caddy-reverse-proxy.md | 29 +++++++++++++++++++++++------
 1 file changed, 23 insertions(+), 6 deletions(-)

diff --git a/docs/caddy-reverse-proxy.md b/docs/caddy-reverse-proxy.md
index da7fe97..9a86a7b 100644
--- a/docs/caddy-reverse-proxy.md
+++ b/docs/caddy-reverse-proxy.md
@@ -99,14 +99,31 @@ committed [`Caddyfile`](../Caddyfile) at the repo root; copy it to the
   i.e. a **blank page**.
 - **`encode zstd gzip`** — compression happens here (SWS has it disabled).
 - **`header { ... }`** — security headers (SWS has them disabled).
-- **`trusted_proxies static <Cloudflare ranges>`** + **`client_ip_headers
+- **`trusted_proxies cloudflare { ... }`** + **`client_ip_headers
   Cf-Connecting-Ip X-Forwarded-For`** — so the real visitor IP is used for
   logging/matchers, but only when the request genuinely comes from Cloudflare
-  (prevents header spoofing from any other source). The ranges come from
-  <https://www.cloudflare.com/ips-v4/> and <https://www.cloudflare.com/ips-v6/>;
-  keep them in sync when Cloudflare updates them. If `caddy-cf` is rebuilt with
-  the `caddy-cloudflare-ip` plugin, the static list can be replaced with
-  `trusted_proxies cloudflare`.
+  (prevents header spoofing from any other source). The `cloudflare` IP source
+  ([WeidiDeng/caddy-cloudflare-ip](https://github.com/WeidiDeng/caddy-cloudflare-ip),
+  baked into the `caddy-cf` image) auto-fetches the ranges from
+  <https://www.cloudflare.com/ips-v4/> and <https://www.cloudflare.com/ips-v6/>
+  and refreshes them on the configured `interval`, so there is no static list to
+  maintain:
+
+  ```caddy
+  trusted_proxies cloudflare {
+  	interval 12h
+  	timeout 15s
+  }
+  ```
+
+  `client_ip_headers` lists which header holds the real visitor IP:
+  `Cf-Connecting-Ip` is Cloudflare's single authoritative end-user IP, with
+  `X-Forwarded-For` as the fallback. It is only trusted for requests coming from
+  the `trusted_proxies` above.
+
+  > If you ever run without the `caddy-cloudflare-ip` plugin, you can instead
+  > pin the static ranges with `trusted_proxies static <ip/cidr ...>` copied
+  > from the Cloudflare IP pages, but then you must keep them in sync manually.
 
 Deploy and reload: