NGINX Variables Cheat Sheet

Introduction

NGINX is a powerful and versatile web server that serves as the backbone for many of the world’s most popular websites. One of the key features that makes NGINX so flexible is its use of variables. These variables are used to write more dynamic and adaptable configuration files. This cheat sheet provides an overview of the most commonly used NGINX variables, along with some examples on how to use them in your configurations.

Understanding NGINX Variables

Variables in NGINX are denoted by the ‘$’ symbol, followed by the variable name. These variables can represent values ranging from client request headers to specific server configuration details. They can be used in various contexts like ‘rewrite’ rules, ‘location’ blocks, and ‘server’ blocks.

Client Request Variables

These variables are associated with client requests, such as request headers, URI, and query arguments:

• $args – The query string (after the question mark in a URL)
• $http_user_agent – The User-Agent request header
• $http_cookie – The Cookie request header
• $http_referer – The Referer request header
• $request_uri – The full original request URI (with arguments)
• $uri – The current URI in the request (without arguments)

Server Variables

Server variables provide information about the server itself:

• $host – In an HTTP request, the hostname from the ‘Host’ request header, or the server’s IP address if there is no ‘Host’ header.
• $server_protocol – The protocol used in the request, usually ‘HTTP/1.1’ or ‘HTTP/2.0’.
• $server_name – The server name declared in the server block.

Network Variables

Variables related to the network details of the request:

• $remote_addr – The client’s IP address.
• $remote_port – The client’s port.
• $proxy_protocol_addr – The client IP address when using the PROXY protocol.

Connection Variables

These variables relate to the connection process:

• $connection – The connection serial number.
• $connection_requests – The number of requests made through a connection.

Other Useful Variables

Other variables that can be handy in multiple scenarios:

• $status – The response status code.
• $body_bytes_sent – Number of bytes sent to a client, not including the response header.
• $bytes_sent – Number of bytes sent to a client, including the response header.
• $request – Full original request line.
• $request_method – Request method, typically ‘GET’ or ‘POST’.
• $request_length – Request length (including request line, headers, and request body).

Examples of Using NGINX Variables

To effectively utilize these variables, you can incorporate them into various configuration blocks. Below are some practical examples:

Logging with Variables

http {
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                        '$status $body_bytes_sent "$http_referer" '
                        '"$http_user_agent"';
    access_log /var/log/nginx/access.log main;
}

This configuration defines a custom log format using NGINX variables and then specifies the log path.

Conditional Configuration

if ($http_user_agent ~* (googlebot|bingbot)) {
    # Perform actions for matched user agents - e.g., Googlebot
}

Here we use NGINX variables to check for particular user agents and apply configurations accordingly.

Restricting Access

location /admin {
    if ($remote_addr != 123.45.67.89) {
        return 403;
    }
}

This location block restricts access to the ‘/admin’ URL path to a single IP address using the ‘$remote_addr’ variable.

Rewriting URLs

rewrite ^/user/(	extbackslash{d	extbackslash}+)/?$ /user_profile.php?id=$1 last;

The rewrite directive uses NGINX variables to capture numerical user IDs from the URL and passes them as query parameters to a PHP script.

Setting Proxy Headers

location /some/path/ {
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://backend;
}

This block sets headers that forward the client’s real IP address to the proxied server.

Conclusion

NGINX variables are essential for creating efficient and flexible configurations. The above cheat sheet provides a glimpse into the power of variables in NGINX. Familiarizing yourself with these variables can streamline your web server management and enable more complex setups. Practice with the provided examples to master the use of variables in real-world scenarios.