docs: document trusted_proxies config option

Cover the option in config-example.yaml, the reverse-proxy
integration guide, and the 0.29.0 CHANGELOG.

CHANGELOG.md

@@ -307,6 +307,7 @@ connected" routers that maintain their control session but cannot route packets.
   - Tagged nodes (registered with tagged pre-auth keys) are exempt from default expiry
   - `oidc.expiry` has been removed; use `node.expiry` instead (applies to all registration methods including OIDC)
   - `ephemeral_node_inactivity_timeout` is deprecated in favour of `node.ephemeral.inactivity_timeout`
+- Add `trusted_proxies` to gate `True-Client-IP` / `X-Real-IP` / `X-Forwarded-For` (previously honoured from any client)
 
 #### Debug
 

config-example.yaml

@@ -39,6 +39,13 @@ grpc_listen_addr: 127.0.0.1:50443
 # are doing.
 grpc_allow_insecure: false
 
+# CIDR(s) of reverse proxies (e.g. 127.0.0.1/32) whose
+# True-Client-IP, X-Real-IP and X-Forwarded-For headers should
+# be honoured. Empty (default) ignores those headers; setting
+# this without a proxy in front lets clients spoof their logged
+# source IP.
+trusted_proxies: []
+
 # The Noise section includes specific configuration for the
 # TS2021 Noise protocol
 noise:

docs/ref/integration/reverse-proxy.md

@@ -31,6 +31,30 @@ tls_cert_path: ""
 tls_key_path: ""
 ```
 
+### Trusted proxies
+
+Headscale ignores `True-Client-IP`, `X-Real-IP` and `X-Forwarded-For`
+unless the request's TCP peer matches `trusted_proxies`. Set this to
+the CIDR(s) your reverse proxy connects from so the real client IP
+appears in access logs:
+
+```yaml title="config.yaml"
+trusted_proxies:
+  - 127.0.0.1/32
+  - ::1/128
+```
+
+The reverse proxy must also strip any client-supplied
+`True-Client-IP` / `X-Real-IP` / `X-Forwarded-For` on inbound requests
+and set its own values. nginx's `$proxy_add_x_forwarded_for` only
+appends to whatever the client sent — pair it with
+`proxy_set_header X-Real-IP $remote_addr;` and clear the inbound XFF
+yourself if your nginx version does not do so.
+
+Leaving `trusted_proxies` empty when there is no proxy in front is
+safe: the headers are dropped from every request and the access log
+shows the directly-connecting TCP peer.
+
 ## nginx
 
 The following example configuration can be used in your nginx setup, substituting values as necessary. `<IP:PORT>` should be the IP address and port where headscale is running. In most cases, this will be `http://localhost:8080`.