The ngx_http_map_module module creates variables whose values depend on values of other variables.

map $http_host $name {
    hostnames;

    default       0;

    example.com   1;
    *.example.com 1;
    example.org   2;
    *.example.org 2;
    .example.net  3;
    wap.*         4;
}

map $http_user_agent $mobile {
    default       0;
    "~Opera Mini" 1;
}

Creates a new variable whose value depends on values of one or more of the source variables specified in the first parameter.

Before version 0.9.0 only a single variable could be specified in the first parameter.

Since variables are evaluated only when used, the mere existence of even a large number of declared “map” variables does not incur any extra costs for request processing.

Parameters inside the map block specify a mapping between source and resulting values.

Source values are specified as strings or regular expressions (0.9.6).

A regular expression should either start from the “~” symbol for a case-sensitive matching, or from the “~*” symbols (1.0.4) for case-insensitive matching. A regular expression can contain named and positional captures that can later be used in other directives along with the resulting variable.

If a source value matches one of the names of special parameters described below, it should be prefixed with the “\” symbol.

The resulting value can be a string or another variable (0.9.0).

The directive also supports three special parameters:

default value

sets the resulting value if the source value matches none of the specified variants. When default is not specified, the default resulting value will be an empty string.

hostnames

allows to specify hostnames with a prefix or suffix mask, as source values, for example,

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

The following two records

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

can be combined:

.example.com  1;

This parameter should be specified before the list of values.

include file

includes a file with values. There can be several inclusions.

If the source value matches more than one of the specified variants, e.g. both mask and regular expression match, the first matching variant will be chosen, in the following order of precedence:

1. string value without a mask
2. longest string value with a prefix mask, e.g. “*.example.com”
3. longest string value with a suffix mask, e.g. “mail.*”
4. first matching regular expression (in order of appearance in a configuration file)
5. default value

map_hash_bucket_size 32|64|128;

Sets the bucket size for the map variables hash tables. Default value depends on the size of the processor’s cache line. Details of setting up hash tables are provided in a separate document.

map_hash_max_size 2048;

Sets the maximum size of the map variables hash tables. Details of setting up hash tables are provided in a separate document.