Skip to content

z0 - nginx l7 balancer forwarded headers #364

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tikinang merged 1 commit into from
Jul 22, 2026
Merged

z0 - nginx l7 balancer forwarded headers #364

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion apps/docs/content/guides/networking.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,10 @@ The L7 balancer is **nginx-based**, deployed as 2 HA containers per project. It

The balancer forwards client info via standard headers:
- **`X-Forwarded-For`** / **`X-Real-IP`** — original client IP
- **`X-Forwarded-Proto`** — `https` (original protocol)
- **`X-Forwarded-Proto`** — original protocol (`http` or `https`)
- **`X-Forwarded-Host`** / **`X-Forwarded-Port`** — original host and port

These headers are set by the balancer itself (client-sent values are overwritten), and the `Forwarded` and `Proxy` headers are stripped from incoming requests.

Your app receives plain HTTP but can inspect these headers for the real client info.

Expand Down
43 changes: 43 additions & 0 deletions apps/docs/content/references/networking/l7-balancer-config.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -368,6 +368,49 @@ Configure security-related options:

**Best Practice:** Keep `server_tokens` disabled to avoid revealing server information.

## Forwarded Headers

The balancer sets the following headers on every request proxied to your application. They are always set by the balancer itself, overwriting any values sent by the client, so your application can safely trust them:

<table className="w-full my-1.5">
<thead>
<tr>
<th className="w-fit whitespace-nowrap">Header</th>
<th className="w-fit">Value</th>
</tr>
</thead>
<tbody>
<tr>
<td className="w-fit font-semibold whitespace-nowrap">Host</td>
<td className="w-fit">Host requested by the client</td>
</tr>
<tr>
<td className="w-fit font-semibold whitespace-nowrap">X-Real-IP</td>
<td className="w-fit">Client IP address</td>
</tr>
<tr>
<td className="w-fit font-semibold whitespace-nowrap">X-Forwarded-For</td>
<td className="w-fit">Client IP address appended to any existing chain</td>
</tr>
<tr>
<td className="w-fit font-semibold whitespace-nowrap">X-Forwarded-Proto</td>
<td className="w-fit">Protocol the client used (`http` or `https`)</td>
</tr>
<tr>
<td className="w-fit font-semibold whitespace-nowrap">X-Forwarded-Host</td>
<td className="w-fit">Host requested by the client</td>
</tr>
<tr>
<td className="w-fit font-semibold whitespace-nowrap">X-Forwarded-Port</td>
<td className="w-fit">Port the client connected to</td>
</tr>
</tbody>
</table>

:::note Security
The `Forwarded` (RFC 7239) and `Proxy` headers are stripped from incoming requests and never reach your application. Configure your framework to read the `X-Forwarded-*` headers above instead.
:::

## Advanced Routing Features

The L7 HTTP Balancer supports sophisticated routing beyond basic domain mapping.
Expand Down
Loading