SoFunction
Updated on 2025-03-04

Implementation of proxy_set_header parameter in nginx

The proxy_set_header directive plays a crucial role when using Nginx as a reverse proxy server. It allows us to customize request header information, add or modify specific information when passing client requests to upstream servers, thereby achieving more flexible proxy functions. This article will explore in-depth the usage of the proxy_set_header instruction, and analyze its role in different application scenarios based on actual scenarios.

1. Overview of the instructions of proxy_set_header

proxy_set_header is a directive in the Nginx configuration that sets the proxy request HTTP header. When Nginx acts as a reverse proxy, it allows customization of requests received from the client or adding new request headers and then forwarding them to the backend server. This is crucial to maintaining the consistency, security and functionality of the HTTP protocol.

2. Syntax of proxy_set_header instruction

The syntax of the proxy_set_header directive is as follows:

proxy_set_header <header-name> <value>;
  • : The name of the HTTP request header to be set or modified.
  • : The new value of the request header, which can be a static string, variable, or expression.
  • value can be a string, a variable, or a combination of them. Nginx provides a wealth of built-in variables that can easily obtain request information, such as:

host: The Host header is the server address used in the HTTP request to specify the request resource. In proxy settings, proxy_set_header Host $host; ensures that the Host field in the request header is passed correctly, avoiding that the Host header in the request is overwritten by the Nginx default value.
X-Forwarded-For: The IP address chain used to record the passing proxy server.
X-Forwarded-Proto: Indicates the protocol (HTTP or HTTPS) used by the original request.
$http_user_agent: User-Agent information for the client.
$request_uri: The URI requested by the client.
X-Real-IP: The X-Real-IP header is used to record the real IP address of the client. In proxy settings, proxy_set_header X-Real-IP $remote_addr; prevents Nginx from rewriting the IP address in the original request, allowing the backend service to recognize the true source of the client.
Origin: Used for CORS (cross-domain resource sharing) requests, indicating the source of the request.

3. Application scenarios of proxy_set_header instruction

Suppose you have a web application server running on the intranet, and you want to expose the application to external users through an Nginx reverse proxy. Here are some possible configuration scenarios:

1. Pass the client IP address:

In a proxy environment, the upstream server cannot directly obtain the client's real IP address. In order for the upstream server to recognize the client's real IP address, the client's IP address can be passed using the proxy_set_header directive.

proxy_set_header X-Real-IP $remote_addr;
  • X-Real-IP is a custom request header field that stores the client's real IP address.
  • The upstream server can obtain the client's IP address by reading the X-Real-IP field.

2. Passing agent information:

In a multi-level proxy environment, upstream servers may need to understand which proxy servers the request passes. The proxy information can be passed using the proxy_set_header directive.

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  • X-Forwarded-For is a standard request header field that stores the client IP address and the IP addresses of all proxy servers, separated by commas.
  • The upstream server can obtain the IP addresses of all proxy servers by reading the X-Forwarded-For field.

3. Support the WebSocket protocol:

The WebSocket protocol is a two-way communication protocol that requires the Upgrade and Connection fields to be set in the request header. The proxy_set_header directive can be used to pass WebSocket protocol information.

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
  • The $http_upgrade variable gets the value of the Upgrade field requested by the client.
  • Set the Connection field to upgrade to indicate that the request is upgraded to the WebSocket protocol.

4. Custom request header information:

In addition to passing client IP address and proxy information, you can also use the proxy_set_header directive to add other custom request headers, such as:

proxy_set_header X-My-Header "My Value";
  • X-My-Header is a custom request header field that stores custom information.
  • The upstream server can obtain custom information by reading the X-My-Header field.

5. Remove the request header information:

The request header field can be removed by using the proxy_set_header directive to set the value of the request header field to "".

proxy_set_header User-Agent "";
  • This removes the User-Agent field in the request header.

6. Cross-domain resource sharing (CORS)

When processing cross-domain requests, the backend server needs to know where the request comes from. By setting the Origin request header, the backend can decide whether to allow the request as needed. For example:

proxy_set_header Origin $http_origin;

This will ensure that the backend server can receive the correct source information and thus make a corresponding CORS response.

Configuration example

server {
    listen 8080;
    server_name your_domain.com;

    location / {
        proxy_pass http://backend_server:80;
        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 Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Origin $http_origin;
        proxy_read_timeout 6000s;
        proxy_set_header X-NginX-Proxy true;
        proxy_http_version 1.1;
        chunked_transfer_encoding off;
    }
}

In this configuration, Nginx forwards the request to the backend_server and passes the client's relevant information through various proxy_set_header instructions.

Notes on proxy_set_header directive

  • Make sure that the set request header field names and values ​​comply with the specifications and avoid conflicts with other request header fields.
  • Make sure the proxy_set_header directives are within the correct location block so that they are only applied to specific requests.
  • Use the proxy_set_header directive with caution to avoid passing sensitive information such as user passwords.
  • When using the proxy_set_header directive, you need to select appropriate variables and values ​​according to the actual situation to ensure that the upstream server can correctly identify and process the request information.

Summarize

The proxy_set_header directive is a very important directive in the Nginx reverse proxy server, providing powerful flexibility for reverse proxy configuration. It allows us to customize request header information, pass client IP address, proxy information, WebSocket protocol information, etc., thereby achieving more flexible proxy functions. When using the proxy_set_header directive, you need to select appropriate variables and values ​​according to the actual situation to ensure that the upstream server can correctly identify and process the request information.

This is the article about the implementation of proxy_set_header parameter in nginx. For more related nginx proxy_set_header parameter content, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!