FAQ

Page Discussion History

Difference between revisions of "HttpMapModule"

(maps can't have complex values for replacements)
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
<span style="color:red">WARNING: this article is obsoleted. Please refer to http://nginx.org/en/docs/ for the latest official documentation.</span>
 +
 
= Synopsis =
 
= 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.
 
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.
Line 37: Line 39:
 
= Directives =
 
= Directives =
 
== map ==
 
== map ==
'''syntax:''' ''map $var1 $var2 { ... }''
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_map_module/map.txt" />
 
+
'''default:''' ''none''
+
 
+
'''context:''' ''http''
+
  
 
'''map''' defines the mapping table which will be used to set a variable.
 
'''map''' defines the mapping table which will be used to set a variable.
Line 54: Line 52:
 
map $uri $myvalue {
 
map $uri $myvalue {
 
     /aa                  /mapped_aa;
 
     /aa                  /mapped_aa;
     ~^/aa/(?<suffix>.*)$  $suffix;
+
     ~^/aa/(?P<suffix>.*)$  $suffix;
 
}
 
}
 
</pre>
 
</pre>
Line 91: Line 89:
  
 
== map_hash_max_size ==
 
== map_hash_max_size ==
'''syntax:''' ''map_hash_max_size number''
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_map_module/map_hash_max_size.txt" />
 
+
'''default:''' ''map_hash_max_size 2048''
+
 
+
'''context:''' ''http''
+
  
 
The directive sets the maximum size of a hash table to hold the variable map. For more details see the descriptions of hash settings [[NginxOptimizations|Optimization section]] .
 
The directive sets the maximum size of a hash table to hold the variable map. For more details see the descriptions of hash settings [[NginxOptimizations|Optimization section]] .
 
  
 
== map_hash_bucket_size ==
 
== map_hash_bucket_size ==
'''syntax:''' ''map_hash_bucket_size n''
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_map_module/map_hash_bucket_size.txt" />
 
+
'''default:''' ''map_hash_bucket_size 32/64/128''
+
 
+
'''context:''' ''http''
+
  
 
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 [[NginxOptimizations|Optimization section]] .
 
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 [[NginxOptimizations|Optimization section]] .
 
  
 
= References =
 
= References =
[http://sysoev.ru/nginx/docs/http/ngx_http_map_module.html Original Documentation]
+
* [http://nginx.org/en/docs/http/ngx_http_map_module.html Original Documentation]
 +
* [http://redant.com.au/blog/manage-ssl-redirection-in-nginx-using-maps-and-save-the-universe/ Advanced Usage - Forcing HTTP/HTTPS via maps]

Revision as of 07:36, 23 August 2013

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

Contents

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

Syntax: map string $variable { ... }
Default:
Context: http
Reference: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>.*)$  $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

Syntax: map_hash_max_size size
Default: 2048
Context: http
Reference: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

Syntax: map_hash_bucket_size size
Default: 32|64|128
Context: http
Reference: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