Trusted Proxies

HitKeep runs behind a reverse proxy in virtually every production setup. If HitKeep cannot trust the proxy chain, every request appears to come from the proxy’s IP address, which breaks GeoIP resolution, rate limiting, and IP exclusions.

The Problem

When Caddy, Traefik, nginx, a load balancer, or CloudFront sits in front of HitKeep, the real visitor’s IP is passed in a forwarded header (X-Forwarded-For, X-Real-IP, or CDN-specific headers). If HitKeep does not trust the direct peer, 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.

The default value is *, which trusts forwarded client IP headers from any direct peer. This is convenient for managed and simple proxy setups. For self-hosted production instances, set explicit CIDRs for the reverse proxies or load balancers you control.

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`) or `*` to trust forwarded client IP headers from any direct peer.

Full reference: Configuration Reference.