📒 docs: improve clarity for ProxyHeader and TrustProxy configuration

[Claude]

Description

Users upgrading from v2 to v3 or deploying behind reverse proxies encounter c.IP() returning the proxy's IP instead of the client's real IP from X-Forwarded-For. The issue stems from unclear documentation: setting ProxyHeader alone has no effect—both TrustProxy and TrustProxyConfig must also be configured.

Changes introduced

• Documentation Update: Enhanced four documentation files to clarify the proxy configuration requirements:

  docs/api/ctx.md - c.IP() method documentation:

  • Added info box explaining both TrustProxy and ProxyHeader are required
  • Included two complete configuration examples for reverse proxy scenarios
  • Added cross-references to detailed configuration docs

  docs/api/fiber.md - Configuration reference table:

  • ProxyHeader: Clarified dependency on TrustProxy, added security warning about header spoofing, listed common header values
  • TrustProxy: Detailed behavior when enabled/disabled, explained validation mechanism, corrected documentation to reference c.Scheme() instead of c.Protocol() for X-Forwarded-Proto header handling
  • TrustProxyConfig: Documented all fields (Proxies, Loopback, Private, LinkLocal, UnixSocket) with concrete examples, corrected default value from nil to {} (empty struct)

  docs/guide/reverse-proxy.md:

  • Added "Getting the Real Client IP Address" section with comprehensive setup guide
  • Included security warning about header spoofing
  • Provided table mapping proxy services to recommended headers (Nginx, Cloudflare, Fastly, etc.)
  • Added complete working example with Nginx config + Fiber config
  • Included debugging endpoint example for configuration verification
  • Removed duplicate Nginx configuration - the "Enabling HTTP/2" section now links to the canonical example instead of repeating the config

  docs/whats_new.md - v3 migration guide:

  • Enhanced "Trusted Proxies" section with important note that both TrustProxy and ProxyHeader must be configured together
  • Added ProxyHeader: fiber.HeaderXForwardedFor to the migration example code
  • Added reference link to the detailed reverse proxy guide
  • Updated overview bullet point to mention the ProxyHeader requirement

• Examples:

  // Before (doesn't work - missing TrustProxy)
  app := fiber.New(fiber.Config{
      ProxyHeader: fiber.HeaderXForwardedFor,
  })
  
  // After (correct configuration)
  app := fiber.New(fiber.Config{
      TrustProxy: true,
      ProxyHeader: fiber.HeaderXForwardedFor,
      TrustProxyConfig: fiber.TrustProxyConfig{
          Proxies: []string{"10.10.0.58"},  // or Private: true
      },
  })

Type of change

• Documentation update (changes to documentation)

Checklist

• Conducted a self-review of the code and provided comments for complex or critical parts.
• Updated the documentation in the /docs/ directory for Fiber's documentation.
• Ensured that new and existing unit tests pass locally with the changes.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>🐛 [Bug]: c.IP() is not returning X-Forwarded-For IP</issue_title>
<issue_description>### Bug Description

Upgraded from v2 -> v3, have noticed that all references to c.IP() are the upstream proxy now.

I confirmed the header from nginx has not changed, but appears that all c.IP() calls return the wrong IP (should be returning X-Forwarded-For IP).

Some details below:

app = fiber.New(fiber.Config{
		ProxyHeader:        fiber.HeaderXForwardedFor,
})

Some metrics:

requests_by_ip_total{ip="10.10.0.58"} 323

^ that's proxy, IPs should be upstream X-Forwarded-For.

Some sample output:

X-Forwarded-For: [192.178.10.108] <- public IP
c.IP(): 10.10.0.58 <- proxy IP

How to Reproduce

Steps to reproduce the behavior:

1. Set ProxyHeader: fiber.HeaderXForwardedFor,
2. Attempt to reach from public IP.
3. c.IP() is not X-Forwarded-For IP, but upstream proxy IP.

Expected Behavior

Expected c.IP() to return X-Forwarded-For IP but it is returning upstream proxy IP instead.

Fiber Version

v3.1.0

Code Snippet (optional)

Checklist:

• I agree to follow Fiber's Code of Conduct.
• I have checked for existing issues that describe my problem prior to opening this one.
• I understand that improperly formatted bug reports may be closed without explanation.</issue_description>

<agent_instructions>Please update the documentation to improve clarity for future users.</agent_instructions>

Comments on the Issue (you are @claude[agent] in this section)

@gaby @nwcs-sh can you share your NGINX config? @gaby @nwcs-sh Can you try by only setting `TrustProxy: true` @gaby Thanks, we will update the docs to make it clearer.

• Fixes 🐛 [Bug]: c.IP() is not returning X-Forwarded-For IP #4139

[Copilot]

Pull request overview

Improves Fiber documentation to clarify how to correctly configure ProxyHeader, TrustProxy, and TrustProxyConfig so c.IP() can return the real client IP when running behind reverse proxies (addressing #4139).

Changes:

• Expanded reverse-proxy guide with a new “Getting the Real Client IP Address” section, examples, and a debugging endpoint.
• Updated fiber.Config docs to clarify ProxyHeader/TrustProxy dependencies and add stronger security guidance.
• Updated c.IP() docs with an info box and concrete configuration examples.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
docs/guide/reverse-proxy.md	Adds an end-to-end guide for real client IP extraction behind proxies, including security warning and examples.
docs/api/fiber.md	Clarifies ProxyHeader, TrustProxy, and TrustProxyConfig configuration and security implications in the config reference table.
docs/api/ctx.md	Updates c.IP() documentation with an admonition and working reverse-proxy configurations.

[gaby]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Applied all three changes in commit 4a23b6b:

1. c.Protocol() → c.Scheme() in the TrustProxy description (docs/api/fiber.md:83) — c.Protocol() returns the HTTP version; c.Scheme() is what reads from X-Forwarded-Proto.
2. TrustProxyConfig default nil → {} (docs/api/fiber.md:84) — it's a value type (not a pointer), so the zero value is an empty struct.
3. Deduplicated Nginx config in docs/guide/reverse-proxy.md — the "Enabling HTTP/2" Nginx details block now references the canonical "Complete Example with Nginx" section instead of repeating the same snippet.

[gaby]

@copilot try again

[Copilot]

@copilot try again

The three changes are applied in commit 0325c39 and markdown linting passes, but the push is being rejected by a GitHub branch protection rule on claude/fix-ip-address-return (GH013: Cannot update this protected ref). Could you check the branch protection settings for this branch? Once that's resolved the commit will push automatically.

[gaby]

@claude[agent] Apply the suggestions raised on this pull request

[Copilot]

Pull request overview

Updates Fiber v3 documentation to clarify how to correctly obtain the real client IP (c.IP()) when running behind a reverse proxy, emphasizing the required combination of TrustProxy, ProxyHeader, and a properly configured TrustProxyConfig, plus related security considerations.

Changes:

• Clarifies ProxyHeader, TrustProxy, and TrustProxyConfig behavior and security warnings in the Fiber config reference.
• Expands the reverse proxy guide with a dedicated “real client IP” section, examples, and header recommendations for common providers.
• Updates the v3 migration guide (“What’s New”) and c.IP() API docs to highlight required proxy configuration and link to the reverse proxy guide.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
docs/whats_new.md	Adds migration guidance emphasizing TrustProxy + ProxyHeader for c.IP() and links to reverse proxy docs.
docs/guide/reverse-proxy.md	Adds a comprehensive section on configuring Fiber to read real client IPs behind proxies, with examples and security warning.
docs/api/fiber.md	Improves config reference entries for ProxyHeader, TrustProxy, and TrustProxyConfig (dependencies, behavior, security).
docs/api/ctx.md	Enhances c.IP() documentation with an info box and concrete reverse-proxy configuration examples.

[Copilot]

Pull request overview

This PR updates Fiber v3 documentation to clarify how ProxyHeader, TrustProxy, and TrustProxyConfig work together so users behind reverse proxies can correctly obtain the real client IP via c.IP() (and understand the related security implications).

Changes:

• Clarifies that ProxyHeader only affects c.IP() when TrustProxy is enabled and the proxy is trusted via TrustProxyConfig.
• Expands reverse-proxy guidance with configuration examples, common header mappings, and a verification/debugging snippet.
• Updates v3 migration notes to highlight the required ProxyHeader setting when upgrading.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
docs/whats_new.md	Adds migration guidance emphasizing TrustProxy + ProxyHeader for c.IP() behind proxies.
docs/guide/reverse-proxy.md	Adds a dedicated “real client IP” section with examples, security warning, and troubleshooting guidance.
docs/api/fiber.md	Refines config reference entries for ProxyHeader, TrustProxy, and TrustProxyConfig (behavior + security).
docs/api/ctx.md	Updates c.IP() docs with an info box and concrete proxy configuration examples.

[Copilot]

Pull request overview

Updates Fiber v3 documentation to reduce confusion when running behind reverse proxies, specifically clarifying that c.IP() will not read proxy headers unless TrustProxy and TrustProxyConfig are configured alongside ProxyHeader.

Changes:

• Clarifies ProxyHeader’s dependency on TrustProxy + TrustProxyConfig and adds security guidance about header spoofing.
• Adds a dedicated “real client IP” setup section (with examples and a debugging endpoint) to the reverse proxy guide.
• Updates the v3 migration notes to explicitly call out the ProxyHeader requirement and links to the reverse proxy guide.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
docs/whats_new.md	Adds an explicit migration note that ProxyHeader must be set (in addition to the TrustProxy changes) and links to the reverse proxy guide.
docs/guide/reverse-proxy.md	Adds a new section documenting how to correctly get the real client IP behind a proxy, including examples and security warning.
docs/api/fiber.md	Expands config reference docs for ProxyHeader, TrustProxy, and TrustProxyConfig (including corrected c.Scheme() vs c.Protocol() mention).
docs/api/ctx.md	Enhances c.IP() docs with an info box + concrete configuration examples and cross-references.

[Copilot]

Pull request overview

Documentation-focused update to clarify how Fiber’s reverse-proxy settings (TrustProxy, ProxyHeader, TrustProxyConfig) affect c.IP() and related behavior, targeting common v2→v3 upgrade confusion behind proxies.

Changes:

• Clarifies that ProxyHeader only affects c.IP() when TrustProxy is enabled and the proxy is trusted via TrustProxyConfig.
• Expands the reverse-proxy guide with a dedicated “real client IP” setup section, examples, and security warnings.
• Updates the v3 migration guide and config reference docs to reflect correct proxy-header behavior and defaults.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
docs/whats_new.md	Adds migration notes/examples emphasizing ProxyHeader usage alongside trusted proxy settings.
docs/guide/reverse-proxy.md	Adds a comprehensive “real client IP” configuration section with examples and warnings.
docs/api/fiber.md	Expands config reference entries for ProxyHeader, TrustProxy, and TrustProxyConfig with clearer behavior/security notes.
docs/api/ctx.md	Improves c.IP() docs with an info box and concrete configuration examples for reverse proxies.

[Copilot]

Pull request overview

This PR updates Fiber’s documentation to clarify how ProxyHeader, TrustProxy, and TrustProxyConfig must be configured together for c.IP() to return a client IP when running behind a reverse proxy, improving v2→v3 upgrade guidance and reducing misconfiguration risk.

Changes:

• Clarifies that ProxyHeader alone is insufficient; TrustProxy + trusted proxies (TrustProxyConfig) are required for proxy headers to be honored.
• Expands reverse proxy guidance with configuration examples, common header options, and debugging tips.
• Updates migration docs to highlight the required proxy configuration and link to the reverse-proxy guide.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
docs/whats_new.md	Strengthens v3 migration notes and examples for trusted proxy + ProxyHeader configuration.
docs/guide/reverse-proxy.md	Adds a dedicated “real client IP” section with setup guidance and examples.
docs/api/fiber.md	Expands config reference entries for ProxyHeader, TrustProxy, and TrustProxyConfig (including security notes).
docs/api/ctx.md	Improves c.IP() docs with an info box and concrete reverse-proxy configuration examples.

[welcome]

Congrats on merging your first pull request! 🎉 We here at Fiber are proud of you! If you need help or want to chat with us, join us on Discord https://gofiber.io/discord