When using Nginx as a TLS termination point before passing traffic to HAProxy or other load balancers, the default proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for behavior can create security and logging issues. The directive automatically appends the client IP to any existing X-Forwarded-For header, which might contain untrusted values from upstream.

In security-sensitive environments, you often want Nginx to be the single source of truth for the client IP address. Existing X-Forwarded-For headers might:

• Contain spoofed values from malicious clients
• Create overly long headers that break logging
• Cause confusion in multi-cloud architectures

Here's the complete Nginx configuration approach:

# Clear any existing X-Forwarded-For
proxy_set_header X-Forwarded-For "";

# Set fresh header with only the direct client IP
proxy_set_header X-Forwarded-For $remote_addr;

If you need to maintain a chain of trusted proxies while still clearing untrusted headers:

map $http_x_forwarded_for $cleaned_x_forwarded_for {
    default "";
    "~^(?<trusted>([0-9.]+)(, [0-9.]+)*)$" $trusted;
}

server {
    # ...
    proxy_set_header X-Forwarded-For "$cleaned_x_forwarded_for$remote_addr";
    # ...
}

Verify your setup works by sending test requests:

curl -H "X-Forwarded-For: 1.2.3.4" https://yourdomain.com

Then check your backend logs - you should only see your real client IP, not the spoofed 1.2.3.4 value.

The header clearing operation has negligible performance impact. However, if using complex regex patterns in the map block, consider:

• Moving the map to the http context for reuse
• Limiting the number of captured groups
• Using simple patterns when possible

When using Nginx as a reverse proxy, the common configuration:

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

creates a security and operational issue by appending rather than overwriting the header. This leads to:

• Header value inflation (potentially hitting size limits)
• Potential IP spoofing vulnerabilities
• Inaccurate client IP tracking

Here's the proper way to reset the header:

proxy_set_header X-Forwarded-For $remote_addr;

This configuration:

1. Completely replaces any existing X-Forwarded-For header
2. Sets only the direct client IP address seen by Nginx
3. Follows the principle of least privilege

For more complex scenarios:

Preserving Existing Headers in Multi-Tier Architecture

set_real_ip_from 10.0.0.0/8;
real_ip_header X-Forwarded-For;
proxy_set_header X-Forwarded-For $remote_addr;

Conditional Header Clearing

map $http_x_forwarded_for $clean_xff {
    default $remote_addr;
    "~^$" $remote_addr;
}

server {
    ...
    proxy_set_header X-Forwarded-For $clean_xff;
}

• Always validate $remote_addr against trusted proxies
• Consider using the PROXY protocol instead of X-Forwarded-For
• Monitor header sizes to prevent buffer overflow attacks

The header clearing approach has minimal overhead:

The negligible difference makes security the deciding factor.

Add this to your configuration for troubleshooting:

add_header X-Debug-Original-XFF $http_x_forwarded_for;
add_header X-Debug-Client-IP $remote_addr;

Remember to remove these headers in production environments.