# HG changeset patch
# User Ruslan Ermilov
-On FreeBSD, AIO is usable used starting from FreeBSD 4.3. +On FreeBSD, AIO is usable starting from FreeBSD 4.3. AIO can either be linked statically into a kernel:
options VFS_AIO @@ -21,9 +21,9 @@ In FreeBSD versions 5 and 6, enabling AIO statically, or dynamically when booting the kernel, will cause the entire networking subsystem to use the Giant lock that can impact overall performance negatively. -This limitation has been removed in FreeBSD 6.4-STABLE in 2009, and in -FreeBSD 7. -However, starting from FreeBSD 5.3, it's possible to enable AIO +This limitation has been removed in FreeBSD 6.4-STABLE in 2009, and in +FreeBSD 7. +However, starting from FreeBSD 5.3 it is possible to enable AIO without the penalty of running the networking subsystem under a Giant lock - for this to work, the AIO module needs to be loaded after the kernel has booted. @@ -46,19 +46,19 @@ sendfile needs to be disabled:-location /video/ { - sendfile off; - aio on; - output_buffers 1 64k; +location /video/ { + sendfile off; + aio on; + output_buffers 1 64k; }-In addition, starting from FreeBSD 5.2.1 and nginx 0.8.12, AIO can +In addition, starting from FreeBSD 5.2.1 and nginx 0.8.12, AIO can also be used to pre-load data for
sendfile()
:In this configuration,-location /video/ { - sendfile on; - tcp_nopush on; - aio sendfile; +location /video/ { + sendfile on; + tcp_nopush on; + aio sendfile; }sendfile()
is called with @@ -76,17 +76,17 @@ directio, otherwise reading will be blocking:-location /video/ { - aio on; - directio 512; - output_buffers 1 128k; +location /video/ { + aio on; + directio 512; + output_buffers 1 128k; }On Linux, directio can only be used for reading blocks that are aligned on 512-byte boundaries (or 4K for XFS). -Reading of unaligned file's tail is still made in blocking mode. +Reading of unaligned file's end is still made in blocking mode. The same holds true for byte range requests, and for FLV requests not from the beginning of a file: reading of unaligned data at the beginning and end of a file will be blocking. @@ -102,12 +102,14 @@ Defines a replacement for the specified location. For example, with the following configuration
-the request of "/i/top.gif" will be responded -with the file "/data/w3/images/top.gif". +the request of +“-location /i/ { - alias /data/w3/images/; +location /i/ { + alias /data/w3/images/; }/i/top.gif
” will be responded +with the file +“/data/w3/images/top.gif
”.The
path
value can contain variables.@@ -117,21 +119,21 @@ these captures (0.7.40), for example:
location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { - alias /data/w3/images/$1; + alias /data/w3/images/$1; }When location matches the last part of the directive's value:
-it's better to use the +it is better to use the root directive instead:-location /images/ { - alias /data/w3/images/; +location /images/ { + alias /data/w3/images/; }-location /images/ { - root /data/w3; +location /images/ { + root /data/w3; }
syntax:client_body_in_file_only @@ -188,7 +190,7 @@ directory. For example, in the following configuration
a temporary file might look like this:-client_body_temp_path /spool/nginx/client_temp 1 2; +client_body_temp_path /spool/nginx/client_temp 1 2;@@ -212,7 +214,7 @@ For most requests, a buffer of 1K bytes is enough. However, if a request includes long cookies, or comes from a WAP client, it may not fit into 1K. -If a request line, or a request header line do not fit entirely into +If a request line, or a request header field do not fit entirely into this buffer then larger buffers are allocated, configured by the large_client_header_buffers directive. @@ -232,7 +234,7 @@ Sets the maximum allowed size of the client request body, specified in theContent-Length
-request header line. +request header field. Ifsize
is greater than the configured value, the "Request Entity Too Large" (413) error is returned to a client. @@ -259,7 +261,7 @@ for a given request. It could be useful for serving large files:or when using aio on Linux.-directio 4m; +directio 4m;
syntax: @@ -273,42 +275,44 @@ using XFS under Linux, it needs to be increased to 4K.
syntax:error_page -
code ...
+code
... [=
[response
]]uri
default: none
context:http
,server
,location
,if in location
Defines the URI that will be shown for the specified errors. These directives are inherited from the previous level if and -only if there are no
error_page
directives on +only if there are no +error_page +directives on the current level. A URI value can contain variables.-Example usage: +Example:
-error_page 404 /404.html; -error_page 502 503 504 /50x.html; -error_page 403 http://example.com/forbidden.html; +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 response code to another, for example:
-error_page 404 =200 /empty.gif; +error_page 404 =200 /empty.gif;-If an error response is processed by a proxied server, or a FastCGI-server, +If an error response is processed by a proxied server, or a FastCGI server, and the server may return different response codes (e.g., 200, 302, 401 or 404), it is possible to respond with a returned code:
-error_page 404 = /404.php; +error_page 404 = /404.php;If there is no need to change URI during redirection it is possible to redirect error processing into a named location:
location / { - error_page 404 = @fallback; + error_page 404 = @fallback; } location @fallback { - proxy_pass http://backend; + proxy_pass http://backend; }
syntax:if_modified_since @@ -323,13 +327,16 @@
If-Modified-Since
request header: -
off
- the +
off
- +the
If-Modified-Since
request header is ignored (0.7.34); -exact
- exact match; -before
- modification time of a response is +exact
- +exact match; +
before
- +modification time of a response is less than or equal to the time in the
If-Modified-Since
request header. -
syntax: +
syntax:internal
default: none
context:location
@@ -351,11 +358,11 @@ directive of the http_rewrite module.
-Example usage: +Example:
-error_page 404 /404.html; +error_page 404 /404.html; -location /404.html { +location /404.html { internal; }
syntax: @@ -375,12 +382,12 @@ The first argument sets a timeout during which a keep-alive client connection will stay open on the server side. The optional second argument sets a value in the -"Keep-Alive: timeout=
time
" +“Keep-Alive: timeout=
” response header. Two arguments may differ.time
The -"
Keep-Alive: timeout=
" +“Keep-Alive: timeout=
” is understood by Mozilla and Konqueror. MSIE will close keep-alive connection in about 60 seconds.
syntax: @@ -392,7 +399,7 @@ A request line cannot exceed the size of one buffer, or the "Request URI too large" (414) error is returned. -A request header line cannot exceed the size of one buffer as well, or the +A request header field cannot exceed the size of one buffer as well, or the "Bad request" (400) error is returned. Buffers are allocated only on demand. @@ -412,9 +419,9 @@ http_auth_basic modules directives:Please note that this will limit access to all methods @@ -440,7 +447,7 @@ server { if ($slow) { - set $limit_rate 4k; + set $limit_rate 4k; } ... @@ -457,8 +464,8 @@-limit_except GET { - allow 192.168.1.0/32; - deny all; +limit_except GET { + allow 192.168.1.0/32; + deny all; }location /flv/ { flv; - limit_rate_after 500k; - limit_rate 50k; + limit_rate_after 500k; + limit_rate 50k; }
syntax:listen @@ -492,16 +499,16 @@ specified. An
address
may also be a hostname, for example:IPv6 addresses (0.7.36) are specified in square brackets:-listen 127.0.0.1:8000; -listen 127.0.0.1; -listen 8000; -listen *:8000; -listen localhost:8000; +listen 127.0.0.1:8000; +listen 127.0.0.1; +listen 8000; +listen *:8000; +listen localhost:8000;-listen [::]:8000; -listen [fe80::1]; +listen [::]:8000; +listen [fe80::1];If only
address
is given, the port 80 is used.@@ -525,32 +532,32 @@ Starting from version 0.8.21, these parameters can be specified in any
listen
directive, but only once for the givenaddress
:port
pair. -
backlog
=number
- +
backlog
=number
- sets the
backlog
parameter in thelisten()
call. By default,backlog
equals -1 on FreeBSD and 511 on other platforms. -rcvbuf
=size
- +rcvbuf
=size
- sets the
SO_RCVBUF
parameter for the listening socket. -sndbuf
=size
- +sndbuf
=size
- sets the
SO_SNDBUF
parameter for the listening socket. -accept_filter
=filter
- +accept_filter
=filter
- sets the name of the accept filter. This works only on FreeBSD, acceptable values are
dataready
andhttpready
. -On receivingSIGHUP
signal, an accept filter can only be +On receipt of theSIGHUP
signal, an accept filter can only be changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE and 4.11-STABLE. -deferred
- +deferred
- instructs to use a deferred
accept()
on Linux using theTCP_DEFER_ACCEPT
option. -bind
- +bind
- specifies to make a separate
bind()
call for a givenaddress
:port
pair. This is because nginx will onlybind()
to*
:port
if there are severallisten
directives with -the same port and different addresses, and one of the +the same port but different addresses, and one of thelisten
directives listens on all addresses for the given port (*
:port
). It should be noted that in this case agetsockname()
@@ -561,11 +568,11 @@deferred
are used then for a givenaddress
:port
pair a separatebind()
call will always be made. -ipv6only
=on
|off
- +ipv6only
=on
|off
- this parameter (0.7.42) sets the value of the
IPV6_V6ONLY
parameter for the listening socket. This parameter can only be set once on start. -ssl
- +ssl
- this parameter (0.7.14) does not relate to system calls
listen()
andbind()
, but allows to specify that all connections accepted on this port should work in @@ -573,12 +580,12 @@ This allows for a more compact configuration for the server operating in both HTTP and HTTPS modes simultaneously.-listen 80; -listen 443 default ssl; -+listen 80; +listen 443 default ssl; +
Example:
-listen 127.0.0.1 default accept_filter=dataready backlog=1024; +listen 127.0.0.1 default accept_filter=dataready backlog=1024;
syntax:location [
=
| @@ -593,8 +600,8 @@ Sets a configuration based on a request URI. A location can either be defined by a prefix string, or by a regular expression. Regular expressions are specified by prepending them with the -"~*
" prefix (for case-insensitive matching), or with the -"~
" prefix (for case-sensitive matching). +“~*
” prefix (for case-insensitive matching), or with the +“~
” prefix (for case-sensitive matching). To find a location matching a given request, nginx first checks locations defined using the prefix strings (prefix locations). Amongst them, the most specific one is searched. @@ -612,29 +619,29 @@ Regular expressions can contain captures (0.7.40) that can later be used in other directives.-If the most specific prefix location has the "
^~
" prefix +If the most specific prefix location has the “^~
” prefix then regular expressions are not checked.-Also, using the "
=
" prefix it's possible to define +Also, using the “=
” prefix it is possible to define an exact match of URI and location. If an exact match is found, the search terminates. -For example, if a "/
" request happens frequently, -defining "location = /
" will speed up the processing +For example, if a “/
” request happens frequently, +defining “location = /
” will speed up the processing of these requests, as search terminates right after the first comparison.In versions from 0.7.1 to 0.8.41, if a request matched the prefix -location without the "
=
" and "^~
" +location without the “=
” and “^~
” prefixes, the search also terminated and regular expressions were not checked.-Let's illustrate the above by an example: +Let's illustrate the above by example:
-The "-location = / { +location = / { [ configuration A ] } -location / { +location / { [ configuration B ] } @@ -646,13 +653,14 @@ [ configuration D ] }/
" request will match configuration A, -the "/documents/document.html
" request - configuration B, -the "/images/1.gif
" request - configuration C, and -the "/documents/1.jpg
" request - configuration D. +The “/
” request will match configuration A, +the “/documents/document.html
” request will match +configuration B, +the “/images/1.gif
” request will match configuration C, and +the “/documents/1.jpg
” request will match configuration D.-The "
@
" prefix defines a named location. -Such a location isn't used for a regular request processing, but instead +The “@
” prefix defines a named location. +Such a location is not used for a regular request processing, but instead used for request redirection.
syntax:log_not_found
on
|off
default: @@ -675,18 +683,18 @@Note that compression is essential for the correct prefix string and regular expressions location matching. -Without it, the "
//scripts/one.php
" request would not match +Without it, the “//scripts/one.php
” request would not matchand might be processed as a static file, -so it gets converted to "location /scripts/ { ... }/scripts/one.php
". +so it gets converted to “/scripts/one.php
”.Turning the compression
off
can become necessary if a URI contains base64-encoded names, since base64 uses the "/" character internally. -However, for security considerations, it's better to avoid turning off +However, for security considerations, it is better to avoid turning off the compression.If a directive is specified on the @@ -724,21 +732,23 @@ directive.
The directive has the following parameters: -
max
- +
max
- sets the maximum number of elements in the cache; on cache overflow the least recently used (LRU) elements get removed; -
inactive
- +inactive
- defines a time, after which the element gets removed from the cache if there were no accesses to it during this time; by default, it is 60 seconds; -
off
- disables the cache. -+
off
+disables the cache. + Example:
-open_file_cache max=1000 inactive=20s; +open_file_cache max=1000 inactive=20s; open_file_cache_valid 30s; open_file_cache_min_uses 2; -open_file_cache_errors on;
syntax: +open_file_cache_errors on; +
open_file_cache_errors on
| off
open_file_cache_errors off
http
, server
, location
@@ -781,7 +791,7 @@ Enables or disables specifying the port in redirects issued by nginx.
read_ahead size
read_ahead 0
read_ahead 0
http
, server
, location
Sets the amount of pre-reading when working with files, in the kernel.
@@ -791,7 +801,7 @@
On FreeBSD, the
fcntl(O_READAHEAD,
size
)
-system call is used, supported in FreeBSD 9.0-CURRENT.
+system call is used, supported in FreeBSD 9.0-CURRENT.
FreeBSD 7 needs to be
patched.
reset_timedout_connection on
| off
reset_timedout_connection
+ on
| off
reset_timedout_connection off
http
, server
, location
Enables or disables resetting of timed out connections.
@@ -822,14 +833,14 @@
http
, server
, location
Sets the address
of a name server, for example:
-resolver 127.0.0.1; +resolver 127.0.0.1;
resolver_timeout time
resolver_timeout 30s
http
, server
, location
Sets a timeout for name resolution, for example:
-resolver_timeout 5s; +resolver_timeout 5s;
root path
root html
-the request of "/i/top.gif" will be responded -with the file "/data/w3/images/top.gif". +“-location /i/ { - root /data/w3; +location /i/ { + root /data/w3; } -
/i/top.gif
” will be responded
+with the file
+“/data/w3/i/top.gif
”.
The path
value can contain variables.
@@ -860,13 +871,13 @@ modules grant access.
location / { - satisfy any; + satisfy any; - allow 192.168.1.0/32; - deny all; + allow 192.168.1.0/32; + deny all; - auth_basic "closed site"; - auth_basic_user_file conf/htpasswd; + auth_basic "closed site"; + auth_basic_user_file conf/htpasswd; }
satisfy_any on
| off
http
Sets a configuration for the virtual server.
There is no clean separation between IP-based (based on the IP address)
-and name-based (based on the Host
header string)
+and name-based (based on the Host
request header field)
virtual servers.
Instead, the listen directives describe all
addresses and ports that should accept connections for a server, and the
@@ -903,53 +914,53 @@
Setting Up Virtual Servers document.
server_name name ...
server_name name
...
server_name hostname
server
Sets names of the virtual server, for example:
server { - server_name example.com www.example.com; + server_name example.com www.example.com; }
The first name becomes a primary server name.
By default, the machine's hostname is used.
-Server names can include an asterisk ("*
")
+Server names can include an asterisk (“*
”)
to replace the first or last part of a name:
server { - server_name example.com *.example.com www.example.*; + server_name example.com *.example.com www.example.*; }
The first two of the above mentioned names can be combined:
server { - server_name .example.com; + server_name .example.com; }
It is also possible to use regular expressions in server names,
-prepending the name with a tilde ("~
"):
+prepending the name with a tilde (“~
”):
server { - server_name www.example.com ~^www\d+\.example\.com$; + server_name www.example.com ~^www\d+\.example\.com$; }
Regular expressions can contain captures (0.7.40) that can later be used in other directives:
server { - server_name ~^(www\.)?(.+)$; + server_name ~^(www\.)?(.+)$; location / { - root /sites/$2; + root /sites/$2; } } server { - server_name _; + server_name _; location / { - root /sites/default; + root /sites/default; } }
@@ -957,25 +968,25 @@ variables that can later be used in other directives:
server { - server_name ~^(www\.)?(?<domain>.+)$; + server_name ~^(www\.)?(?<domain>.+)$; location / { - root /sites/$domain; + root /sites/$domain; } } server { - server_name _; + server_name _; location / { - root /sites/default; + root /sites/default; } }
-Starting from version 0.7.11, it is possible to specify an empty name "": +Starting from version 0.7.11, it is possible to specify an empty name:
It allows this server to process requests without theserver { - server_name www.example.com ""; + server_name www.example.com ""; }
Host
@@ -985,10 +996,8 @@
*.example.com
”mail.*
”server_name_in_redirect on
| off
Host
request header string
+When disabled, the name from the Host
request header field
is used.
-If there's no such a string, an IP address of the server is used.
+If this field is not present, an IP address of the server is used.
server_names_hash_max_size size
server_names_hash_max_size 512
server_tokens on
http
, server
, location
Enables or disables emitting of nginx version in error messages and in the
-Server
response header string.
+Server
response header field.
tcp_nodelay on
| off
tcp_nodelay on
try_files file ... uri
try_files file ...
=code
try_files
+ file
...
+ uri
try_files
+ file
...
+ =code
location
Checks the existence of files in the specified order, and uses
the first found file for request processing; the processing
is performed in this location's context.
It is possible to check the directory existence by specifying
-the slash at the end of a name, e.g. "$uri/
".
+the slash at the end of a name, e.g. “$uri/
”.
If none of the files were found, an internal redirect to the
uri
specified by the last argument is made.
As of version 0.7.51, the last argument can also be a
code
:
location / { - try_files $uri $uri/index.html $uri.html =404; + try_files $uri $uri/index.html $uri.html =404; }
Example when proxying Mongrel:
location / { - try_files /system/maintenance.html - $uri $uri/index.html $uri.html - @mongrel; + try_files /system/maintenance.html + $uri $uri/index.html $uri.html + @mongrel; } location @mongrel { - proxy_pass http://mongrel; + proxy_pass http://mongrel; }
Example for Drupal/FastCGI:
location / { - try_files $uri $uri/ @drupal; + try_files $uri $uri/ @drupal; } location ~ \.php$ { - try_files $uri @drupal; + try_files $uri @drupal; - fastcgi_pass ...; + fastcgi_pass ...; - fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; - fastcgi_param SCRIPT_NAME $fastcgi_script_name; - fastcgi_param QUERY_STRING $args; + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + fastcgi_param SCRIPT_NAME $fastcgi_script_name; + fastcgi_param QUERY_STRING $args; ... other fastcgi_param's } location @drupal { - fastcgi_pass ...; + fastcgi_pass ...; - fastcgi_param SCRIPT_FILENAME /path/to/index.php; - fastcgi_param SCRIPT_NAME /index.php; - fastcgi_param QUERY_STRING q=$uri&$args; + fastcgi_param SCRIPT_FILENAME /path/to/index.php; + fastcgi_param SCRIPT_NAME /index.php; + fastcgi_param QUERY_STRING q=$uri&$args; ... other fastcgi_param's } @@ -1103,24 +1116,24 @@ In the following example,thelocation / { - try_files $uri $uri/ @drupal; + try_files $uri $uri/ @drupal; }try_files
directive is equivalent toAnd here,location / { - error_page 404 = @drupal; - log_not_found off; + error_page 404 = @drupal; + log_not_found off; }location ~ \.php$ { - try_files $uri @drupal; + try_files $uri @drupal; - fastcgi_pass ...; + fastcgi_pass ...; - fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; ... } @@ -1130,22 +1143,22 @@ Example for Wordpress and Joomla:location / { - try_files $uri $uri/ @wordpress; + try_files $uri $uri/ @wordpress; } location ~ \.php$ { - try_files $uri @wordpress; + try_files $uri @wordpress; - fastcgi_pass ...; + fastcgi_pass ...; - fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; ... other fastcgi_param's } location @wordpress { - fastcgi_pass ...; + fastcgi_pass ...; - fastcgi_param SCRIPT_FILENAME /path/to/index.php; + fastcgi_param SCRIPT_FILENAME /path/to/index.php; ... other fastcgi_param's }
syntax: @@ -1157,24 +1170,116 @@ The following mappings are configured by default:types { - text/html html; - image/gif gif; - image/jpeg jpg; + text/html html; + image/gif gif; + image/jpeg jpg; }A sufficiently full mapping table is distributed with nginx in the
conf/mime.types
file.-To make a particular location emit the "
application/octet-stream
" +To make a particular location emit the +“application/octet-stream
” MIME type for all requests, try the following:location /download/ { - types { } - default_type application/octet-stream; + types { } + default_type application/octet-stream; }
syntax:underscores_in_headers
on
|off
default:underscores_in_headers off
context:http
,server
-Enables or disables the use of underscores in client request header strings. -