Skip to content

docs: describe what the client IP is used for and how to set the header on the proxy - #4709

Open
reinkrul wants to merge 2 commits into
masterfrom
docs/client-ip-header
Open

reinkrul wants to merge 2 commits into
masterfrom
docs/client-ip-header

Conversation

@reinkrul

@reinkrul reinkrul commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Why

The deployment docs only said the node reads X-Forwarded-For "when logging calls" and to check the proxy's documentation. They didn't say what the client IP is used for, how the header is read, or that the proxy has to overwrite it.

This came up while checking whether the node is affected by GO-2026-6875 and GO-2026-6872 (echo): it isn't, because the node always sets echo's IPExtractor and its rate limiter doesn't identify callers. The docs now answer the question "is the client IP used for anything security-related?".

Change

docs/pages/deployment/recommended-deployment.rst:

  • New "Client IP address" section under "Proxy / API Gateway":
    • What the client IP is used for: audit log actor, HTTP request log, peer address in the network logs and diagnostics. Not used to allow, deny or rate-limit requests.
    • The proxy must overwrite the header. Callers that connect to the node directly can set the header themselves.
    • How the node reads X-Forwarded-For and other headers (http.clientipheader).
    • NGINX and HAProxy examples.
  • Production checklist: "sets the header" becomes "overwrites the header … with the address of the caller", with a link to the new section.

No code changes.

Note for reviewers

"Not used to allow, deny or rate-limit requests" is true today (audit/http.go, http/requestlogger.go, http/tokenV2/middleware.go, network/transport/grpc/ip_interceptor.go; the rate limiter in http/ratelimiter.go ignores the caller). If that changes, this section has to change with it.

Testing

make docs-docker: build succeeds, no new warnings.

Backport

The file is the same on V6.2. Backport branch is prepared; PR follows after review.

Assisted by AI

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant