Skip to main content

Nginx Variables

Introduction

Variables in Nginx provide a powerful way to create dynamic configurations. They allow you to store and manipulate data during request processing, making your Nginx setup more flexible and powerful. Whether you're setting up simple redirects or complex conditional logic, understanding Nginx variables is essential for mastering server configuration.

In this guide, we'll explore how variables work in Nginx, their different types, and how to use them effectively in your configurations.

Understanding Nginx Variables

Nginx variables are placeholders that store values which can be used throughout your configuration files. They help you create dynamic configurations that adapt to different scenarios and conditions.

Key characteristics of Nginx variables:

  • They are prefixed with a dollar sign ($)
  • They are evaluated at runtime for each request
  • Their values can change during request processing
  • They can be used in most configuration directives

Types of Nginx Variables

Nginx has two main types of variables:

  1. Built-in variables: Predefined by Nginx and represent various aspects of the request/response cycle
  2. Custom variables: Defined by you in your configuration files

Built-in Variables

Nginx comes with many built-in variables that provide information about the current request and connection. Here are some commonly used ones:

VariableDescription
$uriCurrent URI (without query string)
$request_uriFull original request URI (with query string)
$argsQuery string parameters
$arg_nameValue of a specific query parameter (name)
$http_user_agentValue of the User-Agent header
$remote_addrClient IP address
$server_nameName of the server processing the request
$request_methodHTTP method (GET, POST, etc.)

Let's look at an example of how to use built-in variables:

nginx
server {
listen 80;
server_name example.com;

location / {
return 200 "URI: $uri
Full request: $request_uri
Your IP: $remote_addr
";
}
}

If a user visits http://example.com/page?id=123, they would see:

URI: /page
Full request: /page?id=123
Your IP: 192.168.1.100

Custom Variables

You can create your own variables using the set directive. This allows you to store and manipulate data during request processing.

nginx
server {
listen 80;
server_name example.com;

# Define a custom variable
set $mobile_device "false";

# Check user agent and set the variable
if ($http_user_agent ~* "mobile|android|iphone|ipad") {
set $mobile_device "true";
}

location / {
return 200 "Is mobile: $mobile_device";
}
}

Variable Evaluation and Scope

Nginx variables are evaluated at runtime for each request. Their scope depends on where they're defined:

  • Variables defined at the http level are available to all server blocks
  • Variables defined at the server level are available to all locations in that server block
  • Variables defined at the location level are only available in that location

Practical Examples

Let's explore some practical examples of using Nginx variables in real-world scenarios.

Example 1: Redirecting based on query parameters

nginx
server {
listen 80;
server_name example.com;

location / {
if ($arg_source = "newsletter") {
set $campaign_source "email_campaign";
return 302 /landing?campaign=$campaign_source;
}

# Normal processing
root /var/www/html;
index index.html;
}
}

This configuration checks if the request has a query parameter source=newsletter and redirects to a landing page with a customized campaign parameter.

Example 2: Conditional logging based on request type

nginx
http {
# Define a custom log format
log_format detailed '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent"';

server {
listen 80;
server_name example.com;

# Initialize log variable
set $log_file "access.log";

# Change log file for API requests
if ($uri ~* "^/api/") {
set $log_file "api.log";
}

# Use variable in access_log directive
access_log /var/log/nginx/$log_file detailed;

location / {
root /var/www/html;
index index.html;
}
}
}

This configuration uses different log files for API requests and regular web requests.

Example 3: Environment-based configuration

nginx
server {
listen 80;
server_name example.com;

# Set default environment
set $environment "production";

# Check for staging subdomain
if ($host = "staging.example.com") {
set $environment "staging";
}

# Set appropriate root directory based on environment
root /var/www/$environment;

location / {
index index.html;

# Show environment banner in staging
if ($environment = "staging") {
add_header X-Environment "STAGING SERVER" always;
}
}
}

This example uses variables to configure different settings based on whether the site is accessed through the production or staging domain.

Advanced Variable Usage

Variable Interpolation

You can include variables within strings for complex configurations:

nginx
server {
listen 80;
server_name example.com;

location / {
set $greeting "Hello";
set $name "World";

# Combine variables
return 200 "$greeting, $name!";
}
}

This would return "Hello, World!" to the client.

Using map for Variable Transformations

The map directive allows you to create new variables based on the values of other variables:

nginx
http {
# Map country codes to full names
map $geoip_country_code $country_name {
default "Unknown";
US "United States";
CA "Canada";
UK "United Kingdom";
FR "France";
DE "Germany";
}

server {
listen 80;
server_name example.com;

location / {
return 200 "Your country: $country_name";
}
}
}

This example maps country codes from GeoIP to full country names for display.

Using Nginx Variables with Proxy Configuration

Variables are particularly useful when configuring proxy settings:

nginx
server {
listen 80;
server_name example.com;

location /api/ {
# Pass the original host header to the backend
proxy_set_header Host $host;

# Pass the real IP address
proxy_set_header X-Real-IP $remote_addr;

# Pass the protocol used by the client
proxy_set_header X-Forwarded-Proto $scheme;

# Set custom headers
proxy_set_header X-API-Client "web";

proxy_pass http://backend_servers;
}
}

Best Practices for Using Nginx Variables

  1. Avoid excessive variable use in performance-critical paths - Variables add processing overhead
  2. Use meaningful variable names - Make your configurations easier to understand
  3. Comment your variable usage - Explain why you're using variables for complex logic
  4. Be careful with variable evaluation in if statements - Nginx processes if directives differently than traditional programming languages
  5. Prefer map over if when possible - The map directive is more efficient for variable transformations

Summary

Nginx variables provide a powerful way to create dynamic, flexible server configurations. By understanding how to use both built-in and custom variables, you can:

  • Create conditional logic in your server configuration
  • Customize request and response handling based on various factors
  • Pass important information between different parts of your configuration
  • Build more sophisticated web server setups

With the knowledge from this guide, you should be able to leverage variables effectively in your Nginx configurations and create more dynamic, adaptable web server setups.

Additional Resources and Exercises

Resources

Exercises

  1. Basic Variable Usage:

    • Create a configuration that displays different content based on the browser's User-Agent
  2. Custom Error Pages:

    • Set up custom error pages that include the original requested URI using variables
  3. Request Routing Challenge:

    • Create a configuration that routes requests to different backend servers based on the request path and query parameters
  4. Logging Enhancement:

    • Extend the default Nginx logging format to include additional variables that would be useful for debugging


If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)