By Charles Joseph | Cybersecurity Researcher

 Published on December 26th, 2023

When working with an Nginx server, it’s handy to know that you can use the HTTP headers from incoming requests as variables within your Nginx configuration. This feature opens up a range of possibilities, from enhanced logging to more tailored handling of requests.

Let’s break down how this works and how to use it effectively.

Thank you for signing up, we'll be in contact soon.

Stay One Step Ahead of Cyber Threats

Want to Be the Smartest Guy in the Room? Get the Latest Cybersecurity News and Insights.

Subscribe

We respect your privacy and you can unsubscribe anytime.

Understanding the Basics

First, let’s understand what happens when an HTTP request reaches your Nginx server:

• HTTP Headers: These are part of the request sent by the client (like a web browser) to your server. They can include various types of information, such as the type of browser being used, the preferred language, or the original IP address if the request has passed through a proxy.

How Nginx Converts Headers to Variables

Nginx has a neat way of converting these HTTP headers into variables that you can use in its configuration:

1. Lowercase Conversion: All characters in the header name are converted to lowercase.
2. Dashes to Underscores: All dashes (-) in the header name are replaced with underscores (_).
3. Prefix Addition: The prefix $http_ is added to the start of the header name.

Examples of Converted Headers

Let’s look at two common examples to understand this better:

1. X-Forwarded-For Header:
   • Original Header: X-Forwarded-For
   • Nginx Variable: $http_x_forwarded_for
   • Use Case: This header is often set by proxies to pass the original IP address of the client. In Nginx, you can use this variable to log or make decisions based on the client’s actual IP.
2. Accept-Language Header:
   • Original Header: Accept-Language
   • Nginx Variable: $http_accept_language
   • Use Case: This header indicates the client’s preferred language. You can use it to serve content in the preferred language if available.

Practical Applications in Nginx

1. Enhanced Logging:
   • You can log additional information about each request by including these variables in your Nginx log configuration. For example, logging $http_x_forwarded_for can help you keep track of the original IP addresses that are making requests to your server.
2. Conditional Configuration:
   • You can use these variables in if statements within your Nginx configuration to apply specific rules based on the value of a header. For instance, you could write rules that apply only if the Accept-Language header matches a certain language.

Final Tips

• Be Careful with if Statements: While using if statements in Nginx can be powerful; it’s important to use them cautiously, as they can sometimes lead to unexpected behavior.
• Testing Changes: Always test your Nginx configuration changes in a staging environment before applying them to your production server. This ensures that your server remains stable and reliable.

By understanding and utilizing these Nginx variables, you can significantly enhance the functionality and responsiveness of your server to client requests.

Example Nginx.conf File

Below is an example of an Nginx configuration file (nginx.conf) that utilizes the custom HTTP header variables $http_x_forwarded_for and $http_accept_language. This example demonstrates how to use these variables for logging purposes and conditional configurations.

http {
    # Define log format with custom header variables
    log_format main '[$time_local] $remote_addr - $remote_user "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for" '
                    '"$http_accept_language"';

    server {
        listen 80;
        server_name example.com;
        root /var/www/example.com;

        # Access log with custom format
        access_log /var/log/nginx/access.log main;

        # Conditional configuration based on Accept-Language header
        if ($http_accept_language ~* "^en") {
            # Rules or redirections for English language users
        }

        # Additional server configuration...
    }

    # Other http block configurations...
}

Explanation of the Configuration

1. Log Format Definition:
   • The log_format directive defines a custom log format named main.
   • It includes standard information such as the time, request, and status code, along with the $http_x_forwarded_for and $http_accept_language variables to log the original IP address (if passed by a proxy) and the client’s preferred language.
2. Server Block:
   • The server block sets up a basic configuration for a website.
   • The listen directive specifies the port Nginx listens on.
   • server_name defines the domain name of the server.
   • root specifies the root directory of the server where files are served from.
3. Access Log:
   • The access_log directive uses the custom log format defined earlier to log the details of each request, including the custom headers.
4. Conditional Configuration:
   • The if statement checks if the Accept-Language header starts with English (en). You can insert specific rules or configurations inside this block for users whose preferred language is English.
   • Note: The use of if should be limited and tested thoroughly as it can have unexpected results in some Nginx contexts.

Reference: review this article for all Nginx variables