Trusted proxies

Hibernator limits sign-in attempts per client address, so it must see the real address of each client. This page tells you which proxy hops the frontend believes and how to set them. It also lists what the chart does for security. Every value named here is in the table in configuration.md.

• What the frontend believes
• Behind an ingress
• Set the trusted hops
• An ingress behind a load balancer
• Security

What the frontend believes

The frontend container runs Caddy in front of the API. The API believes a forwarded client address only when it comes from that sidecar. A request that reaches the API port from anywhere else counts as coming from its real source address, whatever X-Forwarded-For it carries.

Caddy decides what the sidecar itself believes:

• By default it believes nobody about X-Forwarded-For. It discards the header the caller sent and replaces it with its own view of the remote host.
• It never takes a client address from PROXY protocol, with any setting. It reads and discards a PROXY header that arrives, and keeps its own view of the remote host.

frontend.trustedProxies is the only setting that lets Caddy accept a client address from a proxy. A PROXY header from a load balancer in front of the frontend has no effect. Caddy sees the client address only when the load balancer keeps the source address of the connection.

Behind an ingress

Behind an ingress, Caddy’s view of the remote host is the ingress. Every user who reaches Hibernator through Traefik, NGINX or a load balancer arrives at Caddy from the address of the ingress pod. The API then sees one address for all users, and every per-IP limit becomes one shared budget:

• All users together share the 10 one-time-code requests and the 20 verify attempts per minute. One person can use up the budget for everyone.
• The audit log records the address of the ingress, not the address of the user.

Set the trusted hops

frontend.trustedProxies names the hops Caddy may believe, and the real client address then reaches the API:

frontend:
  trustedProxies:
    - private_ranges        # Caddy's keyword for the RFC 1918 and loopback ranges
    - 10.42.0.0/16          # or the exact ranges your ingress runs in

Empty (the default) trusts no proxy.

Only you can decide what is safe to trust, because it depends on your network. Anything that can reach the frontend from a trusted range can then claim any client address. Trust only the ranges that your ingress occupies. Do not trust a wider range only because it works.

An ingress behind a load balancer

A common setup is an ingress controller, such as Traefik, behind a cloud load balancer that sends traffic to pod addresses. Caddy then sees the ingress pod as its peer. Set the pod range of the cluster (its node or pod subnets), not the addresses of the load balancer.

The address that arrives is the client’s address only when two conditions are true upstream:

• The ingress learns the client address from the load balancer, through PROXY protocol or a preserved source address.
• The ingress forwards that address, not the address of the hop before it.

Caddy can only pass on what the ingress gives it.

Security

• All containers run as non-root (UIDs 1000 and 65532).
• Users sign in with a one-time code sent by email. The session is a JWT.
• The controller authenticates to the API with an HMAC secret, not with a user token.
• RBAC follows least privilege. The exact grants are in install.md.
• secrets.jwtSecret and secrets.internalApiSecret are required, and the chart does not generate them. In production, supply them from a secret manager, such as Vault, Sealed Secrets or External Secrets Operator, and not from a values file: see install.md.
• The HTTPS port of the frontend (:3443) serves a certificate from a secret that you supply (tls.enabled, tls.secretName). Without the secret, the port serves a certificate from the internal CA of Caddy. Only a caller that does not verify the certificate accepts it. See service-redirection.md.