Mastering Nginx Proxy Header Transmission: Key Configurations and Common Pitfalls

Overview of Nginx Proxy Operation

Nginx acts as a high‑performance reverse proxy, forwarding client requests to backend servers (Web, API, etc.). In addition to the URL and request body, it must correctly handle and forward HTTP header information to ensure request integrity, response security, and a good user experience.

1.1 Interaction Between Nginx and Backend Servers

The proxy_pass directive forwards requests to a specified upstream. For example:

location /api/ {
    proxy_pass http://backend_servers;
}

In this configuration, Nginx passes client request headers such as User-Agent and Authorization to the backend.

Nginx Proxy Header Transmission Mechanism

When proxying, Nginx automatically forwards certain headers but allows explicit modification or addition of others. The transmission is controlled by several directives.

2.1 Default Proxy Header Transmission

Host – the request's host name.

User-Agent – client browser information.

Accept-Encoding – supported compression methods.

Accept-Language – client language preferences.

Referer – the page that initiated the request.

Cookie – client cookie data.

2.2 Common Header Configuration Directives

proxy_set_header

– adds or modifies request headers. proxy_pass_request_headers – enables or disables forwarding of request headers (default on). proxy_pass_request_body – enables or disables forwarding of the request body.

2.3 Using proxy_set_header

Typical configuration to forward client IP information:

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

This ensures the backend receives accurate client IP, the full IP chain, and the original protocol.

2.4 Common Use Cases for proxy_set_header

Client IP transmission – use X-Real-IP and X-Forwarded-For to pass the real client address.

Protocol consistency – forward the original scheme via X-Forwarded-Proto for proper handling of HTTP vs. HTTPS.

Host header modification – in virtual‑host environments, set proxy_set_header Host $host; to preserve the correct domain.

2.5 Controlling Header and Body Forwarding

By default both headers and body are forwarded. They can be disabled when needed:

location / {
    proxy_pass_request_headers off;
    proxy_pass http://backend_servers;
}

or

location / {
    proxy_pass_request_body off;
    proxy_pass http://backend_servers;
}

Common Problems and Solutions

3.1 Client IP Not Passed Correctly

Configure:

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

3.2 Incorrect Host Header

Ensure the correct host is sent:

proxy_set_header Host $host;

3.3 Lost Request Headers

Headers such as Connection or Transfer-Encoding may be stripped. Use proxy_set_header to preserve required headers.

3.4 Security Concerns

Malicious clients can forge headers like X-Forwarded-For. Apply strict access control on Nginx to allow only trusted proxies to modify these headers.

Conclusion

Proper configuration of Nginx's proxy header transmission is essential for reliable and secure web service architectures. By mastering directives such as proxy_set_header, proxy_pass_request_headers, and proxy_pass_request_body, administrators can ensure that client request information reaches backend servers accurately, improving overall system performance and stability.