What is Nginx proxy_set_header?

Nginx proxy_set_header directive allows you to modify or add HTTP headers when forwarding requests to backend servers. It provides a flexible way to control and customize the headers sent from the Nginx server to the upstream servers. In this tutorial, we will explore Nginx proxy_set_header directive. We will discuss its purpose, usage, and the various ways it can be configured to manipulate HTTP headers. Whether you are new to Nginx or an experienced user, understanding the proxy_set_header directive will enable you to enhance your web server’s functionality and improve the communication between Nginx and backend servers.

What does Proxy_set_header host $host mean?

One of the most common use cases of the proxy_set_header directive is modifying the Host header. The Host header specifies the domain name or IP address of the server to which the client is making a request. The configuration proxy_set_header host $host; sets the Host header in the forwarded request to the same value as the original request’s Host header.

Configuring Headers with proxy_set_header

If you haven’t already set up Nginx as a Reverse Proxy on your server, we recommend referring to our comprehensive article that provides a step-by-step guide. It covers the entire process of configuring Nginx as a reverse proxy, ensuring you have a solid foundation before proceeding further.

Here is a sample configuration demonstrating the usage of the Nginx proxy_set_header directive, which we will explain in this tutorial.

server {
listen 80;
server_name example.com;

location / {
proxy_pass http://backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass_request_headers on;
proxy_hide_header X-Powered-By;
proxy_set_header_if_empty X-Custom-Header "Default Value";
proxy_set_header Strict-Transport-Security $http_strict_transport_security;
proxy_set_header Content-Security-Policy $http_content_security_policy;
}

location /api {
proxy_pass http://backend;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Custom-Header1 "Value1";
proxy_set_header X-Custom-Header2 "Value2";
proxy_hide_header X-Powered-By;
proxy_set_header_if_empty X-Custom-Header "Default Value";
proxy_set_header Strict-Transport-Security $http_strict_transport_security;
proxy_set_header Content-Security-Policy $http_content_security_policy;
}
}

Please note that you may need to adjust the server name (example.com) and the proxy_pass directive to match your specific server setup. Additionally, ensure that the necessary modules are enabled and any other server-specific configurations are in place.

Make sure to test and verify the configuration on your live server before deploying it. Now let break this config:

Starting with configuring headers using the proxy_set_header directive, you can use the following syntax:

proxy_set_header header_name value;

You can include this directive within an Nginx location block, where you define how Nginx handles requests for a specific location. For example:

location /api {
proxy_pass http://backend;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header User-Agent $http_user_agent;
}

In above configuration, the proxy_set_header directive is used to set the X-Forwarded-For header to the client’s IP address ($remote_addr) and the User-Agent header to the value of the original request’s User-Agent header ($http_user_agent).

Anatomy of Nginx proxy_set_header Directive

Nginx proxy_set_header directive consists of two parts: the header name and its value. You can set the header name to any valid HTTP header field name. The value can be a static string or can include variables that represent dynamic values.

For example:

proxy_set_header X-Custom-Header "Hello, World!";

Here, the X-Custom-Header will be set to the static string "Hello, World!" for every forwarded request.

Defining Custom Headers in Nginx

In addition to modifying existing headers, you can also define custom headers using the proxy_set_header directive. Custom headers allow you to send additional information to the backend servers or perform specific actions based on those headers.

Consider the following example:

location /api {
proxy_pass http://backend;
proxy_set_header X-Custom-Header1 "Value1";
proxy_set_header X-Custom-Header2 "Value2";
}

In this configuration, we define two custom headers, X-Custom-Header1 and X-Custom-Header2, with their respective values. These headers can be accessed by the backend servers to perform further processing or authentication.

Preserving Original Client Headers

When proxying requests to upstream servers, it’s often desirable to preserve the original client headers. This ensures that the upstream server receives the same headers as the original client request. Nginx proxy_set_header directive can be used to preserve specific headers or pass all headers to the upstream server.

To preserve specific headers, you can use the following syntax:

proxy_set_header header_name $http_header_name;

For example, to preserve the Accept-Language header:

location /api {
proxy_pass http://backend;
proxy_set_header Accept-Language $http_accept_language;
}

In above configuration, the Accept-Language header from the original client request is passed to the upstream server.

To pass all headers from the client request, you can use the proxy_pass_request_headers directive in combination with proxy_set_header:

location /api {
proxy_pass http://backend;
proxy_pass_request_headers on;
}

With this configuration, all headers from the client request will be passed to the upstream server.

Modifying Headers for Upstream Requests

Nginx proxy_set_header directive can also be used to modify headers for upstream requests. This allows you to customize the headers sent from Nginx to the upstream server.

For example, let’s say you want to add a custom X-Request-ID header to every upstream request. You can achieve this with the following configuration:

location /api {
proxy_pass http://backend;
proxy_set_header X-Request-ID $request_id;
}

In this case, the X-Request-ID header is set to the value of the variable $request_id, which can be a unique identifier generated by Nginx or retrieved from a request header.

Controlling Header Behavior in Nginx

Nginx provides additional directives to control the behavior of headers. Two important directives are proxy_hide_header and proxy_set_header_if_empty.

Nginx proxy_hide_header directive allows you to remove specific headers from the response sent by the upstream server. For example:

location /api {
proxy_pass http://backend;
proxy_hide_header X-Powered-By;
}

Above, the X-Powered-By header will be removed from the response before it is sent to the client.

Nginx proxy_set_header_if_empty directive allows you to set a header only if it does not exist in the upstream response. This is useful when you want to add a default value for a header if it is not already present. Here’s an example:

location /api {
proxy_pass http://backend;
proxy_set_header_if_empty X-Custom-Header "Default Value";
}

In this configuration, the X-Custom-Header will be set to "Default Value" only if it is not already present in the upstream response.

Handling Security and Privacy Headers

When proxying requests, it’s crucial to handle security and privacy headers properly. For example, you might want to ensure that sensitive headers like Strict-Transport-Security or Content-Security-Policy are passed correctly to the client.

To handle security headers, you can use nginx proxy_set_header directive as shown in the following example:

location / {
proxy_pass http://backend;
proxy_set_header Strict-Transport-Security $http_strict_transport_security;
proxy_set_header Content-Security-Policy $http_content_security_policy;
}

In this configuration, the Strict-Transport-Security and Content-Security-Policy headers are passed from the upstream server to the client, preserving their values.

Remember to review the specific security and privacy headers required for your application and adjust the configuration accordingly.

Conclusion

Congratulations! You’ve learned about Nginx proxy_set_header directive and how it can enhance your web server’s functionality. By using this directive, you can modify or add HTTP headers when forwarding requests to backend servers, allowing for greater control and customization. Whether you’re new to Nginx or an experienced user, understanding Nginx proxy_set_header directive empowers you to optimize communication between Nginx and your backend servers.

Remember, modifying the Host header with proxy_set_header is a common use case. This directive allows you to ensure that the Host header in the forwarded request matches the original request, maintaining accurate routing.

Now that you have a comprehensive understanding of the Nginx proxy_set_header directive and its various applications, you are well-equipped to optimize your web server’s performance, enhance security, and improve the overall user experience. So go ahead, implement these techniques, and unleash the full potential of Nginx!