Client IP¶

burrow exposes the client IP framework-wide so contribs (rate limiting today; request logging, geofencing, abuse detection tomorrow) read a single source instead of each rolling their own header parser.

The trust problem¶

There is no safe default for "what's the client IP." r.RemoteAddr is the TCP peer, which is the client if you're directly on the internet and the reverse proxy otherwise. Headers like X-Forwarded-For are useful behind known proxies and trivially spoofable everywhere else. Quoting chi v5.3.0's release notes:

There is no safe default — the user must pick their trust source explicitly.

burrow takes that stance literally: --client-ip-mode is a required choice, and every non-default mode demands its companion flag.

Picking a mode¶

header mode is safe only when your proxy unconditionally overwrites the named header on every request. True-Client-IP, X-Azure-ClientIP, and Fastly-Client-IP look similar but pass client-supplied values through by default in those products — don't use them unless your edge strips the inbound value first.

xff-trusted-proxies is brittle: if you add or remove a proxy hop and forget to update the count, you'll silently start trusting an attacker-supplied IP. Prefer xff-trusted-cidrs whenever you can enumerate the proxy IP ranges.

Reading the result¶

In handlers and middleware:

import "github.com/oliverandrich/burrow"

func handler(w http.ResponseWriter, r *http.Request) error {
    ip := burrow.ClientIP(r.Context())   // string; "" if no middleware ran
    addr := burrow.ClientIPAddr(r.Context()) // netip.Addr; check addr.IsValid()
    // log, rate-limit, geo-lookup, etc.
}

burrow.ClientIP and burrow.ClientIPAddr re-export chi's GetClientIP / GetClientIPAddr, so the framework's source of client IP is the same one chi's middleware populates.

Configuration¶

All four flags accept env-var and TOML sources (consistent with every other burrow flag):

# burrow.toml
[server.client_ip]
mode = "header"
header = "X-Real-IP"

# Or, for a dynamic AWS ALB fleet:
# mode = "xff-trusted-proxies"
# trusted_proxies = 2

Boot fails fast on misconfiguration: setting a companion flag without the matching mode (or selecting a mode without its companion) returns an error from boot rather than silently picking an unintended source.

Migration from the old ratelimit-trust-proxy flag¶

--ratelimit-trust-proxy (removed) was equivalent to:

--client-ip-mode=header --client-ip-header=X-Real-IP

Update your config; contrib/ratelimit now derives its rate-limit key from burrow.ClientIP regardless of which mode you pick.