Proxy headers in Nginx - Commands & Configuration

Introduction

When you use Nginx to forward requests to another server, it needs to send extra information called proxy headers. These headers tell the receiving server details like the original visitor's IP address or the original request protocol. Without these headers, the server might not know where the request really came from or how it was made.

When you want to forward web traffic from Nginx to an application server and keep the visitor's original IP address.

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

When you want to pass the original host name from the client to the backend server.

When you want to add security by controlling which headers are sent to the backend.

When you want to enable logging on the backend server with accurate client information.

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 example.com. It forwards all requests to a backend server running on localhost port 8080.

The proxy_set_header lines add important headers:

• Host sends the original host name.
• X-Real-IP sends the client's IP address.
• X-Forwarded-For adds the client's IP to the chain of forwarded addresses.
• X-Forwarded-Proto tells 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 service.

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 correctly with the proxy headers.

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

Connection: keep-alive

→

-I - Fetch only HTTP headers without the body

Key Concept

If you remember nothing else from this pattern, remember: proxy headers let the backend server know the original client details when Nginx forwards requests.

Common Mistakes

Not setting the X-Real-IP or X-Forwarded-For headers in the proxy configuration.

The backend server will see Nginx's IP instead of the real client IP, causing incorrect logging and security issues.

Always include proxy_set_header X-Real-IP $remote_addr and proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for in your proxy settings.

Forgetting to reload Nginx after changing the configuration.

Changes won't take effect until Nginx reloads, so the proxy headers won't be sent as expected.

Run sudo nginx -t to test, then sudo systemctl reload nginx to apply changes.

Summary

Use proxy_set_header directives in Nginx to send original client information to backend servers.

Test your Nginx configuration with nginx -t before reloading to avoid errors.

Reload Nginx after changes to apply the new proxy header settings.