Nginx replace REMOTE_ADDR with X-Forwarded-For

Nginx replace REMOTE_ADDR with X-Forwarded-For

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Nginx replace REMOTE_ADDR with X-Forwarded-For

When a reverse proxy sits between your clients and your application server, $_SERVER['REMOTE_ADDR'] inside PHP will almost always return the IP address of the proxy itself, not the originating client. This is standard HTTP behavior: the direct TCP connection is to the proxy, so the remote endpoint from that socket's perspective is the proxy machine. If you are behind a load balancer or any intermediate layer, relying on REMOTE_ADDR for logging, rate limiting, or security will give you incorrect data.

To get the client IP, you need to configure Nginx to pass the header value stored in X-Forwarded-For into PHP as $_SERVER['HTTP_X_FORWARDED_FOR']. Once that header is available, your PHP logic can decide whether to trust it. The goal isn't to magically rewrite REMOTE_ADDR itself; instead, you expose the forwarded address via a header so your application code can choose to use it.

Configuring Nginx to Pass X-Forwarded-For

Start with the proxy configuration block that handles traffic to your PHP backend. Ensure that the upstream server expects headers from the client and that Nginx forwards them:

location / {
    proxy_pass http://backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

The directive proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for is critical. Without it, Nginx will not populate the header with the client IP chain, and PHP's $_SERVER['HTTP_X_FORWARDED_FOR'] will be empty or undefined. You can verify this by adding a temporary debug line in your application or checking Nginx error/access logs to confirm that the header is present before it reaches PHP.

Reading X-Forwarded-For in PHP

Once Nginx is configured, update your PHP code to read from the header instead of relying solely on REMOTE_ADDR:

$ip = $_SERVER['HTTP_X_FORWARDED_FOR'] ?? $_SERVER['REMOTE_ADDR'];

This fallback ensures that if the header is missing, you still get a value—though it will be the proxy's IP. For logging or analytics, you typically want to prioritize the header when it exists. Note that X-Forwarded-For can contain a comma-separated list of IPs when multiple proxies are in the chain:

192.0.2.60, 203.0.113.43

The first IP is the original client. You can extract it safely:

$forwarded = $_SERVER['HTTP_X_FORWARDED_FOR'] ?? null;
$clientIp = $forwarded ? trim(explode(',', $forwarded)[0]) : $_SERVER['REMOTE_ADDR'];

Trusting Headers Safely

Passing the header through Nginx is necessary, but trusting it blindly can be dangerous if your application is exposed to untrusted networks. In many setups, X-Forwarded-For is populated by intermediaries you control (e.g., your load balancer), so it is safe to trust. However, if your service is also reachable directly from the public internet without a proxy, an attacker could spoof this header and appear to originate from a different IP.

A common pattern is to only use X-Forwarded-For when the request comes through the expected internal interface or via a specific trusted host header. You can enforce this by checking that HTTP_HOST or another trusted indicator matches your internal routing rules before accepting the forwarded address.

Why Not Modify REMOTE_ADDR Directly?

You cannot reliably override $_SERVER['REMOTE_ADDR'] in PHP without altering how Nginx passes data to it. Modifying REMOTE_ADDR directly would require changes at the socket level or using a wrapper that intercepts environment variables, which is complex and error-prone. The standard approach is to let Nginx expose the client IP via headers, then have your application logic decide which source to use. This separation of concerns keeps your configuration clean and your code explicit about what it trusts.

If you are using a framework like Laravel, you can configure the trusted proxy hosts in the application settings so that the framework automatically normalizes REMOTE_ADDR based on the headers you've set up in Nginx.

Our network