Trusted Proxies

HitKeep runs behind a reverse proxy in virtually every production setup. Without telling HitKeep which proxies to trust, every request appears to come from the proxy’s IP address — breaking GeoIP resolution, rate limiting, and IP exclusions.

The Problem

When Caddy, Traefik, or nginx sits in front of HitKeep, the real visitor’s IP is passed in a forwarded header (X-Forwarded-For, X-Real-IP). By default HitKeep has no way to know which proxies are legitimate, so it ignores these headers and uses the direct connection IP — your proxy’s IP.

Without trusted proxies configured:

All visitors appear to come from 127.0.0.1 or your proxy’s private IP.
GeoIP shows every visitor as “Unknown”.
IP exclusion rules match the proxy IP, not the visitor’s IP.
Rate limiting applies to the proxy IP, not individual visitors.

Configuration

Set the -trusted-proxies flag (or HITKEEP_TRUSTED_PROXIES env var) to a comma-separated list of CIDRs that represent your reverse proxy or load balancer:

hitkeep -trusted-proxies="127.0.0.1/32,10.0.0.0/8"

Or via environment variable:

HITKEEP_TRUSTED_PROXIES=127.0.0.1/32,10.0.0.0/8

Once a direct connection IP matches a trusted CIDR, HitKeep reads the real client IP from X-Forwarded-For.

Common Configurations

Local Reverse Proxy (same host)

Caddy or nginx running on the same machine:

HITKEEP_TRUSTED_PROXIES=127.0.0.1/32

Docker Compose

Both services in the same Docker network (e.g., 172.16.0.0/12):

HITKEEP_TRUSTED_PROXIES=172.16.0.0/12

Kubernetes

Traffic arriving from the cluster’s pod CIDR:

HITKEEP_TRUSTED_PROXIES=10.0.0.0/8

Cloud Load Balancer

If using an external load balancer, add its egress CIDR. Consult your cloud provider’s documentation for the specific ranges.

Verification

After configuring trusted proxies, use the current-IP endpoint to confirm HitKeep is seeing your real IP:

curl https://your-hitkeep.example/api/user/current-ip \
  -b "hk_token=YOUR_SESSION_COOKIE"

The response should return your actual public IP, not the proxy’s IP. If it still returns the proxy IP, double-check that the CIDR covers the proxy’s address and that the proxy is setting X-Forwarded-For.

Security Note

Only add IP ranges you fully control to the trusted list. A misconfigured or overly broad CIDR allows a client to spoof their IP by setting a X-Forwarded-For header, which undermines rate limiting and IP exclusion rules.

Configuration Reference

Flag	Env Variable	Default	Description
`-trusted-proxies`	`HITKEEP_TRUSTED_PROXIES`	`""`	Comma-separated list of trusted proxy CIDRs (e.g. `10.0.0.0/8,127.0.0.1/32`).

Full reference: Configuration Reference.