Synopsis

This module allows you to classify, or map a set of values into a different set of values, storing the result in a variable. The map directive creates the variable, but only performs the mapping operation when (and if) the variable is accessed. There is no performance penalty for processing requests which do not end up referencing the variable.

Example:

map  $http_host  $name  {
  hostnames;
 
  default          0;
 
  example.com      1;
  *.example.com    1;
  test.com         2;
  *.test.com       2;
  .site.com        3;
}

One use for this would be to use a mapping in place of writing lots of server/location directives or redirects:

map $uri $new {
  default               http://www.domain.com/home/;
 
  /aa                   http://aa.domain.com/;
  /bb                   http://bb.domain.com/;
  /john                 http://my.domain.com/users/john/;
}
 
server {
  server_name   www.domain.com;
  rewrite  ^    $new   redirect;
}

Directives

map

map defines the mapping table which will be used to set a variable.

The table has two columns, pattern and value.

Since 0.9.6, regular expressions can be used as patterns using a ~ prefix.

Since 1.0.4, case insensitive regular expressions can be used by prefixing the pattern with ~*.

map $uri $myvalue {
    /aa                   /mapped_aa;
    ~^/aa/(?<suffix>.*)$  $suffix;
}

If you need to have a tilde to start the pattern but not have it be a regular expression, the pattern can be prefixed with a backslash ('\'):

map $http_referer $myvalue {
    Mozilla    1234;
    \~Mozilla  5678;
}

There are three special parameters:

• default — defines the value to be used where no match is found.
• hostnames — it allows for an easier matching of values like host names, names with a starting dot may match exact host names and host names ending with the value, for example:

*.example.com  1; 

Instead of two entries

example.com    1;
*.example.com  1;

we can use only one

.example.com   1;

• include — include values from a file. Multiple includes may be used.

map_hash_max_size

The directive sets the maximum size of a hash table to hold the variable map. For more details see the descriptions of hash settings Optimization section .

map_hash_bucket_size

The directive sets the maximum size in a hash table to map variables. The default value depends on the size of the cache line processor. More see in the descriptions of hash settings in the Optimization section .

References

Original Documentation