HttpMapModule

WARNING: this article is obsoleted. Please refer to http://nginx.org/en/docs/ for the latest official documentation.

= 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/(?P .*)$ $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
 * Advanced Usage - Forcing HTTP/HTTPS via maps