Map

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

Configuration Example

map $remote_addr $limit {
    127.0.0.1    "";
    default      $binary_remote_addr;
}

limit_conn_zone $limit zone=addr:10m;
limit_conn addr 1;

Directives

map

Syntax	map string $variable { ... };
Default	—
Context	stream

Creates a new variable. Its value depends on the first parameter, specified as a string with variables, for example:

set $var1 "foo";
set $var2 "bar";

map $var1$var2 $new_variable {
    default "foobar_value";
}

Here, the variable $new_variable will have a value composed of the two variables $var1 and $var2, or a default value if these variables are not defined.

Note

Since variables are evaluated only when they are used, the mere declaration even of a large number of "map" variables does not add any extra costs to request processing.

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

Source values are specified as strings or regular expressions.

Strings are matched ignoring the case.

A regular expression should either start from the "~" symbol for a case-sensitive matching, or from the "~*" symbols 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 contain text, variable and their combination.

The following special parameters are also supported:

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	indicates that source values can be hostnames with a prefix or suffix mask. This parameter should be specified before the list of values.

For example,

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

The following two records

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

can be combined:

.example.com  1;

include file	includes a file with values. There can be several inclusions.
volatile	indicates that the variable is not cacheable.

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

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 (default)

map_hash_bucket_size

Syntax	map_hash_bucket_size size;
Default	map_hash_bucket_size 32|64|128;
Context	stream

Sets the bucket size for the map variables hash tables. Default value depends on the processor's cache line size. The details of setting up hash tables are provided separately.

map_hash_max_size

Syntax	map_hash_max_size size;
Default	map_hash_max_size 2048;
Context	stream

Sets the maximum size of the map variables hash tables. The details of setting up hash tables are provided separately.