Proxy headers forwarding in Nginx - Commands & Configuration

Introduction

When you use Nginx as a proxy server, it forwards requests to another server. Proxy headers forwarding means sending important information like the original client's IP address and protocol to the backend server. This helps the backend know who made the request and how it was made.

When you want your backend server to know the real IP address of the user visiting your website.

When your backend needs to know if the original request was made over HTTP or HTTPS.

When you want to keep track of the original host name requested by the client.

When you use Nginx as a reverse proxy in front of an application server.

When you want to pass custom headers from Nginx to your backend for logging or security.

Config File - nginx.conf

nginx.conf

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://localhost:8080;
        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;
    }
}

This configuration sets up Nginx to listen on port 80 for requests to example.com.

The proxy_pass directive forwards requests to a backend server running on localhost port 8080.

The proxy_set_header lines add headers to the forwarded request:

• Host sends the original host requested by the client.
• X-Real-IP sends the client's real IP address.
• X-Forwarded-For adds the client's IP to the chain of forwarded IPs.
• X-Forwarded-Proto tells the backend if the original request was HTTP or HTTPS.

Commands

This command tests the Nginx configuration file for syntax errors before applying changes.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

This command reloads Nginx to apply the new configuration without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

This command sends a simple HTTP request to check if Nginx is forwarding requests properly.

Terminal

curl -I http://example.com

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Wed, 01 Jan 2025 12:00:00 GMT

Content-Type: text/html

Content-Length: 612

Connection: keep-alive

→

-I - Fetch only HTTP headers without the body

Key Concept

If you remember nothing else from this pattern, remember: forwarding the original client information in headers lets your backend know who made the request and how.

Common Mistakes

Not setting the X-Forwarded-For header in the proxy configuration.

The backend server will not know the real client IP, only the proxy's IP.

Always include proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; to pass the client IP chain.

Forgetting to reload Nginx after changing the configuration.

Changes won't take effect until Nginx reloads or restarts.

Run sudo systemctl reload nginx to apply changes safely.

Setting Host header incorrectly or not at all.

Backend may reject requests or behave unexpectedly if it doesn't receive the correct Host header.

Set proxy_set_header Host $host; to forward the original host requested.

Summary

Use proxy_set_header directives to forward client IP, host, and protocol to the backend.

Test your Nginx configuration with nginx -t before reloading.

Reload Nginx to apply changes without downtime using systemctl reload nginx.

Practice

1. What is the main purpose of using proxy_set_header in an nginx proxy configuration?

easy

A. To cache static files on the proxy server

B. To block client requests based on IP address

C. To compress responses from the backend server

D. To forward original client information like IP and Host to the backend server

Solution

1. Step 1: Understand proxy_set_header role

   The directive proxy_set_header is used to set or override HTTP headers sent to the backend server.

2. Step 2: Identify what headers are forwarded

   It forwards client info such as IP address, Host, and protocol to help backend servers process requests correctly.

3. Final Answer:

   To forward original client information like IP and Host to the backend server -> Option D

4. Quick Check:

   proxy_set_header forwards client info = D [OK]

Hint: Remember proxy_set_header sends client info to backend [OK]

Common Mistakes:

• Thinking it blocks requests
• Confusing it with caching or compression
• Assuming it modifies client requests directly

2. Which of the following is the correct syntax to forward the original client IP address in nginx proxy configuration?

easy

A. proxy_set_header X-Real-IP $proxy_addr;

B. proxy_pass_header X-Real-IP $remote_addr;

C. proxy_set_header X-Real-IP $remote_addr;

D. proxy_forward_header X-Real-IP $remote_addr;

Solution

1. Step 1: Identify correct directive for setting headers

   The correct directive to set headers in nginx proxy is proxy_set_header.

2. Step 2: Use correct variable for client IP

   The variable $remote_addr holds the original client IP address.

3. Final Answer:

   proxy_set_header X-Real-IP $remote_addr; -> Option C

4. Quick Check:

   proxy_set_header + $remote_addr = B [OK]

Hint: Use proxy_set_header with $remote_addr for client IP [OK]

Common Mistakes:

• Using wrong directive like proxy_pass_header
• Using $proxy_addr which is invalid
• Confusing proxy_set_header with proxy_forward_header

3. Given this nginx proxy snippet:

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

What will be the value of the X-Forwarded-For header sent to the backend if the client IP is 192.168.1.10 and the header already contains 10.0.0.1?

medium

A. 192.168.1.10

B. 10.0.0.1, 192.168.1.10

C. 10.0.0.1

D. $proxy_add_x_forwarded_for

Solution

1. Step 1: Understand $proxy_add_x_forwarded_for variable

   This variable appends the client IP to the existing X-Forwarded-For header, separated by a comma.

2. Step 2: Combine existing and client IP

   Since the header already has 10.0.0.1, and client IP is 192.168.1.10, the result is "10.0.0.1, 192.168.1.10".

3. Final Answer:

   10.0.0.1, 192.168.1.10 -> Option B

4. Quick Check:

   $proxy_add_x_forwarded_for appends IP = C [OK]

Hint: Remember $proxy_add_x_forwarded_for appends client IP [OK]

Common Mistakes:

• Assuming it replaces the header instead of appending
• Confusing $proxy_add_x_forwarded_for with $remote_addr
• Expecting only client IP without existing values

4. You configured nginx proxy with:

proxy_set_header X-Forwarded-Proto $scheme;

But the backend always receives http even when client uses https. What is the likely cause?

medium

A. nginx is not configured to listen on HTTPS, so $scheme is always http

B. proxy_set_header syntax is incorrect

C. Backend server ignores X-Forwarded-Proto header

D. You must use $https variable instead of $scheme

Solution

1. Step 1: Understand $scheme variable behavior

   $scheme reflects the protocol used by the client to connect to nginx (http or https).

2. Step 2: Check nginx HTTPS configuration

   If nginx is not listening on HTTPS, all requests come as http, so $scheme is always "http".

3. Final Answer:

   nginx is not configured to listen on HTTPS, so $scheme is always http -> Option A

4. Quick Check:

   $scheme depends on nginx listener protocol = A [OK]

Hint: Check if nginx listens on HTTPS for $scheme to be https [OK]

Common Mistakes:

• Thinking proxy_set_header syntax is wrong
• Assuming backend ignores header without checking
• Using $https variable which is not standard

5. You want to forward the original client IP, host, and protocol to your backend server behind nginx proxy. Which complete configuration snippet correctly forwards these headers?

hard

A. proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;

B. proxy_set_header X-Real-IP $proxy_addr;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $https;

C. proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Host $proxy_host;
proxy_set_header X-Forwarded-Proto $scheme;

D. proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $http_scheme;

Solution

1. Step 1: Verify variables for client IP, host, and protocol

   $remote_addr is client IP, $host is original host header, and $scheme is protocol (http or https).

2. Step 2: Check each option for correctness

   proxy_set_header X-Real-IP $remote_addr; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; uses correct variables and syntax. Others use invalid variables like $proxy_addr, $proxy_host, or $http_scheme which do not exist.

3. Final Answer:

   proxy_set_header X-Real-IP $remote_addr; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; -> Option A

4. Quick Check:

   Use $remote_addr, $host, $scheme for forwarding headers = A [OK]

Hint: Use $remote_addr, $host, and $scheme for correct forwarding [OK]

Common Mistakes:

• Using non-existent variables like $proxy_addr or $proxy_host
• Confusing $https with $scheme
• Missing one or more headers to forward