ngx_http_core_module
Directives
Variables
alias
syntax: alias file-path|directory-path;
default: no
context: location
This directive assigns a path to be used for the indicated location. Note that it may look similar to the root directive, but the document root doesn't change, just the file system path used for the request.
For example:
location /i/ {
alias /spool/w3/images/;
}
The request "/i/top.gif" will return the file "/spool/w3/images/top.gif".
It is possible to use variables in the replacement path.
The alias directive cannot be used inside a regex-specified location. If you need to do this you must use a combination of rewrite and root.
client_body_in_file_only
syntax: client_body_in_file_only on|off
default: client_body_in_file_only off
context: http, server, location
The directive enables to store a client request body in a file.
Please note that the file at the request completion will not be removed if the directive is enabled.
The directive can be used for debugging and for the $r->request_body_file method in the ngx_http_perl_module module.
client_body_buffer_size
syntax: client_body_buffer_size the_size
default: client_body_buffer_size 8k/16k
context: http, server, location
The directive specifies the client request body buffer size.
If the request body is more than the buffer, then the entire request body or some part is written in a temporary file.
The default size is equal to two pages size, depending on platform it is either 8K or 16K.
client_body_temp_path
syntax: client_body_temp_path dir-path [ level1 [ level2 [ level3 ] ] ]
default: client_body_temp_path client_body_temp
context: http, server, location
The directive assigns the directory for storing the temporary files in it with the body of the request.
In the dir-path a hierarchy of subdirectories up to three levels are possible.
For example
client_body_temp_path /spool/nginx/client_temp 1 2;
The directory structure will be like this:
/spool/nginx/client_temp/7/45/00000123457
client_body_timeout
syntax: client_body_timeout time
default: client_body_timeout 60
context: http, server, location
Directive sets the read timeout for the request body from client.
The timeout is set only if a body is not get in one readstep. If after this time the client send nothing, nginx returns error "Request time out" (408).
client_header_buffer_size
syntax: client_header_buffer_size size
default: client_header_buffer_size 1k
context: http, server
Directive sets the headerbuffer size for the request header from client.
For the overwhelming majority of requests it is completely sufficient a buffer size of 1K.
However if a big cookie is in the request-header or the request has come from a wap-client the header can not be placed in 1K, therefore, the request-header or a line of request-header is not located completely in this buffer nginx allocate a bigger buffer, the size of the bigger buffer can be set with the instruction large_client_header_buffers.
client_header_timeout
syntax: client_header_timeout time
default: client_header_timeout 60
context: http, server
Directive assigns timeout with reading of the title of the request of client.
The timeout is set only if a header is not get in one readstep. If after this time the client send nothing, nginx returns error "Request time out" (408).
client_max_body_size
syntax: client_max_body_size size
default: client_max_body_size 1m
context: http, server, location
Directive assigns the maximum accepted body size of client request, indicated by the line "Content-Length" in the header of request.
If size is greater the given one, then the client gets the error "Request Entity Too Large" (413).
It is necessary to keep in mind that the browsers do not know how to correctly show this error.
default_type
syntax: default_type MIME-type
default: default_type text/plain
context: http, server, location
default_type assigns the default MIME-type to be used for files where the standard MIME map doesn't specify anything. See also types
Example:
location = /proxy.pac {
default_type application/x-ns-proxy-autoconfig;
}
location = /wpad.dat {
rewrite . /proxy.pac;
default_type application/x-ns-proxy-autoconfig;
}
error_page
syntax: error_page code [ code... ] [ = |=answer-code ] uri
default: no
context: http, server, location, if in location
The directive specifies the URI, which will be showed for the errors indicated.
Example of the use:
error_page 404 /404.html; error_page 502 503 504 /50x.html; error_page 403 http://example.com/forbidden.html;
Furthermore, it is possible to change the code of answer to another, for example:
error_page 404 =200 /.empty.gif;
If an erroneous answer is processed by the proxied or FastCGI server and this server can return the different answer codes, for example, 200, 302, 401 or 404, then it is possible to issue the code returned:
error_page 404 = /404.php;
index
syntax: index file [file...]
default: index index.html
context: http, server, location
Directive determines the file(s) which will be used as the index. It's possible to use variables in the name of file. The presence of the files is checked in the order of their enumeration. A file with an absolute path can be put at the end. Example using a variable:
index index.$geo.html index.0.html /index.html;
internal
syntax: internal
default: no
context: location
internal indicates that the matching location can be used only for so called "internal" requests.
For external requests it will return the error "Not found" (404).
Internal requests are the following:
requests redirected by the instruction error_page
subrequests created by the command include virtual of the "ngx_http_ssi_module" module
requests changed by the instruction rewrite of the "ngx_http_rewrite_module" module
An example to prevent clients fetching error pages directly:
error_page 404 /404.html;
location /404.html {
internal;
}
keepalive_timeout
syntax: keepalive_timeout time [ time ]
default: keepalive_timeout 75
context: http, server, location
Directive assigns the timeout, for keep-alive connections with the client.
The second parameter assigns value in the line "Keep-Alive: timeout=time" in the header of answer.
The parameters can differ from each other. Line "Keep-Alive: timeout=time" understands Mozilla and Konqueror. MSIE itself shuts keep-alive connection approximately after 60 seconds.
large_client_header_buffers
syntax: large_client_header_buffers number size
default: large_client_header_buffers 4 4k/8k
context: http, server
Directive assigns the maximum number and size of buffers for large headers to read from client request.
The request line can not be bigger then the size of one buffer, if the client send a bigger header nginx returns error "Request URI too large" (414).
The longest header line of request also must be not more than the size of one buffer, otherwise the client get the error "Bad request" (400).
Buffers are separated only as needed.
By default the size of one buffer is equal to the size of page, depending on platform this either 4K or 8K, if at the end of working request connection converts to state keep-alive, then these buffers are freed.
limit_except
syntax: limit_except methods {...}
default: no
context: location
Directive limits HTTP-methods, accessible inside location.
For the limitation can be used the directives of modules ngx_http_access_module and ngx_http_auth_basic_module:
limit_except GET {
allow 192.168.1.0/32;
deny all;
}
limit_rate
syntax: limit_rate speed
default: no
context: http, server, location, if in location
Directive assigns the speed of transmission of the answer to client. Speed is assigned in the bytes per second. Limitation works only for one connection, i.e., if client opens 2 connections, then total velocity will be 2 times than higher limited.
If it is necessary to limit speed for the part of the clients at the level of server, then directive limit_rate for this does not be suitable.
Instead of this should be assigned the necessary speed of variable $limit_rate:
server {
if ($slow) {
set $limit_rate 4k;
}
...
}
listen
syntax: listen address:port [ default [ backlog=num | rcvbuf=size | sndbuf=size | accept_filter=filter | deferred | bind ] ]
default: listen 80
context: server
The directive specifies the address and port, on which the server accepts requests. It is possible to specify address or port only, besides, an address can be the server name, for example:
listen 127.0.0.1:8000; listen 127.0.0.1; listen 8000; listen *:8000; listen localhost:8000;
If only address is given, then default port 80 is used.
If the directive has the "default" parameter, then the server, in whom is described this directive, he will be the default server for the address:port pair, but if there are no directives with the "default" parameter, then the default server will be the first server, in whom is described the address:port pair.
In directive listen with parameter default it is possible to indicate several parameters, specific for the system calls listen(2) and bind(2).
backlog=num -- is assigned parameter backlog in call listen(2). By default backlog it is equal to -1.
rcvbuf=size -- is assigned parameter SO_RCVBUF for listening socket.
sndbuf=size -- is assigned parameter SO_SNDBUF for listening socket.
accept_filter=filter -- is assigned name accept-filter.
- It works only to FreeBSD, it is possible to use two filters -- dataready and httpready. On the signal -HUP accept-filter it is possible to change only in the quite last versions FreeBSD: 6.0, 5.4-STABLE and 4.11-STABLE.
deferred -- indicates to use that postponed accept(2) on Linux with
- the aid of option TCP_DEFER_ACCEPT.
bind -- indicates that it is necessary to make bind(2) separately
- for this pair of address:port. The fact is that if are described several directives listen with the identical port, but by different addresses and one of the directives listen listens to on all addresses for this port (*:port), then nginx will make bind(2) only to *:port. It is necessary to consider that in this case for determining the address, on which the connections arrive, is done the system call getsockname(). But if are used parameters backlog, rcvbuf, sndbuf, accept_filter or deferred, then it is always done separately for this pair of address:port bind(2).
Example of the use of the parameters:
listen 127.0.0.1 default accept_filter=dataready backlog=1024;
location
syntax: location [=|~|~*|^~] /uri/ { ... }
default: no
context: server
This directive allows different configurations depending on the URI. It can be configured using both conventional strings and regular expressions. To use regular expressions, you must use the prefix ~* for case insensitive match and ~ for case sensitive match.
To determine which location directive matches a particular query, the conventional strings are checked first. Conventional strings match the beginning portion of the query and are case-sensitive - the most specific match will be used (see below on how nginx determines this). Afterwards, regular expressions are checked in the order defined in the configuration file. The first regular expression to match the query will stop the search. If no regular expression matches are found, the result from the convention string search is used.
There are two ways to modify this behavior. The first is to use the prefix "=", which matches an exact query only. If the query matches, then searching stops and the request is handled immediately. For example, if the request "/" occurs frequently, then using "location = /" will expedite the processing of this request.
The second is to use the prefix ^~. This prefix is used with a conventional string and tells nginx to not check regular expressions if the path provided is a match. For instance, "location ^~ /images/" would halt searching if the query begins with /images/ - all regular expression directives would not be checked.
Furthermore it is important to know that NGINX does the comparison not URL encoded, so if you have a URL like "/images/%20/test" then use "/images/ /test" to determine the location.
To summarize, the order in which directives are checked is as follows:
- Directives with the = prefix that match the query exactly. If found, searching stops.
- All remaining directives with conventional strings, longest match first. If this match used the ^~ prefix, searching stops.
- Regular expressions, in order of definition in the configuration file.
- If #3 yielded a match, that result is used. Else the match from #2 is used.
Example:
location = / {
# matches the query / only.
[ configuration A ]
}
location / {
# matches any query, since all queries begin with /, but regular
# expressions and any longer conventional blocks will be
# matched first.
[ configuration B ]
}
location ^~ /images/ {
# matches any query beginning with /images/ and halts searching,
# so regular expressions will not be checked.
[ configuration C ]
}
location ~* \.(gif|jpg|jpeg)$ {
# matches any request ending in gif, jpg, or jpeg. However, all
# requests to the /images/ directory will be handled by
# Configuration C.
[ configuration D ]
}
Example requests:
/ -> configuration A
/documents/document.html -> configuration B
/images/1.gif -> configuration C
/documents/1.jpg -> configuration D
Note that you could define these 4 configurations in any order and the results would remain the same.
How nginx Determines Which Path Matches
Most users will not need to know how nginx internally determines which path to use - know that it will choose the "most specific" match for your URL in a speedy and efficient manner. For those that are curious, however, read on.
All path strings are sorted alphabetically. nginx then proceeds to search down the list looking for matches until the request URI has a "higher" value then the current string in the sorted list. This is determined using the family of strcmp() functions - once strcmp() returns 1, then searching stops. Once searching stops, the last string which matched is used.
For example, lets say we have the following paths:
/ /a /apple /banana
Now, lets say the server gets the path "/az". nginx would begin search down this list. First, "/" would match, but "/ is less than "/az" so searching continues. "/a" also matches, but "/a" is still less than "/az" so we continue again. "/apple" does not match. The next string, "/banana", is greater than "/az" so searching stops and the last match, "/a", would be used.
msie_padding
syntax: msie_padding [on|off]
default: msie_padding on
context: http, server, location
This directive enables or disables the the msie_padding feature for MSIE browsers. When this is enabled Nginx will pad the size of the response headers up to 512 bytes for responses with status codes of more than 400. This prevents activating the "friendly" http error pages feature of the relevant browsers, so as to not hide the possibly more informative error pages.
msie_refresh
syntax: msie_refresh [on|off]
default: msie_refresh off
context: http, server, location
This directive allows or forbids issuing a refresh instead of doing a redirect for MSIE.
optimize_server_names
syntax: optimize_server_names [ on|off ]
default: optimize_server_names on
context: http, server
Directive activates or deactivates optimization of host name checks for name-based virtual servers.
In particular, the check influences the name of the host used in redirects. If optimization is on, and all name-based servers listening on one address:port pair have identical configuration, then names are not checked during request execution and redirects use first server name.
If redirect must use host name passed by the client, then the optimization must be turned off.
port_in_redirect
syntax: port_in_redirect [ on|off ]
default: port_in_redirect on
context: http, server, location
Directive allows or prevents port indication in redirects handled by nginx.
recursive_error_pages
syntax: recursive_error_pages [on|off]
default: recursive_error_pages off
context: http, server, location
recursive_error_pages enables or disables following a chain of error_page directives.
root
syntax: root path
default: root html
context: http, server, location, if in location
root specifies the document root for the requests. For example, with this configuration
location /i/ {
root /spool/w3;
}
A request for "/i/top.gif" will return the file "/spool/w3/i/top.gif". You can use variables in the argument.
satisfy_any
syntax: satisfy_any [ on|off ]
default: satisfy_any off
context: location
Directive solves access with at least one successful checking, executed by modules ngx_http_access_module or ngx_http_auth_basic_module:
location / {
satisfy_any on;
allow 192.168.1.0/32;
deny all;
auth_basic "closed site";
auth_basic_user_file conf/htpasswd;
}
send_timeout
syntax: send_timeout the time
default: send_timeout 60
context: http, server, location
Directive assigns response timeout to client. Timeout is established not on entire transfer of answer, but only between two operations of reading, if after this time client will take nothing, then nginx is shutting down the connection.
sendfile
syntax: sendfile [ on|off ]
default: sendfile off
context: http, server, location
Directive activate or deactivate the usage of sendfile().
server
syntax: server {...}
default: no
context: http
Directive assigns configuration for the virtual server.
There is no clear separation of the virtual servers ip-based (on the basis ip- address) and name-based (on the basis of the name, transferred in the line "Host" of the title of request).
Instead of this by directives listen are described all addresses and ports, on which it is necessary to assume connections for this server, and in directive server_name are indicated all names of servers. The example to configurations is described in tuning of virtual servers.
server_name
syntax: server_name name [... ]
default: server_name hostname
context: server
Directive assigns the names of virtual server, for example:
server {
server_name example.com www.example.com;
}
The first name becomes the basic name of server. By default the name of the machine (hostname) is used. It is possible to use "*" for replacing the first part of the name:
server {
server_name example.com *.example.com;
}
Two of the given name of the above example can be combined into one:
server {
server_name .example.com;
}
The basic name of server is used in an HTTP redirects, if no a "Host" header was in client request or that header does not match any assigned server_name. You can also use just "*" to force Nginx to use the "Host" header in the HTTP redirect (note that "*" cannot be used as the first name, but you can use a dummy name such as "_" instead):
server {
server_name example.com *;
}
server {
server_name _ *;
}
server_names_hash_max_size
syntax: server_names_hash_max_size number
default: server_names_hash_max_size 512
context: http
Directive assigns the maximum size of the hash-tables of the names of servers. In greater detail see in the description of tuning hash.
server_names_hash_bucket_size
syntax: server_names_hash_bucket_size number
default: server_names_hash_bucket_size 32/64/128
context: http
Directive assigns the size of basket in the hash-tables of the names of servers. This value by default depends on the size of the line of processor cache. In greater detail see in the description of tuning hash.
tcp_nodelay
syntax: tcp_nodelay [on|off]
default: tcp_nodelay on
context: http, server, location
This directive allows or forbids the use of the socket option TCP_NODELAY. Only included in keep-alive connections.
Want to know more about the TCP_NODELAY socket option? ReadMoreAboutTcpNodelay
tcp_nopush
syntax: tcp_nopush [on|off]
default: tcp_nopush off
context: http, server, location
This directive permits or forbids the use of the socket options TCP_NOPUSH on FreeBSD or TCP_CORK on Linux. This option is only available when using sendfile.
- Setting this option causes nginx to attempt to send it's HTTP response headers in one packet on Linux and FreeBSD 4.x
types
syntax: types {...}
context: http, server, location
Directive assigns the correspondence of expansion and MIME-types of answers. To one MIME- type can correspond several expansions. By default it is used these correspondences:
types {
text/html html;
image/gif gif;
image/jpeg jpg;
}
The sufficiently complete table of mappings is included and is located in file conf/mime.types.
So that for that determined location'a for all answers would reveal MIME- type "application/octet-stream", it is possible to use the following:
location /download/ {
types { }
default_type application/octet-stream;
}
Variables
The module ngx_http_core_module supports the built-in variables, whose names correspond with the names of variables in Apache.
First of all, these are the variables, which represent the lines of the title of the client request, for example, $http_user_agent, $http_cookie and so forth.
Furthermore, there are other variables:
$args, this variable is equal to arguments in the line of request;
$content_length, this variable is equal to line "Content-Length" in the header of request;
$content_type, this variable is equal to line "Content-Type" in the header of request;
$document_root, this variable is equal to the value of directive root for the current request;
$document_uri, the same as $uri;
$host, this variable is equal to line "Host" in the header of request or name of the server, to whom the request arrived, if there is no this line;
$limit_rate, the variable allows to limit connection rate;
$request_method, this variable is equal to the method of request, usually this "GET" or "POST";
$remote_addr, this variable is equal to the address of client;
$remote_port, this variable is equal to the port of client;
$remote_user, this variable is equal to the name of user, authenticated by ngx_http_auth_basic_module;
$request_filename, this variable is equal to path to the file for the current request, formed from directives root or alias and URI request;
$request_body_file, ???
$request_uri, this variable is equal to the complete initial URI together with the arguments;
$query_string, the same as $args;
$scheme, the HTTP scheme (http, https). Evaluated only on demand, for example:
rewrite ^(.+)$ $scheme://example.com$1 redirect;
$server_protocol, this variable is equal to the protocol of request, usually this "HTTP/1.0" or "HTTP/1.1";
$server_addr, the variable is equal to the server address, to whom arrived the request. As a rule, for obtaining the value of this variable is done one system call. In order to avoid system call, it is necessary to indicate addresses in directives listen and to use parameter bind;
$server_name, this variable is equal to the name of the server, to whom arrived the request;
$server_port, this variable is equal to the port of the server, to which the request arrived;
$uri, this variable is equal to current URI in the request, it can differ from initial, for example by internal redirects, or with the use of index it is file with internal redirects.