Nginx Map

7 min read Oct 10, 2024

Nginx Map: A Powerful Tool for Dynamic Configuration

Nginx, the popular web server, is renowned for its performance and flexibility. One of its powerful features is the map directive, which enables you to create and use custom variables within your Nginx configurations. But what exactly is an Nginx map directive and how can it be used to make your configurations more dynamic and efficient? Let's dive in.

What is an Nginx Map?

Think of an Nginx map directive as a lookup table or dictionary within your Nginx configuration. It allows you to associate a specific value with a key. This key-value pair can then be accessed and used dynamically within your server blocks, location blocks, or even within your Nginx rewrite rules.

Why is it useful?

Nginx map directives provide a powerful mechanism for:

Dynamically modifying your Nginx configuration based on request parameters, headers, or other variables. Imagine you want to serve different content based on the user's country. You can use a map to associate country codes with specific server blocks or content locations.
Optimizing your server's response based on specific conditions. For example, you might want to set different caching rules based on the file extension of the requested resource. This can be achieved using a map directive.
Creating custom variables for use in other Nginx directives. This allows you to define your own logic and decision-making within your Nginx configuration.

How does an Nginx Map work?

Here's the basic structure of an Nginx map directive:

map $variable_name $new_variable_name {
  key1 value1;
  key2 value2;
  ...
}

$variable_name: The variable that will be used as the key for the lookup. This can be any existing Nginx variable, such as $remote_addr, $http_user_agent, or even a custom variable defined earlier in your configuration.
$new_variable_name: The name of the new variable that will store the corresponding value from the lookup table.
key1 value1;: Each line defines a key-value pair. The key will be compared against the value of $variable_name. If a match is found, the corresponding value will be assigned to $new_variable_name.

Examples of Nginx Map Usage

Let's look at some practical examples of how you can use map directives in your Nginx configurations.

Serving different content based on user location

Imagine you want to serve a different version of your website to users from a specific country. You can use a map directive to associate country codes with specific server blocks:

map $geoip_country_code $location {
  US /us;
  CA /ca;
  default /;
}

server {
  listen 80;
  server_name example.com;
  root /var/www/html/$location;
}

In this example, we define a map called $location based on the $geoip_country_code variable. This variable would usually be populated by a GeoIP module that identifies the user's location. The map associates specific country codes with different content locations: US users will be served content from /us, Canadian users from /ca, and everyone else from the default location /.

Setting different caching rules based on file type

You can use a map to set different caching rules for different file types:

map $ext $cache_duration {
  \.html 300s;
  \.jpg 600s;
  default 120s;
}

server {
  listen 80;
  location ~* \.(jpg|png|gif)$ {
    expires $cache_duration;
  }
}

This configuration defines a map called $cache_duration based on the $ext variable, which represents the file extension. For HTML files, the cache duration is set to 300 seconds, for images (jpg, png, gif) it's 600 seconds, and for other file types, the default cache duration is 120 seconds.

Nginx Map - Best Practices

Here are some best practices to keep in mind when using map directives:

Define map directives in the http or server context. This ensures that the maps are available globally within your server blocks.
Keep your map definitions concise and focused. Avoid overcomplicating your maps with too many key-value pairs.
Use a consistent naming convention for your map variables. This makes it easier to understand and maintain your Nginx configurations.
Test your map directives carefully. Before deploying any changes, ensure that the map definitions work as expected and do not introduce any unexpected behavior.

Conclusion

The Nginx map directive provides a powerful and flexible mechanism for customizing your Nginx configurations. By using map directives, you can create dynamic configurations that respond to various conditions, such as user location, file type, or other request attributes. This can lead to more efficient, optimized, and user-centric web server configurations.