Mercurial > hg > nginx
changeset 4187:b9dade63fcc2
The reference documentation is moving elsewhere.
| author | Ruslan Ermilov <ru@nginx.com> |
|---|---|
| date | Sun, 09 Oct 2011 06:49:54 +0000 |
| parents | cce2fd0acc0f |
| children | ca3230f2c6d8 |
| files | docs/GNUmakefile docs/dtd/module.dtd docs/html/http/ngx_http_core_module.html docs/html/http/ngx_http_mp4_module.html docs/html/ngx_core_module.html docs/xml/http/ngx_http_core_module.xml docs/xml/http/ngx_http_mp4_module.xml docs/xml/ngx_core_module.xml docs/xsls/content.xsls docs/xsls/directive.xsls docs/xsls/module.xsls docs/xslt/content.xslt docs/xslt/directive.xslt docs/xslt/module.xslt |
| diffstat | 14 files changed, 1 insertions(+), 4772 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/GNUmakefile +++ b/docs/GNUmakefile @@ -24,7 +24,7 @@ define XSLT endef -all: changes html +all: changes changes: $(TEMP)/$(NGINX)/CHANGES.ru \ $(TEMP)/$(NGINX)/CHANGES @@ -55,27 +55,3 @@ changes: $(TEMP)/$(NGINX)/CHANGES.ru docs/xslt/changes.xslt: docs/xsls/changes.xsls $(call XSLScript, docs/xsls/changes.xsls, $@) - -html: \ - docs/html/ngx_core_module.html \ - docs/html/http/ngx_http_core_module.html \ - docs/html/http/ngx_http_mp4_module.html - -docs/html/%.html: \ - docs/xml/%.xml \ - docs/xslt/module.xslt \ - docs/dtd/module.dtd - $(call XSLT, docs/xslt/module.xslt, $<, $@) - -docs/html/http/%.html: \ - docs/xml/http/%.xml \ - docs/xslt/module.xslt \ - docs/dtd/module.dtd - $(call XSLT, docs/xslt/module.xslt, $<, $@) - -docs/xslt/module.xslt: \ - docs/xslt/directive.xslt \ - docs/xslt/content.xslt - -docs/xslt/%.xslt: docs/xsls/%.xsls - $(call XSLScript, $<, $@)
deleted file mode 100644 --- a/docs/dtd/module.dtd +++ /dev/null @@ -1,85 +0,0 @@ - -<!ELEMENT module (section+) > -<!ATTLIST module - name CDATA #REQUIRED - id ID #REQUIRED -> - -<!ELEMENT section (directive | para)+ > -<!ATTLIST section - name CDATA #REQUIRED - id ID #IMPLIED -> - -<!ELEMENT directive (syntax+, default, context+, para+) > -<!ATTLIST directive - name ID #REQUIRED - appeared-in CDATA #IMPLIED -> - -<!ELEMENT syntax (#PCDATA | argument | code | parameter | value)* > - -<!ELEMENT default (#PCDATA | code)* > - -<!ELEMENT context (#PCDATA)* > - -<!ELEMENT para (#PCDATA | argument | c-def | c-func | code | command | - dq | emphasis | example | header | http-status | link | - list | note | parameter | pathname | value | var)* > - -<!ELEMENT argument (#PCDATA)* > - -<!ELEMENT c-def (#PCDATA)* > - -<!ELEMENT c-func (#PCDATA)* > - -<!ELEMENT code (#PCDATA | value)* > - -<!ELEMENT command (#PCDATA)* > - -<!ELEMENT dq ANY > - -<!ELEMENT emphasis (#PCDATA)* > - -<!ELEMENT example (#PCDATA)* > - -<!ELEMENT header (#PCDATA | argument)* > - -<!ELEMENT http-status EMPTY > -<!ATTLIST http-status - code CDATA #REQUIRED - text CDATA #IMPLIED -> - -<!ELEMENT link (#PCDATA)* > -<!ATTLIST link - doc CDATA #IMPLIED - id CDATA #IMPLIED - url CDATA #IMPLIED -> - -<!ELEMENT list (listitem+ | (tag-name | tag-desc)+) > -<!ATTLIST list - type (bullet | enum | tag) #REQUIRED -> - -<!ELEMENT listitem ANY > -<!ELEMENT tag-name ANY > -<!ELEMENT tag-desc ANY > - -<!ELEMENT note ANY > - -<!ELEMENT parameter (#PCDATA)* > - -<!ELEMENT pathname (#PCDATA)* > - -<!ELEMENT value (#PCDATA)* > - -<!ELEMENT var (#PCDATA)* > - -<!ENTITY nbsp " " > -<!ENTITY mdash " - " > -<!ENTITY lsquo "‘"> -<!ENTITY rsquo "’"> -<!ENTITY ldquo "“"> -<!ENTITY rdquo "”">
deleted file mode 100644 --- a/docs/html/http/ngx_http_core_module.html +++ /dev/null @@ -1,1287 +0,0 @@ -<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>HTTP Core Module</title></head><body><center><h3>HTTP Core Module</h3></center><a name="directives"></a><center><h4>Directives</h4></center><hr><a name="aio"></a><strong>syntax</strong>: - <code>aio - <code>on</code> | - <code>off</code> | - <code>sendfile</code></code><br><strong>default</strong>: - <code>aio off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><strong>appeared in version</strong>: - 0.8.11<p> -Enables or disables the use of asynchronous file I/O (AIO) -on FreeBSD and Linux. -</p><p> -On FreeBSD, AIO is usable starting from FreeBSD 4.3. -AIO can either be linked statically into a kernel: -<blockquote><pre> -options VFS_AIO -</pre></blockquote> -or loaded dynamically as a kernel loadable module: -<blockquote><pre> -kldload aio -</pre></blockquote></p><p> -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 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. -In this case, the following message will appear in -<code>/var/log/messages</code><blockquote><pre> -WARNING: Network stack Giant-free, but aio requires Giant. -Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0 -</pre></blockquote> -and can safely be ignored. - -The requirement to use the Giant lock with AIO is related to the -fact that FreeBSD supports asynchronous calls -<code>aio_read()</code> -and -<code>aio_write()</code> -when working with sockets. -However, since nginx only uses AIO for disk I/O, no problems should arise. -</p><p> -For AIO to work, -<a href="#sendfile">sendfile</a> -needs to be disabled: -<blockquote><pre> -location /video/ { - sendfile off; - aio on; - output_buffers 1 64k; -} -</pre></blockquote></p><p> -In addition, starting from FreeBSD 5.2.1 and nginx 0.8.12, AIO can -also be used to pre-load data for <code>sendfile()</code>: -<blockquote><pre> -location /video/ { - sendfile on; - tcp_nopush on; - aio sendfile; -} -</pre></blockquote> -In this configuration, <code>sendfile()</code> is called with -the <code>SF_NODISKIO</code> flag which causes it not to -block on disk I/O and instead report back when the data are not in -memory; nginx then initiates an asynchronous data load by reading -one byte. The FreeBSD kernel then loads the first 128K bytes -of a file into memory, however next reads will only load data -in 16K chunks. This can be tuned using the -<a href="#read_ahead">read_ahead</a> -directive. -</p><p> -On Linux, AIO is usable starting from kernel version 2.6.22; -plus, it is also necessary to enable -<a href="#directio">directio</a>, -otherwise reading will be blocking: -<blockquote><pre> -location /video/ { - aio on; - directio 512; - output_buffers 1 128k; -} -</pre></blockquote></p><p> -On Linux, -<a href="#directio">directio</a> -can only be used for reading blocks that are aligned on 512-byte -boundaries (or 4K for XFS). -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. -There is no need to turn off -<a href="#sendfile">sendfile</a> -explicitly as it is turned off automatically when -<a href="#directio">directio</a> -is used. -</p><hr><a name="alias"></a><strong>syntax</strong>: - <code>alias <code><i>path</i></code></code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>location</code><br><p> -Defines a replacement for the specified location. -For example, with the following configuration -<blockquote><pre> -location /i/ { - alias /data/w3/images/; -} -</pre></blockquote> -the request of -“<code>/i/top.gif</code>” will be responded -with the file -“<code>/data/w3/images/top.gif</code>”. -</p><p> -The <code><i>path</i></code> value can contain variables. -</p><p> -If <code>alias</code> is used inside a location defined -with a regular expression then such regular expression should -contain captures and <code>alias</code> should refer to -these captures (0.7.40), for example: -<blockquote><pre> -location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { - alias /data/w3/images/$1; -} -</pre></blockquote></p><p> -When location matches the last part of the directive's value: -<blockquote><pre> -location /images/ { - alias /data/w3/images/; -} -</pre></blockquote> -it is better to use the -<a href="#root">root</a> -directive instead: -<blockquote><pre> -location /images/ { - root /data/w3; -} -</pre></blockquote></p><hr><a name="client_body_in_file_only"></a><strong>syntax</strong>: - <code>client_body_in_file_only - <code>on</code> | - <code>clean</code> | - <code>off</code></code><br><strong>default</strong>: - <code>client_body_in_file_only off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Determines whether nginx should save the entire client request body -into a file. -This directive can be used during debugging, or when using the -<code>$request_body_file</code> -variable, or the -<a href="ngx_http_perl_module.html#methods">$r->request_body_file</a> -method of the module -<a href="ngx_http_perl_module.html">ngx_http_perl_module</a>. -</p><p> -When set to the value <code>on</code>, temporary files are not -removed after request processing. -</p><p> -The value <code>clean</code> will cause the temporary files -left after request processing to be removed. -</p><hr><a name="client_body_in_single_buffer"></a><strong>syntax</strong>: - <code>client_body_in_single_buffer <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>client_body_in_single_buffer off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Determines whether nginx should save the entire client request body -in a single buffer. -The directive is recommended when using the -<code>$request_body</code> -variable, to save the number of copy operations involved. -</p><hr><a name="client_body_buffer_size"></a><strong>syntax</strong>: - <code>client_body_buffer_size <code><i>size</i></code></code><br><strong>default</strong>: - <code>client_body_buffer_size 8k/16k</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Sets buffer size for reading client request body. -In case request body is larger than the buffer, -the whole body or only its part is written to a temporary file. - -By default, buffer size is equal to two memory pages. -This is 8K on x86, other 32-bit platforms, and x86-64. -It is usually 16K on other 64-bit platforms. -</p><hr><a name="client_body_temp_path"></a><strong>syntax</strong>: - <code>client_body_temp_path - <code><i>path</i></code> - [<code><i>level1</i></code> - [<code><i>level2</i></code> - [<code><i>level3</i></code>]]] -</code><br><strong>default</strong>: - <code>client_body_temp_path client_body_temp</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Defines a directory for storing temporary files holding client request bodies. -Up to three-level subdirectory hierarchy can be used underneath the specified -directory. -For example, in the following configuration -<blockquote><pre> -client_body_temp_path /spool/nginx/client_temp 1 2; -</pre></blockquote> -a temporary file might look like this: -<blockquote><pre> -/spool/nginx/client_temp/7/45/00000123457 -</pre></blockquote></p><hr><a name="client_body_timeout"></a><strong>syntax</strong>: - <code>client_body_timeout <code><i>time</i></code></code><br><strong>default</strong>: - <code>client_body_timeout 60</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Defines a timeout for reading client request body. -A timeout is only set between two successive read operations, -not for the transmission of the whole request body. -If a client does not transmit anything within this time, -the client error -408 (Request Time-out) -is returned. -</p><hr><a name="client_header_buffer_size"></a><strong>syntax</strong>: - <code>client_header_buffer_size <code><i>size</i></code></code><br><strong>default</strong>: - <code>client_header_buffer_size 1k</code><br><strong>context</strong>: - <code>http</code>, <code>server</code><br><p> -Sets buffer size for reading client request header. -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 field do not fit entirely into -this buffer then larger buffers are allocated, configured by the -<a href="#large_client_header_buffers">large_client_header_buffers</a> -directive. -</p><hr><a name="client_header_timeout"></a><strong>syntax</strong>: - <code>client_header_timeout <code><i>time</i></code></code><br><strong>default</strong>: - <code>client_header_timeout 60</code><br><strong>context</strong>: - <code>http</code>, <code>server</code><br><p> -Defines a timeout for reading client request header. -If a client does not transmit the entire header within this time, -the client error -408 (Request Time-out) -is returned. -</p><hr><a name="client_max_body_size"></a><strong>syntax</strong>: - <code>client_max_body_size <code><i>size</i></code></code><br><strong>default</strong>: - <code>client_max_body_size 1m</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Sets the maximum allowed size of the client request body, -specified in the -<code>Content-Length</code> -request header field. -If it exceeds the configured value, the client error -413 (Request Entity Too Large) -is returned. -Please be aware that -<a href="/web/upload.html">browsers cannot correctly display -this error</a>. -</p><hr><a name="default_type"></a><strong>syntax</strong>: - <code>default_type <code><i>mime-type</i></code></code><br><strong>default</strong>: - <code>default_type text/plain</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Defines a default MIME-type of a response. -</p><hr><a name="directio"></a><strong>syntax</strong>: - <code>directio <code><i>size</i></code> | <code>off</code></code><br><strong>default</strong>: - <code>directio off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><strong>appeared in version</strong>: - 0.7.7<p> -Enables the use of -the <code>O_DIRECT</code> flag (FreeBSD, Linux), -the <code>F_NOCACHE</code> flag (Mac OS X), -or the <code>directio()</code> function (Solaris), -when reading files that are larger than the specified <code><i>size</i></code>. -It automatically disables (0.7.15) the use of -<a href="#sendfile">sendfile</a> -for a given request. -It could be useful for serving large files: -<blockquote><pre> -directio 4m; -</pre></blockquote> -or when using <a href="#aio">aio</a> on Linux. -</p><hr><a name="directio_alignment"></a><strong>syntax</strong>: - <code>directio_alignment <code><i>size</i></code></code><br><strong>default</strong>: - <code>directio_alignment 512</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><strong>appeared in version</strong>: - 0.8.11<p> -Sets an alignment for -<a href="#directio">directio</a>. -In most cases, a 512-byte alignment is enough, however, when -using XFS under Linux, it needs to be increased to 4K. -</p><hr><a name="error_page"></a><strong>syntax</strong>: - <code>error_page - <code><i>code</i></code> ... - [<code>=</code>[<code><i>response</i></code>]] - <code><i>uri</i></code></code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code>, <code>if in location</code><br><p> -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 -<code>error_page</code> -directives on -the current level. -A URI value can contain variables. -</p><p> -Example: -<blockquote><pre> -error_page 404 /404.html; -error_page 502 503 504 /50x.html; -error_page 403 http://example.com/forbidden.html; -</pre></blockquote></p><p> -Furthermore, it is possible to change the response code to another, for example: -<blockquote><pre> -error_page 404 =200 /empty.gif; -</pre></blockquote></p><p> -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: -<blockquote><pre> -error_page 404 = /404.php; -</pre></blockquote></p><p> -If there is no need to change URI during redirection it is possible to redirect -error processing into a named location: -<blockquote><pre> -location / { - error_page 404 = @fallback; -} - -location @fallback { - proxy_pass http://backend; -} -</pre></blockquote></p><hr><a name="if_modified_since"></a><strong>syntax</strong>: - <code>if_modified_since - <code>off</code> | - <code>exact</code> | - <code>before</code></code><br><strong>default</strong>: - <code>if_modified_since exact</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><strong>appeared in version</strong>: - 0.7.24<p> -Specifies how to compare modification time of a response -with the time in the -<code>If-Modified-Since</code> -request header: - -<dl compact><dt><code>off</code></dt><dd> -the -<code>If-Modified-Since</code> request header is ignored (0.7.34); -</dd><dt><code>exact</code></dt><dd> -exact match; -</dd><dt><code>before</code></dt><dd> -modification time of a response is -less than or equal to the time in the <code>If-Modified-Since</code> -request header. -</dd></dl></p><hr><a name="internal"></a><strong>syntax</strong>: - <code>internal</code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>location</code><br><p> -Specifies that a given location can only be used for internal requests. -For external requests, the client error -404 (Not Found) -is returned. -Internal requests are the following: - -<ul><li> -requests redirected by the <a href="#error_page">error_page</a> directive; -</li><li> -subrequests formed by the -<code>include virtual</code> -command of the module -<a href="ngx_http_ssi_module.html">ngx_http_ssi_module</a>; -</li><li> -requests changed by the -<a href="ngx_http_rewrite_module.html#rewrite">rewrite</a> -directive of the module -<a href="ngx_http_rewrite_module.html">ngx_http_rewrite_module</a>. -</li></ul></p><p> -Example: -<blockquote><pre> -error_page 404 /404.html; - -location /404.html { - internal; -} -</pre></blockquote></p><hr><a name="keepalive_requests"></a><strong>syntax</strong>: - <code>keepalive_requests <code><i>number</i></code></code><br><strong>default</strong>: - <code>keepalive_requests 100</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><strong>appeared in version</strong>: - 0.8.0<p> -Sets the maximum number of requests that can be -made through one keep-alive connection. -</p><hr><a name="keepalive_timeout"></a><strong>syntax</strong>: - <code>keepalive_timeout - <code><i>time</i></code> - [<code><i>time</i></code>] -</code><br><strong>default</strong>: - <code>keepalive_timeout 75</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -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 -“<code>Keep-Alive: timeout=<code><i>time</i></code></code>” -response header. -Two arguments may differ. -</p><p> -The -“<code>Keep-Alive: timeout=</code>” -is understood by Mozilla and Konqueror. -MSIE will close keep-alive connection in about 60 seconds. -</p><hr><a name="large_client_header_buffers"></a><strong>syntax</strong>: - <code>large_client_header_buffers <code><i>number size</i></code></code><br><strong>default</strong>: - <code>large_client_header_buffers 4 4k/8k</code><br><strong>context</strong>: - <code>http</code>, <code>server</code><br><p> -Sets the maximum <code><i>number</i></code> and <code><i>size</i></code> of -buffers used when reading large client request headers. -A request line cannot exceed the size of one buffer, or the client error -414 (Request-URI Too Large) -is returned. -A request header field cannot exceed the size of one buffer as well, or the -client error -400 (Bad Request) -is returned. -Buffers are allocated only on demand. -By default, the buffer size is equal to one memory page size. -It is either 4K or 8K, platform dependent. -If after the end of request processing a connection is transitioned -into the keep-alive state, these buffers are freed. -</p><hr><a name="limit_except"></a><strong>syntax</strong>: - <code>limit_except <code><i>method</i></code> ... { ... }</code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>location</code><br><p> -Limits allowed HTTP methods inside a location. -The GET method also implies the HEAD method. -Access to other methods can be limited using the -<a href="ngx_http_access_module.html">ngx_http_access_module</a> -and -<a href="ngx_http_auth_basic_module.html">ngx_http_auth_basic_module</a> -modules directives: -<blockquote><pre> -limit_except GET { - allow 192.168.1.0/32; - deny all; -} -</pre></blockquote> -Please note that this will limit access to all methods -<strong>except</strong> GET and HEAD. -</p><hr><a name="limit_rate"></a><strong>syntax</strong>: - <code>limit_rate <code><i>rate</i></code></code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code>, <code>if in location</code><br><p> -Rate limits the transmission of a response to a client. -The <code><i>rate</i></code> is specified in bytes per second. - -The limit is per connection, so if a single client opens 2 connections, -an overall rate will be 2x more than specified. -</p><p> -This directive is not applicable if one wants to rate limit -a group of clients on the -<a href="#server">server</a> -level. -If that is the case, the desired limit can be specified in the -<code>$limit_rate</code> -variable: -<blockquote><pre> -server { - - if ($slow) { - set $limit_rate 4k; - } - - ... -} -</pre></blockquote></p><hr><a name="limit_rate_after"></a><strong>syntax</strong>: - <code>limit_rate_after <code><i>size</i></code></code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code>, <code>if in location</code><br><strong>appeared in version</strong>: - 0.8.0<p> -Sets the initial amount after which the further transmission -of a response to a client will be rate limited. -</p><p> -Example: -<blockquote><pre> -location /flv/ { - flv; - limit_rate_after 500k; - limit_rate 50k; -} -</pre></blockquote></p><hr><a name="listen"></a><strong>syntax</strong>: - <code>listen - <code><i>address</i></code>[:<code><i>port</i></code>] - [<code>default</code> | <code>default_server</code> - [<code>backlog</code>=<code><i>number</i></code>] - [<code>rcvbuf</code>=<code><i>size</i></code>] - [<code>sndbuf</code>=<code><i>size</i></code>] - [<code>accept_filter</code>=<code><i>filter</i></code>] - [<code>deferred</code>] - [<code>bind</code>] - [<code>ipv6only</code>=<code>on</code>|<code>off</code>] - [<code>ssl</code>]] -</code><br><code> </code><code>listen - <code><i>port</i></code> - [<code>default</code> | <code>default_server</code> - [<code>backlog</code>=<code><i>number</i></code>] - [<code>rcvbuf</code>=<code><i>size</i></code>] - [<code>sndbuf</code>=<code><i>size</i></code>] - [<code>accept_filter</code>=<code><i>filter</i></code>] - [<code>deferred</code>] - [<code>bind</code>] - [<code>ipv6only</code>=<code>on</code>|<code>off</code>] - [<code>ssl</code>]] -</code><br><strong>default</strong>: - <code>listen *:80 | *:8000</code><br><strong>context</strong>: - <code>server</code><br><p> -Sets an <code><i>address</i></code> and a <code><i>port</i></code>, on which -the server will accept requests. -Only one of <code><i>address</i></code> or <code><i>port</i></code> can be -specified. -An <code><i>address</i></code> may also be a hostname, for example: -<blockquote><pre> -listen 127.0.0.1:8000; -listen 127.0.0.1; -listen 8000; -listen *:8000; -listen localhost:8000; -</pre></blockquote> -IPv6 addresses (0.7.36) are specified in square brackets: -<blockquote><pre> -listen [::]:8000; -listen [fe80::1]; -</pre></blockquote></p><p> -If only <code><i>address</i></code> is given, the port 80 is used. -</p><p> -If directive is not present then either the <code>*:80</code> is used -if nginx runs with superuser privileges, or <code>*:8000</code> otherwise. -</p><p> -The <code>default</code> parameter, if present, -will cause the server to become the default server for the specified -<code><i>address</i></code>:<code><i>port</i></code> pair. -If none of the directives have the <code>default</code> -parameter then the first server with the -<code><i>address</i></code>:<code><i>port</i></code> pair will be -the default server for this pair. -Starting from version 0.8.21 it is possible to use the -<code>default_server</code> -parameter. -</p><p> -A <code>listen</code> directive which has the <code>default</code> -parameter can have several additional parameters specific to system calls -<code>listen()</code> and <code>bind()</code>. -Starting from version 0.8.21, these parameters can be specified in any -<code>listen</code> directive, but only once for the given -<code><i>address</i></code>:<code><i>port</i></code> pair. -<dl compact><dt><code>backlog</code>=<code><i>number</i></code></dt><dd> -sets the <code>backlog</code> parameter in the -<code>listen()</code> call. -By default, <code>backlog</code> equals -1 on FreeBSD -and 511 on other platforms. -</dd><dt><code>rcvbuf</code>=<code><i>size</i></code></dt><dd> -sets the <code>SO_RCVBUF</code> parameter for the listening socket. -</dd><dt><code>sndbuf</code>=<code><i>size</i></code></dt><dd> -sets the <code>SO_SNDBUF</code> parameter for the listening socket. -</dd><dt><code>accept_filter</code>=<code><i>filter</i></code></dt><dd> -sets the name of the accept filter. -This works only on FreeBSD, acceptable values are <code>dataready</code> -and <code>httpready</code>. -On receipt of the <code>SIGHUP</code> signal, an accept filter can only be -changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE -and 4.11-STABLE. -</dd><dt><code>deferred</code></dt><dd> -instructs to use a deferred <code>accept()</code> on Linux -using the <code>TCP_DEFER_ACCEPT</code> option. -</dd><dt><code>bind</code></dt><dd> -specifies to make a separate <code>bind()</code> call for a given -<code><i>address</i></code>:<code><i>port</i></code> pair. -This is because nginx will only <code>bind()</code> to -<code>*</code>:<code><i>port</i></code> -if there are several <code>listen</code> directives with -the same port but different addresses, and one of the -<code>listen</code> directives listens on all addresses -for the given port (<code>*</code>:<code><i>port</i></code>). -It should be noted that in this case a <code>getsockname()</code> -system call will be made to determine an address that accepted a -connection. -If parameters <code>backlog</code>, <code>rcvbuf</code>, -<code>sndbuf</code>, <code>accept_filter</code>, or -<code>deferred</code> are used then for a given -<code><i>address</i></code>:<code><i>port</i></code> pair -a separate <code>bind()</code> call will always be made. -</dd><dt><code>ipv6only</code>=<code>on</code>|<code>off</code></dt><dd> -this parameter (0.7.42) sets the value of the <code>IPV6_V6ONLY</code> -parameter for the listening socket. -This parameter can only be set once on start. -</dd><dt><code>ssl</code></dt><dd> -this parameter (0.7.14) does not relate to system calls -<code>listen()</code> and <code>bind()</code>, but allows to -specify that all connections accepted on this port should work in -the SSL mode. -This allows for a more compact configuration for the server operating -in both HTTP and HTTPS modes simultaneously. -<blockquote><pre> -listen 80; -listen 443 default ssl; -</pre></blockquote></dd></dl></p><p> -Example: -<blockquote><pre> -listen 127.0.0.1 default accept_filter=dataready backlog=1024; -</pre></blockquote></p><hr><a name="location"></a><strong>syntax</strong>: - <code>location [ - <code>=</code> | - <code>~</code> | - <code>~*</code> | - <code>^~</code> | - <code>@</code> - ] <code><i>uri</i></code> -{ ... }</code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>server</code><br><p> -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 -“<code>~*</code>” prefix (for case-insensitive matching), or with the -“<code>~</code>” 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. -Then regular expressions are checked, in the order of their appearance -in a configuration file. -A search terminates on the first match, and its corresponding -configuration is used. -If no match with a regular expression location is found then a -configuration of the most specific prefix location is used. -</p><p> -For case-insensitive operating systems such as Mac OS X and Cygwin, -the string matching ignores a case (0.7.7). -However, comparison is limited to one-byte locales. -</p><p> -Regular expressions can contain captures (0.7.40) that can later -be used in other directives. -</p><p> -If the most specific prefix location has the “<code>^~</code>” prefix -then regular expressions are not checked. -</p><p> -Also, using the “<code>=</code>” 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 “<code>/</code>” request happens frequently, -defining “<code>location = /</code>” will speed up the processing -of these requests, as search terminates right after the first -comparison. -</p><p> -In versions from 0.7.1 to 0.8.41, if a request matched the prefix -location without the “<code>=</code>” and “<code>^~</code>” -prefixes, the search also terminated and regular expressions were -not checked. -</p><p> -Let's illustrate the above by example: -<blockquote><pre> -location = / { - [ configuration A ] -} - -location / { - [ configuration B ] -} - -location ^~ /images/ { - [ configuration C ] -} - -location ~* \.(gif|jpg|jpeg)$ { - [ configuration D ] -} -</pre></blockquote> -The “<code>/</code>” request will match configuration A, -the “<code>/documents/document.html</code>” request will match -configuration B, -the “<code>/images/1.gif</code>” request will match configuration C, and -the “<code>/documents/1.jpg</code>” request will match configuration D. -</p><p> -The “<code>@</code>” prefix defines a named location. -Such a location is not used for a regular request processing, but instead -used for request redirection. -</p><hr><a name="log_not_found"></a><strong>syntax</strong>: - <code>log_not_found <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>log_not_found on</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables logging of errors about not found files into the -<a href="../ngx_core_module.html#error_log">error_log</a>. -</p><hr><a name="log_subrequest"></a><strong>syntax</strong>: - <code>log_subrequest <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>log_subrequest off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables logging of subrequests into the -<a href="ngx_http_log_module.html#access_log">access_log</a>. -</p><hr><a name="merge_slashes"></a><strong>syntax</strong>: - <code>merge_slashes <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>merge_slashes on</code><br><strong>context</strong>: - <code>http</code>, <code>server</code><br><p> -Enables or disables compression of two or more adjacent slashes -in a URI into a single slash. -</p><p> -Note that compression is essential for the correct prefix string -and regular expressions location matching. -Without it, the “<code>//scripts/one.php</code>” request would not match -<blockquote><pre> -location /scripts/ { - ... -} -</pre></blockquote> -and might be processed as a static file, -so it gets converted to “<code>/scripts/one.php</code>”. -</p><p> -Turning the compression <code>off</code> can become necessary if a URI -contains base64-encoded names, since base64 uses the "/" character internally. -However, for security considerations, it is better to avoid turning off -the compression. -</p><p> -If a directive is specified on the -<a href="#server">server</a> -level, which is also a default server, its value will cover -all virtual servers listening on the same address and port. -</p><hr><a name="msie_padding"></a><strong>syntax</strong>: - <code>msie_padding <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>msie_padding on</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables adding of comments to responses with status -greater than 400 for MSIE clients, to pad the response size to 512 bytes. -</p><hr><a name="msie_refresh"></a><strong>syntax</strong>: - <code>msie_refresh <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>msie_refresh off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables issuing refreshes instead of redirects, for MSIE clients. -</p><hr><a name="open_file_cache"></a><strong>syntax</strong>: - <code>open_file_cache -<code>max</code>=<code><i>N</i></code> -[<code>inactive</code>=<code><i>time</i></code>] | -<code>off</code></code><br><strong>default</strong>: - <code>open_file_cache off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Configures a cache that can store: -<ul><li> -open file descriptors, their sizes and modification times; -</li><li> -directory lookups; -</li><li> -file lookup errors, such as "file not found", "no read permission", -and so on. -Caching of errors should be enabled separately by the -<a href="#open_file_cache_errors">open_file_cache_errors</a> -directive. -</li></ul></p><p> -The directive has the following parameters: -<dl compact><dt><code>max</code></dt><dd> -sets the maximum number of elements in the cache; -on cache overflow the least recently used (LRU) elements get removed; -</dd><dt><code>inactive</code></dt><dd> -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; -</dd><dt><code>off</code></dt><dd> -disables the cache. -</dd></dl></p><p> -Example: -<blockquote><pre> -open_file_cache max=1000 inactive=20s; -open_file_cache_valid 30s; -open_file_cache_min_uses 2; -open_file_cache_errors on; -</pre></blockquote></p><hr><a name="open_file_cache_errors"></a><strong>syntax</strong>: - <code>open_file_cache_errors <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>open_file_cache_errors off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables caching of file lookup errors by the -<a href="#open_file_cache">open_file_cache</a>. -</p><hr><a name="open_file_cache_min_uses"></a><strong>syntax</strong>: - <code>open_file_cache_min_uses <code><i>number</i></code></code><br><strong>default</strong>: - <code>open_file_cache_min_uses 1</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Sets the minimum <code><i>number</i></code> of file accesses during -the period configured by the <code>inactive</code> parameter -of the <a href="#open_file_cache">open_file_cache</a> directive, -after which a file descriptor will remain open in the cache. -</p><hr><a name="open_file_cache_valid"></a><strong>syntax</strong>: - <code>open_file_cache_valid <code><i>time</i></code></code><br><strong>default</strong>: - <code>open_file_cache_valid 60</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Sets a time after which -<a href="#open_file_cache">open_file_cache</a> -elements should be validated. -</p><hr><a name="optimize_server_names"></a><strong>syntax</strong>: - <code>optimize_server_names <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>optimize_server_names on</code><br><strong>context</strong>: - <code>http</code>, <code>server</code><br><p> -This directive is obsolete. -</p><p> -Enables or disables optimization of hostname checking in name-based -virtual servers. -In particular, the checking affects hostnames used in redirects. -If optimization is enabled, and all name-based servers listening on -the same address:port pair have identical configuration, then -names are not checked during request processing, and the first -server name is used in redirects. -In case redirects should use hostnames sent by clients, -optimization needs to be disabled. -</p><hr><a name="port_in_redirect"></a><strong>syntax</strong>: - <code>port_in_redirect <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>port_in_redirect on</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables specifying the port in redirects issued by nginx. -</p><hr><a name="read_ahead"></a><strong>syntax</strong>: - <code>read_ahead <code><i>size</i></code></code><br><strong>default</strong>: - <code>read_ahead 0</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Sets the amount of pre-reading when working with files, in the kernel. -</p><p> -On Linux, the -<code>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</code> -system call is used, so the <code><i>size</i></code> argument is ignored. -</p><p> -On FreeBSD, the -<code>fcntl(O_READAHEAD,</code><code><i>size</i></code><code>)</code> -system call is used, supported in FreeBSD 9.0-CURRENT. -FreeBSD 7 needs to be -<a href="http://sysoev.ru/freebsd/patch.readahead.txt">patched</a>. -</p><hr><a name="recursive_error_pages"></a><strong>syntax</strong>: - <code>recursive_error_pages <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>recursive_error_pages off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables doing several redirects using the -<a href="#error_page">error_page</a> -directive. -</p><hr><a name="reset_timedout_connection"></a><strong>syntax</strong>: - <code>reset_timedout_connection - <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>reset_timedout_connection off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables resetting of timed out connections. -The reset is performed as follows: before closing a socket, the -<code>SO_LINGER</code> -option is set on it with a timeout value of 0. -When the socket is closed, a client is sent TCP RST, and all memory -occupied by this socket is freed. -This avoids keeping of an already closed socket with filled buffers -for a long time, in a FIN_WAIT1 state. -</p><p> -It should be noted that timed out keep-alive connections are still -closed normally. -</p><hr><a name="resolver"></a><strong>syntax</strong>: - <code>resolver <code><i>address</i></code></code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Sets the <code><i>address</i></code> of a name server, for example: -<blockquote><pre> -resolver 127.0.0.1; -</pre></blockquote></p><hr><a name="resolver_timeout"></a><strong>syntax</strong>: - <code>resolver_timeout <code><i>time</i></code></code><br><strong>default</strong>: - <code>resolver_timeout 30s</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Sets a timeout for name resolution, for example: -<blockquote><pre> -resolver_timeout 5s; -</pre></blockquote></p><hr><a name="root"></a><strong>syntax</strong>: - <code>root <code><i>path</i></code></code><br><strong>default</strong>: - <code>root html</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code>, <code>if in location</code><br><p> -Sets the root directory for requests. -For example, with the following configuration -<blockquote><pre> -location /i/ { - root /data/w3; -} -</pre></blockquote>“<code>/i/top.gif</code>” will be responded -with the file -“<code>/data/w3/i/top.gif</code>”. -</p><p> -The <code><i>path</i></code> value can contain variables. -</p><p> -A path to the file is constructed by merely adding a URI to the value -of the <code>root</code> directive. -If a URI need to be modified, the -<a href="#alias">alias</a> directive should be used. -</p><hr><a name="satisfy"></a><strong>syntax</strong>: - <code>satisfy <code>all</code> | <code>any</code></code><br><strong>default</strong>: - <code>satisfy all</code><br><strong>context</strong>: - <code>location</code><br><p> -Allows access if any of the -<a href="ngx_http_access_module.html">ngx_http_access_module</a> -or <a href="ngx_http_auth_basic_module.html">ngx_http_auth_basic_module</a> -modules grant access. -<blockquote><pre> -location / { - satisfy any; - - allow 192.168.1.0/32; - deny all; - - auth_basic "closed site"; - auth_basic_user_file conf/htpasswd; -} -</pre></blockquote></p><hr><a name="satisfy_any"></a><strong>syntax</strong>: - <code>satisfy_any <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>satisfy_any off</code><br><strong>context</strong>: - <code>location</code><br><p> -This directive was renamed to the <a href="#satisfy">satisfy</a> directive. -</p><hr><a name="send_timeout"></a><strong>syntax</strong>: - <code>send_timeout <code><i>time</i></code></code><br><strong>default</strong>: - <code>send_timeout 60</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Sets a timeout for transmitting a response to the client. -A timeout is only set between two successive write operations, -not for the transmission of the whole response. -If a client does not receive anything within this time, -a connection is closed. -</p><hr><a name="sendfile"></a><strong>syntax</strong>: - <code>sendfile <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>sendfile off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables the use of -<code>sendfile()</code>. -</p><hr><a name="server"></a><strong>syntax</strong>: - <code>server { ... }</code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>http</code><br><p> -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 <code>Host</code> request header field) -virtual servers. -Instead, the <a href="#listen">listen</a> directives describe all -addresses and ports that should accept connections for a server, and the -<a href="#server_name">server_name</a> directive lists all server names. -An example configuration is provided in the -<a href="../virtual_hosts.html"> -Setting Up Virtual Servers</a> document. -</p><hr><a name="server_name"></a><strong>syntax</strong>: - <code>server_name <code><i>name</i></code> ...</code><br><strong>default</strong>: - <code>server_name hostname</code><br><strong>context</strong>: - <code>server</code><br><p> -Sets names of the virtual server, for example: -<blockquote><pre> -server { - server_name example.com www.example.com; -} -</pre></blockquote></p><p> -The first name becomes a primary server name. -By default, the machine's hostname is used. -Server names can include an asterisk (“<code>*</code>”) -to replace the first or last part of a name: -<blockquote><pre> -server { - server_name example.com *.example.com www.example.*; -} -</pre></blockquote></p><p> -The first two of the above mentioned names can be combined: -<blockquote><pre> -server { - server_name .example.com; -} -</pre></blockquote></p><p> -It is also possible to use regular expressions in server names, -prepending the name with a tilde (“<code>~</code>”): -<blockquote><pre> -server { - server_name www.example.com ~^www\d+\.example\.com$; -} -</pre></blockquote></p><p> -Regular expressions can contain captures (0.7.40) that can later -be used in other directives: -<blockquote><pre> -server { - server_name ~^(www\.)?(.+)$; - - location / { - root /sites/$2; - } -} - -server { - server_name _; - - location / { - root /sites/default; - } -} -</pre></blockquote></p><p> -Starting from version 0.8.25, named captures in regular expressions create -variables that can later be used in other directives: -<blockquote><pre> -server { - server_name ~^(www\.)?(?<domain>.+)$; - - location / { - root /sites/$domain; - } -} - -server { - server_name _; - - location / { - root /sites/default; - } -} -</pre></blockquote></p><p> -Starting from version 0.7.11, it is possible to specify an empty name: -<blockquote><pre> -server { - server_name www.example.com ""; -} -</pre></blockquote> -It allows this server to process requests without the <code>Host</code> -header, instead of the default server for the given address:port pair. -</p><p> -The name checking order is as follows: -<ol><li> -full names -</li><li> -names with the prefix mask, e.g. “<code>*.example.com</code>”</li><li> -names with the suffix mask, e.g. “<code>mail.*</code>”</li><li> -regular expressions -</li></ol></p><hr><a name="server_name_in_redirect"></a><strong>syntax</strong>: - <code>server_name_in_redirect <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>server_name_in_redirect on</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables the use of the primary server name, specified by the -<a href="#server_name">server_name</a> -directive, in redirects issued by nginx. -When disabled, the name from the <code>Host</code> request header field -is used. -If this field is not present, an IP address of the server is used. -</p><hr><a name="server_names_hash_max_size"></a><strong>syntax</strong>: - <code>server_names_hash_max_size <code><i>size</i></code></code><br><strong>default</strong>: - <code>server_names_hash_max_size 512</code><br><strong>context</strong>: - <code>http</code><br><p> -Sets the maximum <code><i>size</i></code> of the server names hash tables. -For more information, please refer to -<a href="../hash.html">Setting Up Hashes</a>. -</p><hr><a name="server_names_hash_bucket_size"></a><strong>syntax</strong>: - <code>server_names_hash_bucket_size <code><i>size</i></code></code><br><strong>default</strong>: - <code>server_names_hash_bucket_size 32/64/128</code><br><strong>context</strong>: - <code>http</code><br><p> -Sets the bucket size for the server names hash tables. -Default value depends on the size of the processor's cache line. -For more information, please refer to -<a href="../hash.html">Setting Up Hashes</a>. -</p><hr><a name="server_tokens"></a><strong>syntax</strong>: - <code>server_tokens <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>server_tokens on</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables emitting of nginx version in error messages and in the -<code>Server</code> response header field. -</p><hr><a name="tcp_nodelay"></a><strong>syntax</strong>: - <code>tcp_nodelay <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>tcp_nodelay on</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables the use of the <code>TCP_NODELAY</code> option. -The option is enabled only when a connection is transitioned into the -keep-alive state. -</p><hr><a name="tcp_nopush"></a><strong>syntax</strong>: - <code>tcp_nopush <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>tcp_nopush off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Enables or disables the use of -the <code>TCP_NOPUSH</code> socket option on FreeBSD -or the <code>TCP_CORK</code> socket option on Linux. -Opitons are enables only when <a href="#sendfile">sendfile</a> is used. -Enabling the option allows to -<ul><li> -send the response header and the beginning of a file in one packet, -on Linux and FreeBSD 4.*; -</li><li> -send a file in full packets. -</li></ul></p><hr><a name="try_files"></a><strong>syntax</strong>: - <code>try_files - <code><i>file</i></code> ... - <code><i>uri</i></code></code><br><code> </code><code>try_files - <code><i>file</i></code> ... - =<code><i>code</i></code></code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>location</code><br><p> -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. “<code>$uri/</code>”. -If none of the files were found, an internal redirect to the -<code><i>uri</i></code> specified by the last argument is made. -As of version 0.7.51, the last argument can also be a -<code><i>code</i></code>: -<blockquote><pre> -location / { - try_files $uri $uri/index.html $uri.html =404; -} -</pre></blockquote></p><p> -Example when proxying Mongrel: -<blockquote><pre> -location / { - try_files /system/maintenance.html - $uri $uri/index.html $uri.html - @mongrel; -} - -location @mongrel { - proxy_pass http://mongrel; -} -</pre></blockquote></p><p> -Example for Drupal/FastCGI: -<blockquote><pre> -location / { - try_files $uri $uri/ @drupal; -} - -location ~ \.php$ { - try_files $uri @drupal; - - fastcgi_pass ...; - - 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_param SCRIPT_FILENAME /path/to/index.php; - fastcgi_param SCRIPT_NAME /index.php; - fastcgi_param QUERY_STRING q=$uri&$args; - - ... other fastcgi_param's -} -</pre></blockquote> -In the following example, -<blockquote><pre> -location / { - try_files $uri $uri/ @drupal; -} -</pre></blockquote> -the <code>try_files</code> directive is equivalent to -<blockquote><pre> -location / { - error_page 404 = @drupal; - log_not_found off; -} -</pre></blockquote> -And here, -<blockquote><pre> -location ~ \.php$ { - try_files $uri @drupal; - - fastcgi_pass ...; - - fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; - - ... -} -</pre></blockquote><code>try_files</code> checks the existence of the PHP file -before passing the request to the FastCGI server. -</p><p> -Example for Wordpress and Joomla: -<blockquote><pre> -location / { - try_files $uri $uri/ @wordpress; -} - -location ~ \.php$ { - try_files $uri @wordpress; - - fastcgi_pass ...; - - fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; - ... other fastcgi_param's -} - -location @wordpress { - fastcgi_pass ...; - - fastcgi_param SCRIPT_FILENAME /path/to/index.php; - ... other fastcgi_param's -} -</pre></blockquote></p><hr><a name="types"></a><strong>syntax</strong>: - <code>types { ... }</code><br><strong>default</strong>: - <code>see below</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Maps file name extensions to MIME types of responses. -Several extensions can map to one type. -The following mappings are configured by default: -<blockquote><pre> -types { - text/html html; - image/gif gif; - image/jpeg jpg; -} -</pre></blockquote></p><p> -A sufficiently full mapping table is distributed with nginx in the -<code>conf/mime.types</code> file. -</p><p> -To make a particular location emit the -“<code>application/octet-stream</code>” -MIME type for all requests, try the following: -<blockquote><pre> -location /download/ { - types { } - default_type application/octet-stream; -} -</pre></blockquote></p><hr><a name="underscores_in_headers"></a><strong>syntax</strong>: - <code>underscores_in_headers <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>underscores_in_headers off</code><br><strong>context</strong>: - <code>http</code>, <code>server</code><br><p> -Enables or disables the use of underscores in client request header fields. -</p><a name="variables"></a><center><h4>Embedded Variables</h4></center><p> -The module <code>ngx_http_core_module</code> supports embedded variables with -names matching those of the Apache Server. -First of all, these are variables representing client request header -fields, such as, <code>$http_user_agent</code>, <code>$http_cookie</code>, -and so on. -It also supports other variables: -<dl compact><dt><code>$args</code></dt><dd> -arguments in the request line -</dd><dt><code>$arg_</code><code><i>name</i></code></dt><dd> -argument <code><i>name</i></code> in the request line -</dd><dt><code>$binary_remote_addr</code></dt><dd> -client address in a binary form, value's length is always 4 bytes -</dd><dt><code>$content_length</code></dt><dd><code>Content-Length</code> request header field -</dd><dt><code>$content_type</code></dt><dd><code>Content-Type</code> request header field -</dd><dt><code>$cookie_</code><code><i>name</i></code></dt><dd> -the <code><i>name</i></code> cookie -</dd><dt><code>$document_root</code></dt><dd><a href="#root">root</a> directive's value for the current request -</dd><dt><code>$document_uri</code></dt><dd> -same as <code>$uri</code></dd><dt><code>$host</code></dt><dd><code>Host</code> request header field, -or the server name matching a request if this field is not present -</dd><dt><code>$hostname</code></dt><dd> -host name -</dd><dt><code>$http_</code><code><i>name</i></code></dt><dd> -the <code><i>name</i></code> request header field -</dd><dt><code>$is_args</code></dt><dd>“<code>?</code>” if a request line has arguments, -or an empty string otherwise -</dd><dt><code>$limit_rate</code></dt><dd> -allows for connection rate limiting -</dd><dt><code>$pid</code></dt><dd> -PID of the worker process -</dd><dt><code>$request_method</code></dt><dd> -request method, usually -“<code>GET</code>” or “<code>POST</code>”</dd><dt><code>$remote_addr</code></dt><dd> -client address -</dd><dt><code>$remote_port</code></dt><dd> -client port -</dd><dt><code>$remote_user</code></dt><dd> -user name supplied with the Basic authentication -</dd><dt><code>$realpath_root</code></dt><dd><a href="#root">root</a> directive's value -for the current request, with all symbolic links resolved to real paths -</dd><dt><code>$request_filename</code></dt><dd> -file path for the current query, based on the -<a href="#root">root</a> and <a href="#alias">alias</a> -directives, and the request URI -</dd><dt><code>$request_body</code></dt><dd> -request body -<p> -The variable's value is made available in locations -processed by the -<a href="ngx_http_proxy_module.html#proxy_pass">proxy_pass</a> -and -<a href="ngx_http_fastcgi_module.html#fastcgi_pass">fastcgi_pass</a> -directives. -</p></dd><dt><code>$request_body_file</code></dt><dd> -name of a temporary file with the request body -<p> -At the end of processing, the file needs to be removed. -To always write a request body to a file, -<a href="#client_body_in_file_only">client_body_in_file_only on</a> -needs be specified. -When passing the name of a temporary file in a proxied request, -or in a request to a FastCGI server, -passing of the request body should be disabled by the -<a href="ngx_http_proxy_module.html#proxy_pass_request_body">proxy_pass_request_body</a> -and -<a href="ngx_http_fastcgi_module.html#fastcgi_pass_request_body">fastcgi_pass_request_body</a> -directives, respectively. -</p></dd><dt><code>$request_uri</code></dt><dd> -full original request URI (with arguments) -</dd><dt><code>$query_string</code></dt><dd> -same as <code>$args</code></dd><dt><code>$scheme</code></dt><dd> -request scheme, “<code>http</code>” or “<code>https</code>”</dd><dt><code>$server_protocol</code></dt><dd> -request protocol, usually -“<code>HTTP/1.0</code>” -or -“<code>HTTP/1.1</code>”</dd><dt><code>$server_addr</code></dt><dd> -an address of the server which accepted a request -<p> -Computing a value of this variable usually requires one system call. -To avoid a system call, the <code>listen</code> directives -must specify addresses and use the <code>bind</code> parameter -</p></dd><dt><code>$server_name</code></dt><dd> -name of the server which accepted a request -</dd><dt><code>$server_port</code></dt><dd> -port of the server which accepted a request -</dd><dt><code>$uri</code></dt><dd> -current URI in request -<p> -It may differ from an original, e.g. when doing internal redirects, -or when using index files. -</p></dd></dl></p></body></html>
deleted file mode 100644 --- a/docs/html/http/ngx_http_mp4_module.html +++ /dev/null @@ -1,90 +0,0 @@ -<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>HTTP MP4 Module</title></head><body><center><h3>HTTP MP4 Module</h3></center><center><h4>Summary</h4></center><p> -The module <code>ngx_http_mp4_module</code> provides pseudo-streaming -server-side support for H.264/AAC files typically having filename extensions -<code>.mp4</code>, <code>.m4v</code>, -and <code>.m4a</code>. -</p><p> -Pseudo-streaming works in alliance with conformant Flash players. -A player sends an HTTP request to the server with a start time -argument in the request URI’s query string (named simply -<code>start</code> -and specified in seconds), and the server responds with a stream -so that its start position corresponds to the requested time, -for example: -<blockquote><pre> -http://example.com/elephants_dream.mp4?start=238.88 -</pre></blockquote> -This allows for a random seeking at any time, or starting playback -in the middle of a timeline. -</p><p> -To support seeking, H.264-based formats store the metadata -in the so-called “moov atom.” -It is a part of the file that holds the index information for the -whole file. -</p><p> -To start playback, a player first needs to read metadata. -This is done by sending a special request with the -<code>start=0</code> -argument. Many encoding software will insert the metadata at -the end of the file. This is bad for pseudo-streaming: -the metadata needs to be located at the beginning of the file, -or else the entire file will have to be downloaded before it -starts playing. If a file is well-formed (with metadata at the -beginning of a file), nginx just sends back the contents of a file. -Otherwise, it has to read the file and prepare a new stream so that -metadata comes before media data. -This involves some CPU, memory, and disk I/O overhead, -so it is a good idea to -<a href="http://flowplayer.org/plugins/streaming/pseudostreaming.html#prepare"> -prepare an original file for pseudo-streaming</a>, -rather than having nginx do this on every such request. -</p><p> -For a matching request with a non-zero -<code>start</code> -argument, nginx will read metadata from the file, prepare the -stream starting from the requested offset, and send it to a client. -This has the same overhead as described above. -</p><p> -If a matching request does not include the -<code>start</code> -argument, there is no overhead, and the file is just sent as a static resource. -Some players also support byte-range requests, and thus do not require -this module at all. -</p><p> -This module is not built by default, it should be enabled with the -<code>--with-http_mp4_module</code> -configuration parameter. - -If you were using the third-party mp4 module, be sure to disable it. -</p><p> -A similar pseudo-streaming support for FLV files is provided by the module -<a href="ngx_http_flv_module.html">ngx_http_flv_module</a>. -</p><a name="example"></a><center><h4>Example Configuration</h4></center><p><blockquote><pre> -location /video/ { - mp4; - mp4_buffer_size 1m; - mp4_max_buffer_size 5m; -} -</pre></blockquote></p><a name="directives"></a><center><h4>Directives</h4></center><hr><a name="mp4"></a><strong>syntax</strong>: - <code>mp4</code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>location</code><br><p> -Turns on module processing in a surrounding location. -</p><hr><a name="mp4_buffer_size"></a><strong>syntax</strong>: - <code>mp4_buffer_size <code><i>size</i></code></code><br><strong>default</strong>: - <code>mp4_buffer_size 512K</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -Sets the initial size of a memory buffer used to process MP4 files. -</p><hr><a name="mp4_max_buffer_size"></a><strong>syntax</strong>: - <code>mp4_max_buffer_size <code><i>size</i></code></code><br><strong>default</strong>: - <code>mp4_max_buffer_size 10M</code><br><strong>context</strong>: - <code>http</code>, <code>server</code>, <code>location</code><br><p> -During metadata processing, a larger buffer may become necessary. -Its size cannot exceed the specified <code><i>size</i></code>, -or else nginx will return the server error -500 (Internal Server Error), -and log the following: -<blockquote><pre> -"/some/movie/file.mp4" mp4 moov atom is too large: -12583268, you may want to increase mp4_max_buffer_size -</pre></blockquote></p></body></html>
deleted file mode 100644 --- a/docs/html/ngx_core_module.html +++ /dev/null @@ -1,148 +0,0 @@ -<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Core Module</title></head><body><center><h3>Core Module</h3></center><a name="example"></a><center><h4>Example Configuration</h4></center><p><blockquote><pre> -user www www; -worker_processes 2; - -error_log /var/log/nginx-error.log info; - -events { - use kqueue; - worker_connections 2048; -} - -... -</pre></blockquote></p><a name="directives"></a><center><h4>Directives</h4></center><hr><a name="daemon"></a><strong>syntax</strong>: - <code>daemon <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>daemon on</code><br><strong>context</strong>: - <code>main</code><br><p> -Determines whether nginx should become a daemon. -Mainly used during development. -</p><hr><a name="env"></a><strong>syntax</strong>: - <code>env <code><i>VAR</i></code>[=<code><i>VALUE</i></code>]</code><br><strong>default</strong>: - <code>env TZ</code><br><strong>context</strong>: - <code>main</code><br><p> -Allows to limit a set of environment variables, change their values, -or create new environment variables, for the following cases: -<ul><li> -variable inheritance during a -<a href="control.html#upgrade">live upgrade</a> -of an executable file; -</li><li> -use of variables by the module -<a href="http/ngx_http_perl_module.html">ngx_http_perl_module</a>; -</li><li> -use of variables by worker processes. -Please bear in mind that controlling system libraries in this way -is not always possible as it is not uncommon for libraries to check -variables only during initialization, well before they can be set -using this directive. -An exception from this is an above mentioned -<a href="control.html#upgrade">live upgrade</a> -of an executable file. -</li></ul></p><p> -The TZ variable is always inherited and made available to the module -<a href="http/ngx_http_perl_module.html">ngx_http_perl_module</a>, -unless configured explicitly. -</p><p> -Usage example: -<blockquote><pre> -env MALLOC_OPTIONS; -env PERL5LIB=/data/site/modules; -env OPENSSL_ALLOW_PROXY_CERTS=1; -</pre></blockquote></p><hr><a name="include"></a><strong>syntax</strong>: - <code>include <code><i>file</i></code> | <code><i>mask</i></code></code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <strong>any</strong><br><p> -Includes another <code><i>file</i></code>, or files matching the -specified <code><i>mask</i></code>, into configuration. -Included files should consist of -syntactically correct directives and blocks. -</p><p> -Usage example: -<blockquote><pre> -include mime.types; -include vhosts/*.conf; -</pre></blockquote></p><hr><a name="master_process"></a><strong>syntax</strong>: - <code>master_process <code>on</code> | <code>off</code></code><br><strong>default</strong>: - <code>master_process on</code><br><strong>context</strong>: - <code>main</code><br><p> -Determines whether worker processes are started. -This directive is intended for nginx developers. -</p><hr><a name="pid"></a><strong>syntax</strong>: - <code>pid <code><i>file</i></code></code><br><strong>default</strong>: - <code>pid nginx.pid</code><br><strong>context</strong>: - <code>main</code><br><p> -Defines a <code><i>file</i></code> which will store the process ID of the main process. -</p><hr><a name="ssl_engine"></a><strong>syntax</strong>: - <code>ssl_engine <code><i>device</i></code></code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>main</code><br><p> -Defines the name of the hardware SSL accelerator. -</p><hr><a name="user"></a><strong>syntax</strong>: - <code>user <code><i>user</i></code> [<code><i>group</i></code>]</code><br><strong>default</strong>: - <code>user nobody nobody</code><br><strong>context</strong>: - <code>main</code><br><p> -Defines <code><i>user</i></code> and <code><i>group</i></code> -credentials used by worker processes. -If <code><i>group</i></code> is omitted, a group whose name equals -that of <code><i>user</i></code> is used. -</p><hr><a name="timer_resolution"></a><strong>syntax</strong>: - <code>timer_resolution <code><i>interval</i></code></code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>main</code><br><p> -Reduces timer resolution in worker processes, thus reducing the -number of <code>gettimeofday()</code> system calls made. -By default, <code>gettimeofday()</code> is called each time -on receiving a kernel event. -With reduced resolution, <code>gettimeofday()</code> is only -called once per specified <code><i>interval</i></code>. -</p><p> -Example: -<blockquote><pre> -timer_resolution 100ms; -</pre></blockquote></p><p> -An internal implementation of interval depends on the method used: -<ul><li> -an <code>EVFILT_TIMER</code> filter if <code>kqueue</code> is used; -</li><li><code>timer_create()</code> if <code>eventport</code> is used; -</li><li><code>setitimer()</code> otherwise. -</li></ul></p><hr><a name="worker_rlimit_core"></a><strong>syntax</strong>: - <code>worker_rlimit_core <code><i>size</i></code></code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>main</code><br><p> -Changes the limit on the largest size of a core file -(<code>RLIMIT_CORE</code>) for worker processes. -Used to increase the limit without restarting the main process. -</p><hr><a name="worker_rlimit_nofile"></a><strong>syntax</strong>: - <code>worker_rlimit_nofile <code><i>number</i></code></code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>main</code><br><p> -Changes the limit on the maximum number of open files -(<code>RLIMIT_NOFILE</code>) for worker processes. -Used to increase the limit without restarting the main process. -</p><hr><a name="worker_priority"></a><strong>syntax</strong>: - <code>worker_priority <code><i>number</i></code></code><br><strong>default</strong>: - <code>worker_priority 0</code><br><strong>context</strong>: - <code>main</code><br><p> -Defines a scheduling priority for worker processes like is -done by the <code>nice</code>: a negative -<code><i>number</i></code> -means higher priority. -Allowed range normally varies from -20 to 20. -</p><p> -Example: -<blockquote><pre> -worker_priority -10; -</pre></blockquote></p><hr><a name="worker_processes"></a><strong>syntax</strong>: - <code>worker_processes <code><i>number</i></code></code><br><strong>default</strong>: - <code>worker_processes 1</code><br><strong>context</strong>: - <code>main</code><br><p> -Defines the number of worker processes. -</p><hr><a name="working_directory"></a><strong>syntax</strong>: - <code>working_directory <code><i>directory</i></code></code><br><strong>default</strong>: - <strong>none</strong><br><strong>context</strong>: - <code>main</code><br><p> -Defines a current working directory for a worker process. -It is primarily used when writing a core-file, in which case -a working process should have write permission for the -specified directory. -</p></body></html>
deleted file mode 100644 --- a/docs/xml/http/ngx_http_core_module.xml +++ /dev/null @@ -1,2194 +0,0 @@ -<?xml version="1.0"?> - -<!DOCTYPE module SYSTEM "../../dtd/module.dtd"> - -<module name="HTTP Core Module" id="http_core_module"> - -<section id="directives" name="Directives"> - -<directive name="aio" appeared-in="0.8.11"> -<syntax>aio - <value>on</value> | - <value>off</value> | - <value>sendfile</value> -</syntax> -<default>aio off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables the use of asynchronous file I/O (AIO) -on FreeBSD and Linux. -</para> - -<para> -On FreeBSD, AIO is usable starting from FreeBSD 4.3. -AIO can either be linked statically into a kernel: -<example> -options VFS_AIO -</example> -or loaded dynamically as a kernel loadable module: -<example> -kldload aio -</example> -</para> - -<para> -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 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. -In this case, the following message will appear in -<pathname>/var/log/messages</pathname> -<example> -WARNING: Network stack Giant-free, but aio requires Giant. -Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0 -</example> -and can safely be ignored. -<note> -The requirement to use the Giant lock with AIO is related to the -fact that FreeBSD supports asynchronous calls -<c-func>aio_read</c-func> -and -<c-func>aio_write</c-func> -when working with sockets. -However, since nginx only uses AIO for disk I/O, no problems should arise. -</note> -</para> - -<para> -For AIO to work, -<link id="sendfile">sendfile</link> -needs to be disabled: -<example> -location /video/ { - sendfile off; - aio on; - output_buffers 1 64k; -} -</example> -</para> - -<para> -In addition, starting from FreeBSD 5.2.1 and nginx 0.8.12, AIO can -also be used to pre-load data for <c-func>sendfile</c-func>: -<example> -location /video/ { - sendfile on; - tcp_nopush on; - aio sendfile; -} -</example> -In this configuration, <c-func>sendfile</c-func> is called with -the <c-def>SF_NODISKIO</c-def> flag which causes it not to -block on disk I/O and instead report back when the data are not in -memory; nginx then initiates an asynchronous data load by reading -one byte. The FreeBSD kernel then loads the first 128K bytes -of a file into memory, however next reads will only load data -in 16K chunks. This can be tuned using the -<link id="read_ahead">read_ahead</link> -directive. -</para> - -<para> -On Linux, AIO is usable starting from kernel version 2.6.22; -plus, it is also necessary to enable -<link id="directio">directio</link>, -otherwise reading will be blocking: -<example> -location /video/ { - aio on; - directio 512; - output_buffers 1 128k; -} -</example> -</para> - -<para> -On Linux, -<link id="directio">directio</link> -can only be used for reading blocks that are aligned on 512-byte -boundaries (or 4K for XFS). -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. -There is no need to turn off -<link id="sendfile">sendfile</link> -explicitly as it is turned off automatically when -<link id="directio">directio</link> -is used. -</para> - -</directive> - - -<directive name="alias"> -<syntax>alias <argument>path</argument></syntax> -<default/> -<context>location</context> - -<para> -Defines a replacement for the specified location. -For example, with the following configuration -<example> -location /i/ { - alias /data/w3/images/; -} -</example> -the request of -<dq><code>/i/top.gif</code></dq> will be responded -with the file -<dq><pathname>/data/w3/images/top.gif</pathname></dq>. -</para> - -<para> -The <argument>path</argument> value can contain variables. -</para> - -<para> -If <code>alias</code> is used inside a location defined -with a regular expression then such regular expression should -contain captures and <code>alias</code> should refer to -these captures (0.7.40), for example: -<example> -location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { - alias /data/w3/images/$1; -} -</example> -</para> - -<para> -When location matches the last part of the directive's value: -<example> -location /images/ { - alias /data/w3/images/; -} -</example> -it is better to use the -<link id="root">root</link> -directive instead: -<example> -location /images/ { - root /data/w3; -} -</example> -</para> - -</directive> - - -<directive name="client_body_in_file_only"> -<syntax>client_body_in_file_only - <value>on</value> | - <value>clean</value> | - <value>off</value> -</syntax> -<default>client_body_in_file_only off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Determines whether nginx should save the entire client request body -into a file. -This directive can be used during debugging, or when using the -<var>$request_body_file</var> -variable, or the -<link doc="ngx_http_perl_module.xml" id="methods">$r->request_body_file</link> -method of the module -<link doc="ngx_http_perl_module.xml">ngx_http_perl_module</link>. -</para> - -<para> -When set to the value <value>on</value>, temporary files are not -removed after request processing. -</para> - -<para> -The value <value>clean</value> will cause the temporary files -left after request processing to be removed. -</para> - -</directive> - - -<directive name="client_body_in_single_buffer"> -<syntax>client_body_in_single_buffer <value>on</value> | <value>off</value> -</syntax> -<default>client_body_in_single_buffer off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Determines whether nginx should save the entire client request body -in a single buffer. -The directive is recommended when using the -<var>$request_body</var> -variable, to save the number of copy operations involved. -</para> - -</directive> - - -<directive name="client_body_buffer_size"> - -<syntax>client_body_buffer_size <argument>size</argument></syntax> -<default>client_body_buffer_size 8k/16k</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets buffer size for reading client request body. -In case request body is larger than the buffer, -the whole body or only its part is written to a temporary file. -<!-- ссылку на соотв. директивы про временные файлы? --> -By default, buffer size is equal to two memory pages. -This is 8K on x86, other 32-bit platforms, and x86-64. -It is usually 16K on other 64-bit platforms. -</para> - -</directive> - - -<directive name="client_body_temp_path"> -<syntax>client_body_temp_path - <argument>path</argument> - [<argument>level1</argument> - [<argument>level2</argument> - [<argument>level3</argument>]]] -</syntax> -<default>client_body_temp_path client_body_temp</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Defines a directory for storing temporary files holding client request bodies. -Up to three-level subdirectory hierarchy can be used underneath the specified -directory. -For example, in the following configuration -<example> -client_body_temp_path /spool/nginx/client_temp 1 2; -</example> -a temporary file might look like this: -<example> -/spool/nginx/client_temp/7/45/00000123457 -</example> -</para> - -</directive> - - -<directive name="client_body_timeout"> -<syntax>client_body_timeout <argument>time</argument></syntax> -<default>client_body_timeout 60</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Defines a timeout for reading client request body. -A timeout is only set between two successive read operations, -not for the transmission of the whole request body. -If a client does not transmit anything within this time, -the client error -<http-status code="408" text="Request Time-out"/> -is returned. -</para> - -</directive> - - -<directive name="client_header_buffer_size"> -<syntax>client_header_buffer_size <argument>size</argument></syntax> -<default>client_header_buffer_size 1k</default> -<context>http</context> -<context>server</context> - -<para> -Sets buffer size for reading client request header. -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 field do not fit entirely into -this buffer then larger buffers are allocated, configured by the -<link id="large_client_header_buffers">large_client_header_buffers</link> -directive. -</para> - -</directive> - - -<directive name="client_header_timeout"> -<syntax>client_header_timeout <argument>time</argument></syntax> -<default>client_header_timeout 60</default> -<context>http</context> -<context>server</context> - -<para> -Defines a timeout for reading client request header. -If a client does not transmit the entire header within this time, -the client error -<http-status code="408" text="Request Time-out"/> -is returned. -</para> - -</directive> - - -<directive name="client_max_body_size"> -<syntax>client_max_body_size <argument>size</argument></syntax> -<default>client_max_body_size 1m</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets the maximum allowed size of the client request body, -specified in the -<header>Content-Length</header> -request header field. -If it exceeds the configured value, the client error -<http-status code="413" text="Request Entity Too Large"/> -is returned. -Please be aware that -<link doc="/web/upload.xml">browsers cannot correctly display -this error</link>. -</para> - -</directive> - - -<directive name="default_type"> -<syntax>default_type <argument>mime-type</argument></syntax> -<default>default_type text/plain</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Defines a default MIME-type of a response. -</para> - -</directive> - - -<directive name="directio" appeared-in="0.7.7"> -<syntax>directio <argument>size</argument> | <value>off</value></syntax> -<default>directio off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables the use of -the <c-def>O_DIRECT</c-def> flag (FreeBSD, Linux), -the <c-def>F_NOCACHE</c-def> flag (Mac OS X), -or the <c-func>directio</c-func> function (Solaris), -when reading files that are larger than the specified <argument>size</argument>. -It automatically disables (0.7.15) the use of -<link id="sendfile">sendfile</link> -for a given request. -It could be useful for serving large files: -<example> -directio 4m; -</example> -or when using <link id="aio">aio</link> on Linux. -</para> - -</directive> - - -<directive name="directio_alignment" appeared-in="0.8.11"> -<syntax>directio_alignment <argument>size</argument></syntax> -<default>directio_alignment 512</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets an alignment for -<link id="directio">directio</link>. -In most cases, a 512-byte alignment is enough, however, when -using XFS under Linux, it needs to be increased to 4K. -</para> - -</directive> - - -<directive name="error_page"> -<syntax>error_page - <argument>code</argument> ... - [<value>=</value>[<argument>response</argument>]] - <argument>uri</argument> -</syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<context>if in location</context> - -<para> -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 -<code>error_page</code> -directives on -the current level. -A URI value can contain variables. -</para> - -<para> -Example: -<example> -error_page 404 /404.html; -error_page 502 503 504 /50x.html; -error_page 403 http://example.com/forbidden.html; -</example> -</para> - -<para> -Furthermore, it is possible to change the response code to another, for example: -<example> -error_page 404 =200 /empty.gif; -</example> -</para> - -<para> -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: -<example> -error_page 404 = /404.php; -</example> -</para> - -<para> -If there is no need to change URI during redirection it is possible to redirect -error processing into a named location: -<example> -location / { - error_page 404 = @fallback; -} - -location @fallback { - proxy_pass http://backend; -} -</example> -</para> - -</directive> - - -<directive name="if_modified_since" appeared-in="0.7.24"> -<syntax>if_modified_since - <value>off</value> | - <value>exact</value> | - <value>before</value> -</syntax> -<default>if_modified_since exact</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Specifies how to compare modification time of a response -with the time in the -<header>If-Modified-Since</header> -request header: - -<list type="tag"> - -<tag-name><value>off</value></tag-name> -<tag-desc> -the -<header>If-Modified-Since</header> request header is ignored (0.7.34); -</tag-desc> - -<tag-name><value>exact</value></tag-name> -<tag-desc> -exact match; -</tag-desc> - -<tag-name><value>before</value></tag-name> -<tag-desc> -modification time of a response is -less than or equal to the time in the <header>If-Modified-Since</header> -request header. -</tag-desc> - -</list> -</para> - -</directive> - - -<directive name="internal"> -<syntax>internal</syntax> -<default/> -<context>location</context> - -<para> -Specifies that a given location can only be used for internal requests. -For external requests, the client error -<http-status code="404" text="Not Found"/> -is returned. -Internal requests are the following: - -<list type="bullet"> - -<listitem> -requests redirected by the <link id="error_page">error_page</link> directive; -</listitem> - -<listitem> -subrequests formed by the -<command>include virtual</command> -command of the module -<link doc="ngx_http_ssi_module.xml">ngx_http_ssi_module</link>; -</listitem> - -<listitem> -requests changed by the -<link doc="ngx_http_rewrite_module.xml" id="rewrite">rewrite</link> -directive of the module -<link doc="ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>. -</listitem> - -</list> -</para> - -<para> -Example: -<example> -error_page 404 /404.html; - -location /404.html { - internal; -} -</example> -</para> - -</directive> - - -<directive name="keepalive_requests" appeared-in="0.8.0"> -<syntax>keepalive_requests <argument>number</argument></syntax> -<default>keepalive_requests 100</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets the maximum number of requests that can be -made through one keep-alive connection. -</para> - -</directive> - - -<directive name="keepalive_timeout"> -<syntax>keepalive_timeout - <argument>time</argument> - [<argument>time</argument>] -</syntax> -<default>keepalive_timeout 75</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -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 -<dq><header>Keep-Alive: timeout=<argument>time</argument></header></dq> -response header. -Two arguments may differ. -</para> - -<para> -The -<dq><header>Keep-Alive: timeout=</header></dq> -is understood by Mozilla and Konqueror. -MSIE will close keep-alive connection in about 60 seconds. -</para> - -</directive> - - -<directive name="large_client_header_buffers"> -<syntax>large_client_header_buffers <argument>number size</argument></syntax> -<default>large_client_header_buffers 4 4k/8k</default> -<context>http</context> -<context>server</context> - -<para> -Sets the maximum <argument>number</argument> and <argument>size</argument> of -buffers used when reading large client request headers. -A request line cannot exceed the size of one buffer, or the client error -<http-status code="414" text="Request-URI Too Large"/> -is returned. -A request header field cannot exceed the size of one buffer as well, or the -client error -<http-status code="400" text="Bad Request"/> -is returned. -Buffers are allocated only on demand. -By default, the buffer size is equal to one memory page size. -It is either 4K or 8K, platform dependent. -If after the end of request processing a connection is transitioned -into the keep-alive state, these buffers are freed. -</para> - -</directive> - - -<directive name="limit_except"> -<syntax>limit_except <argument>method</argument> ... { ... }</syntax> -<default/> -<context>location</context> - -<para> -Limits allowed HTTP methods inside a location. -The GET method also implies the HEAD method. -Access to other methods can be limited using the -<link doc="ngx_http_access_module.xml">ngx_http_access_module</link> -and -<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> -modules directives: -<example> -limit_except GET { - allow 192.168.1.0/32; - deny all; -} -</example> -Please note that this will limit access to all methods -<emphasis>except</emphasis> GET and HEAD. -</para> - -</directive> - - -<directive name="limit_rate"> -<syntax>limit_rate <argument>rate</argument></syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<context>if in location</context> - -<para> -Rate limits the transmission of a response to a client. -The <argument>rate</argument> is specified in bytes per second. -<!-- -The smaller the rate, the more accurate will be the limitation. ---> -The limit is per connection, so if a single client opens 2 connections, -an overall rate will be 2x more than specified. -</para> - -<para> -This directive is not applicable if one wants to rate limit -a group of clients on the -<link id="server">server</link> -level. -If that is the case, the desired limit can be specified in the -<var>$limit_rate</var> -variable: -<example> -server { - - if ($slow) { - set $limit_rate 4k; - } - - ... -} -</example> -</para> - -</directive> - - -<directive name="limit_rate_after" appeared-in="0.8.0"> -<syntax>limit_rate_after <argument>size</argument></syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<context>if in location</context> - -<para> -Sets the initial amount after which the further transmission -of a response to a client will be rate limited. -</para> - -<para> -Example: -<example> -location /flv/ { - flv; - limit_rate_after 500k; - limit_rate 50k; -} -</example> -</para> - -</directive> - - -<directive name="listen"> -<syntax>listen - <argument>address</argument>[:<argument>port</argument>] - [<parameter>default</parameter> | <parameter>default_server</parameter> - [<parameter>backlog</parameter>=<argument>number</argument>] - [<parameter>rcvbuf</parameter>=<argument>size</argument>] - [<parameter>sndbuf</parameter>=<argument>size</argument>] - [<parameter>accept_filter</parameter>=<argument>filter</argument>] - [<parameter>deferred</parameter>] - [<parameter>bind</parameter>] - [<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>] - [<parameter>ssl</parameter>]] -</syntax> -<syntax>listen - <argument>port</argument> - [<parameter>default</parameter> | <parameter>default_server</parameter> - [<parameter>backlog</parameter>=<argument>number</argument>] - [<parameter>rcvbuf</parameter>=<argument>size</argument>] - [<parameter>sndbuf</parameter>=<argument>size</argument>] - [<parameter>accept_filter</parameter>=<argument>filter</argument>] - [<parameter>deferred</parameter>] - [<parameter>bind</parameter>] - [<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>] - [<parameter>ssl</parameter>]] -</syntax> -<default>listen *:80 | *:8000</default> -<context>server</context> - -<para> -Sets an <argument>address</argument> and a <argument>port</argument>, on which -the server will accept requests. -Only one of <argument>address</argument> or <argument>port</argument> can be -specified. -An <argument>address</argument> may also be a hostname, for example: -<example> -listen 127.0.0.1:8000; -listen 127.0.0.1; -listen 8000; -listen *:8000; -listen localhost:8000; -</example> -IPv6 addresses (0.7.36) are specified in square brackets: -<example> -listen [::]:8000; -listen [fe80::1]; -</example> -</para> - -<para> -If only <argument>address</argument> is given, the port 80 is used. -</para> - -<para> -If directive is not present then either the <code>*:80</code> is used -if nginx runs with superuser privileges, or <code>*:8000</code> otherwise. -</para> - -<para> -The <parameter>default</parameter> parameter, if present, -will cause the server to become the default server for the specified -<argument>address</argument>:<argument>port</argument> pair. -If none of the directives have the <parameter>default</parameter> -parameter then the first server with the -<argument>address</argument>:<argument>port</argument> pair will be -the default server for this pair. -Starting from version 0.8.21 it is possible to use the -<parameter>default_server</parameter> -parameter. -</para> - -<para> -A <code>listen</code> directive which has the <parameter>default</parameter> -parameter can have several additional parameters specific to system calls -<c-func>listen</c-func> and <c-func>bind</c-func>. -Starting from version 0.8.21, these parameters can be specified in any -<code>listen</code> directive, but only once for the given -<argument>address</argument>:<argument>port</argument> pair. -<list type="tag"> - -<tag-name> -<parameter>backlog</parameter>=<argument>number</argument> -</tag-name> -<tag-desc> -sets the <parameter>backlog</parameter> parameter in the -<c-func>listen</c-func> call. -By default, <parameter>backlog</parameter> equals -1 on FreeBSD -and 511 on other platforms. -</tag-desc> - -<tag-name> -<parameter>rcvbuf</parameter>=<argument>size</argument> -</tag-name> -<tag-desc> -sets the <c-def>SO_RCVBUF</c-def> parameter for the listening socket. -</tag-desc> - -<tag-name> -<parameter>sndbuf</parameter>=<argument>size</argument> -</tag-name> -<tag-desc> -sets the <c-def>SO_SNDBUF</c-def> parameter for the listening socket. -</tag-desc> - -<tag-name> -<parameter>accept_filter</parameter>=<argument>filter</argument> -</tag-name> -<tag-desc> -sets the name of the accept filter. -This works only on FreeBSD, acceptable values are <value>dataready</value> -and <value>httpready</value>. -On receipt of the <c-def>SIGHUP</c-def> signal, an accept filter can only be -changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE -and 4.11-STABLE. -</tag-desc> - -<tag-name> -<parameter>deferred</parameter> -</tag-name> -<tag-desc> -instructs to use a deferred <c-func>accept</c-func> on Linux -using the <c-def>TCP_DEFER_ACCEPT</c-def> option. -</tag-desc> - -<tag-name> -<parameter>bind</parameter> -</tag-name> -<tag-desc> -specifies to make a separate <c-func>bind</c-func> call for a given -<argument>address</argument>:<argument>port</argument> pair. -This is because nginx will only <c-func>bind</c-func> to -<code>*</code>:<argument>port</argument> -if there are several <code>listen</code> directives with -the same port but different addresses, and one of the -<code>listen</code> directives listens on all addresses -for the given port (<code>*</code>:<argument>port</argument>). -It should be noted that in this case a <c-func>getsockname</c-func> -system call will be made to determine an address that accepted a -connection. -If parameters <parameter>backlog</parameter>, <parameter>rcvbuf</parameter>, -<parameter>sndbuf</parameter>, <parameter>accept_filter</parameter>, or -<parameter>deferred</parameter> are used then for a given -<argument>address</argument>:<argument>port</argument> pair -a separate <c-func>bind</c-func> call will always be made. -</tag-desc> - -<tag-name> -<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value> -</tag-name> -<tag-desc> -this parameter (0.7.42) sets the value of the <c-def>IPV6_V6ONLY</c-def> -parameter for the listening socket. -This parameter can only be set once on start. -</tag-desc> - -<tag-name> -<parameter>ssl</parameter> -</tag-name> -<tag-desc> -this parameter (0.7.14) does not relate to system calls -<c-func>listen</c-func> and <c-func>bind</c-func>, but allows to -specify that all connections accepted on this port should work in -the SSL mode. -This allows for a more compact configuration for the server operating -in both HTTP and HTTPS modes simultaneously. -<example> -listen 80; -listen 443 default ssl; -</example> -</tag-desc> - -</list> -</para> - -<para> -Example: -<example> -listen 127.0.0.1 default accept_filter=dataready backlog=1024; -</example> -</para> - -</directive> - - -<directive name="location"> -<syntax>location [ - <value>=</value> | - <value>~</value> | - <value>~*</value> | - <value>^~</value> | - <value>@</value> - ] <argument>uri</argument> -{ ... }</syntax> -<default/> -<context>server</context> -<!-- -<context>location</context> ---> - -<para> -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 -<dq><value>~*</value></dq> prefix (for case-insensitive matching), or with the -<dq><value>~</value></dq> 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. -Then regular expressions are checked, in the order of their appearance -in a configuration file. -A search terminates on the first match, and its corresponding -configuration is used. -If no match with a regular expression location is found then a -configuration of the most specific prefix location is used. -</para> - -<para> -For case-insensitive operating systems such as Mac OS X and Cygwin, -the string matching ignores a case (0.7.7). -However, comparison is limited to one-byte locales. -</para> - -<para> -Regular expressions can contain captures (0.7.40) that can later -be used in other directives. -</para> - -<para> -If the most specific prefix location has the <dq><value>^~</value></dq> prefix -then regular expressions are not checked. -</para> - -<para> -Also, using the <dq><value>=</value></dq> 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 <dq><code>/</code></dq> request happens frequently, -defining <dq><code>location = /</code></dq> will speed up the processing -of these requests, as search terminates right after the first -comparison. -</para> - -<para> -In versions from 0.7.1 to 0.8.41, if a request matched the prefix -location without the <dq><value>=</value></dq> and <dq><value>^~</value></dq> -prefixes, the search also terminated and regular expressions were -not checked. -</para> - -<para> -Let's illustrate the above by example: -<example> -location = / { - [ configuration A ] -} - -location / { - [ configuration B ] -} - -location ^~ /images/ { - [ configuration C ] -} - -location ~* \.(gif|jpg|jpeg)$ { - [ configuration D ] -} -</example> -The <dq><code>/</code></dq> request will match configuration A, -the <dq><code>/documents/document.html</code></dq> request will match -configuration B, -the <dq><code>/images/1.gif</code></dq> request will match configuration C, and -the <dq><code>/documents/1.jpg</code></dq> request will match configuration D. -</para> - -<para> -The <dq><value>@</value></dq> prefix defines a named location. -Such a location is not used for a regular request processing, but instead -used for request redirection. -</para> - -<!-- -<migration from="Apache" directive="Location" /> ---> - -</directive> - - -<directive name="log_not_found"> -<syntax>log_not_found <value>on</value> | <value>off</value></syntax> -<default>log_not_found on</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables logging of errors about not found files into the -<link doc="../ngx_core_module.xml" id="error_log">error_log</link>. -</para> - -</directive> - - -<directive name="log_subrequest"> -<syntax>log_subrequest <value>on</value> | <value>off</value></syntax> -<default>log_subrequest off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables logging of subrequests into the -<link doc="ngx_http_log_module.xml" id="access_log">access_log</link>. -</para> - -</directive> - - -<directive name="merge_slashes"> -<syntax>merge_slashes <value>on</value> | <value>off</value></syntax> -<default>merge_slashes on</default> -<context>http</context> -<context>server</context> - -<para> -Enables or disables compression of two or more adjacent slashes -in a URI into a single slash. -</para> - -<para> -Note that compression is essential for the correct prefix string -and regular expressions location matching. -Without it, the <dq><code>//scripts/one.php</code></dq> request would not match -<example> -location /scripts/ { - ... -} -</example> -and might be processed as a static file, -so it gets converted to <dq><code>/scripts/one.php</code></dq>. -</para> - -<para> -Turning the compression <value>off</value> can become necessary if a URI -contains base64-encoded names, since base64 uses the "/" character internally. -However, for security considerations, it is better to avoid turning off -the compression. -</para> - -<para> -If a directive is specified on the -<link id="server">server</link> -level, which is also a default server, its value will cover -all virtual servers listening on the same address and port. -</para> - -</directive> - - -<directive name="msie_padding"> -<syntax>msie_padding <value>on</value> | <value>off</value></syntax> -<default>msie_padding on</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables adding of comments to responses with status -greater than 400 for MSIE clients, to pad the response size to 512 bytes. -</para> - -</directive> - - -<directive name="msie_refresh"> -<syntax>msie_refresh <value>on</value> | <value>off</value></syntax> -<default>msie_refresh off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables issuing refreshes instead of redirects, for MSIE clients. -</para> - -</directive> - - -<directive name="open_file_cache"> -<syntax>open_file_cache -<parameter>max</parameter>=<argument>N</argument> -[<parameter>inactive</parameter>=<argument>time</argument>] | -<value>off</value> -</syntax> -<default>open_file_cache off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Configures a cache that can store: -<list type="bullet"> - -<listitem> -open file descriptors, their sizes and modification times; -</listitem> - -<listitem> -directory lookups; -</listitem> - -<listitem> -file lookup errors, such as "file not found", "no read permission", -and so on. -Caching of errors should be enabled separately by the -<link id="open_file_cache_errors">open_file_cache_errors</link> -directive. -</listitem> - -</list> -</para> - -<para> -The directive has the following parameters: -<list type="tag"> - -<tag-name> -<parameter>max</parameter> -</tag-name> -<tag-desc> -sets the maximum number of elements in the cache; -on cache overflow the least recently used (LRU) elements get removed; -</tag-desc> - -<tag-name> -<parameter>inactive</parameter> -</tag-name> -<tag-desc> -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; -</tag-desc> - -<tag-name> -<value>off</value> -</tag-name> -<tag-desc> -disables the cache. -</tag-desc> - -</list> -</para> - -<para> -Example: -<example> -open_file_cache max=1000 inactive=20s; -open_file_cache_valid 30s; -open_file_cache_min_uses 2; -open_file_cache_errors on; -<!-- -open_file_cache_events on; ---> -</example> -</para> - -</directive> - - -<directive name="open_file_cache_errors"> -<syntax>open_file_cache_errors <value>on</value> | <value>off</value></syntax> -<default>open_file_cache_errors off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables caching of file lookup errors by the -<link id="open_file_cache">open_file_cache</link>. -</para> - -</directive> - - -<!-- - -<directive name="open_file_cache_events"> -<syntax>open_file_cache_events <value>on</value> | <value>off</value></syntax> -<default>open_file_cache_events off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables to use kernel events to validate -<link id="open_file_cache">open_file_cache</link> -elements. -This directive works with the -<link doc="../events.xml" id="kqueue">kqueue</link> -method only. -Note that only NetBSD 2.0+ and FreeBSD 6.0+ -support events for arbitrary file system types. -Other operating systems support events only for essential -file systems such as UFS or FFS. -</para> - -</directive> - ---> - - -<directive name="open_file_cache_min_uses"> -<syntax>open_file_cache_min_uses <argument>number</argument></syntax> -<default>open_file_cache_min_uses 1</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets the minimum <argument>number</argument> of file accesses during -the period configured by the <parameter>inactive</parameter> parameter -of the <link id="open_file_cache">open_file_cache</link> directive, -after which a file descriptor will remain open in the cache. -</para> - -</directive> - - -<directive name="open_file_cache_valid"> -<syntax>open_file_cache_valid <argument>time</argument></syntax> -<default>open_file_cache_valid 60</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets a time after which -<link id="open_file_cache">open_file_cache</link> -elements should be validated. -<!-- -When <link id="open_file_cache_events"> -open_file_cache_events</link> is enabled, open file descriptors -are checked only once, and then updated right after they get changed. ---> -</para> - -</directive> - - -<directive name="optimize_server_names"> -<syntax>optimize_server_names <value>on</value> | <value>off</value></syntax> -<default>optimize_server_names on</default> -<context>http</context> -<context>server</context> - -<para> -This directive is obsolete. -</para> - -<para> -Enables or disables optimization of hostname checking in name-based -virtual servers. -In particular, the checking affects hostnames used in redirects. -If optimization is enabled, and all name-based servers listening on -the same address:port pair have identical configuration, then -names are not checked during request processing, and the first -server name is used in redirects. -In case redirects should use hostnames sent by clients, -optimization needs to be disabled. -</para> - -</directive> - - -<directive name="port_in_redirect"> -<syntax>port_in_redirect <value>on</value> | <value>off</value></syntax> -<default>port_in_redirect on</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables specifying the port in redirects issued by nginx. -</para> - -</directive> - - -<directive name="read_ahead"> -<syntax>read_ahead <argument>size</argument></syntax> -<default>read_ahead 0</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets the amount of pre-reading when working with files, in the kernel. -</para> - -<para> -On Linux, the -<code>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</code> -system call is used, so the <argument>size</argument> argument is ignored. -</para> - -<para> -On FreeBSD, the -<code>fcntl(O_READAHEAD,</code><argument>size</argument><code>)</code> -system call is used, supported in FreeBSD 9.0-CURRENT. -FreeBSD 7 needs to be -<link url="http://sysoev.ru/freebsd/patch.readahead.txt">patched</link>. -</para> - -</directive> - - -<directive name="recursive_error_pages"> -<syntax>recursive_error_pages <value>on</value> | <value>off</value></syntax> -<default>recursive_error_pages off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables doing several redirects using the -<link id="error_page">error_page</link> -directive. -</para> - -</directive> - - -<directive name="reset_timedout_connection"> -<syntax>reset_timedout_connection - <value>on</value> | <value>off</value></syntax> -<default>reset_timedout_connection off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables resetting of timed out connections. -The reset is performed as follows: before closing a socket, the -<c-def>SO_LINGER</c-def> -option is set on it with a timeout value of 0. -When the socket is closed, a client is sent TCP RST, and all memory -occupied by this socket is freed. -This avoids keeping of an already closed socket with filled buffers -for a long time, in a FIN_WAIT1 state. -</para> - -<para> -It should be noted that timed out keep-alive connections are still -closed normally. -</para> - -</directive> - - -<directive name="resolver"> -<syntax>resolver <argument>address</argument></syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets the <argument>address</argument> of a name server, for example: -<example> -resolver 127.0.0.1; -</example> -</para> - -</directive> - - -<directive name="resolver_timeout"> -<syntax>resolver_timeout <argument>time</argument></syntax> -<default>resolver_timeout 30s</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets a timeout for name resolution, for example: -<example> -resolver_timeout 5s; -</example> -</para> - -</directive> - - -<directive name="root"> -<syntax>root <argument>path</argument></syntax> -<default>root html</default> -<context>http</context> -<context>server</context> -<context>location</context> -<context>if in location</context> - -<para> -Sets the root directory for requests. -For example, with the following configuration -<example> -location /i/ { - root /data/w3; -} -</example> -<dq><code>/i/top.gif</code></dq> will be responded -with the file -<dq><pathname>/data/w3/i/top.gif</pathname></dq>. -</para> - -<para> -The <argument>path</argument> value can contain variables. -</para> - -<para> -A path to the file is constructed by merely adding a URI to the value -of the <code>root</code> directive. -If a URI need to be modified, the -<link id="alias">alias</link> directive should be used. -</para> - -</directive> - - -<directive name="satisfy"> -<syntax>satisfy <value>all</value> | <value>any</value></syntax> -<default>satisfy all</default> -<context>location</context> - -<para> -Allows access if any of the -<link doc="ngx_http_access_module.xml">ngx_http_access_module</link> -or <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> -modules grant access. -<example> -location / { - satisfy any; - - allow 192.168.1.0/32; - deny all; - - auth_basic "closed site"; - auth_basic_user_file conf/htpasswd; -} -</example> -</para> - -</directive> - - -<directive name="satisfy_any"> -<syntax>satisfy_any <value>on</value> | <value>off</value></syntax> -<default>satisfy_any off</default> -<context>location</context> - -<para> -This directive was renamed to the <link id="satisfy">satisfy</link> directive. -</para> - -</directive> - - -<directive name="send_timeout"> -<syntax>send_timeout <argument>time</argument></syntax> -<default>send_timeout 60</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets a timeout for transmitting a response to the client. -A timeout is only set between two successive write operations, -not for the transmission of the whole response. -If a client does not receive anything within this time, -a connection is closed. -</para> - -</directive> - - -<directive name="sendfile"> - -<syntax>sendfile <value>on</value> | <value>off</value></syntax> -<default>sendfile off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables the use of -<c-func>sendfile</c-func>. -</para> - -</directive> - - -<directive name="server"> -<syntax>server { ... }</syntax> -<default/> -<context>http</context> - -<para> -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 <header>Host</header> request header field) -virtual servers. -Instead, the <link id="listen">listen</link> directives describe all -addresses and ports that should accept connections for a server, and the -<link id="server_name">server_name</link> directive lists all server names. -An example configuration is provided in the -<link doc="../virtual_hosts.xml"> -Setting Up Virtual Servers</link> document. -</para> - -</directive> - - -<directive name="server_name"> -<syntax>server_name <argument>name</argument> ...</syntax> -<default>server_name hostname</default> -<context>server</context> - -<para> -Sets names of the virtual server, for example: -<example> -server { - server_name example.com www.example.com; -} -</example> -</para> - -<para> -The first name becomes a primary server name. -By default, the machine's hostname is used. -Server names can include an asterisk (<dq><code>*</code></dq>) -to replace the first or last part of a name: -<example> -server { - server_name example.com *.example.com www.example.*; -} -</example> -</para> - -<para> -The first two of the above mentioned names can be combined: -<example> -server { - server_name .example.com; -} -</example> -</para> - -<para> -It is also possible to use regular expressions in server names, -prepending the name with a tilde (<dq><code>~</code></dq>): -<example> -server { - server_name www.example.com ~^www\d+\.example\.com$; -} -</example> -</para> - -<para> -Regular expressions can contain captures (0.7.40) that can later -be used in other directives: -<example> -server { - server_name ~^(www\.)?(.+)$; - - location / { - root /sites/$2; - } -} - -server { - server_name _; - - location / { - root /sites/default; - } -} -</example> -</para> - -<para> -Starting from version 0.8.25, named captures in regular expressions create -variables that can later be used in other directives: -<example> -server { - server_name ~^(www\.)?(?<domain>.+)$; - - location / { - root /sites/$domain; - } -} - -server { - server_name _; - - location / { - root /sites/default; - } -} -</example> -</para> - -<para> -Starting from version 0.7.11, it is possible to specify an empty name: -<example> -server { - server_name www.example.com ""; -} -</example> -It allows this server to process requests without the <header>Host</header> -header, instead of the default server for the given address:port pair. -</para> - -<para> -The name checking order is as follows: -<list type="enum"> - -<listitem> -full names -</listitem> - -<listitem> -names with the prefix mask, e.g. <dq><code>*.example.com</code></dq> -</listitem> - -<listitem> -names with the suffix mask, e.g. <dq><code>mail.*</code></dq> -</listitem> - -<listitem> -regular expressions -</listitem> - -</list> -</para> - -</directive> - - -<directive name="server_name_in_redirect"> -<syntax>server_name_in_redirect <value>on</value> | <value>off</value></syntax> -<default>server_name_in_redirect on</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables the use of the primary server name, specified by the -<link id="server_name">server_name</link> -directive, in redirects issued by nginx. -When disabled, the name from the <header>Host</header> request header field -is used. -If this field is not present, an IP address of the server is used. -</para> - -</directive> - - -<directive name="server_names_hash_max_size"> -<syntax>server_names_hash_max_size <argument>size</argument></syntax> -<default>server_names_hash_max_size 512</default> -<context>http</context> - -<para> -Sets the maximum <argument>size</argument> of the server names hash tables. -For more information, please refer to -<link doc="../hash.xml">Setting Up Hashes</link>. -</para> - -</directive> - - -<directive name="server_names_hash_bucket_size"> -<syntax>server_names_hash_bucket_size <argument>size</argument></syntax> -<default>server_names_hash_bucket_size 32/64/128</default> -<context>http</context> - -<para> -Sets the bucket size for the server names hash tables. -Default value depends on the size of the processor's cache line. -For more information, please refer to -<link doc="../hash.xml">Setting Up Hashes</link>. -</para> - -</directive> - - -<directive name="server_tokens"> -<syntax>server_tokens <value>on</value> | <value>off</value></syntax> -<default>server_tokens on</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables emitting of nginx version in error messages and in the -<header>Server</header> response header field. -</para> - -</directive> - - -<directive name="tcp_nodelay"> -<syntax>tcp_nodelay <value>on</value> | <value>off</value></syntax> -<default>tcp_nodelay on</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables the use of the <c-def>TCP_NODELAY</c-def> option. -The option is enabled only when a connection is transitioned into the -keep-alive state. -</para> - -</directive> - - -<directive name="tcp_nopush"> -<syntax>tcp_nopush <value>on</value> | <value>off</value></syntax> -<default>tcp_nopush off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables the use of -the <c-def>TCP_NOPUSH</c-def> socket option on FreeBSD -or the <c-def>TCP_CORK</c-def> socket option on Linux. -Opitons are enables only when <link id="sendfile">sendfile</link> is used. -Enabling the option allows to -<list type="bullet"> - -<listitem> -send the response header and the beginning of a file in one packet, -on Linux and FreeBSD 4.*; -</listitem> - -<listitem> -send a file in full packets. -</listitem> - -</list> -</para> - -</directive> - - -<directive name="try_files"> -<syntax>try_files - <argument>file</argument> ... - <argument>uri</argument> -</syntax> -<syntax>try_files - <argument>file</argument> ... - =<argument>code</argument> -</syntax> -<default/> -<context>location</context> - -<para> -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. <dq><code>$uri/</code></dq>. -If none of the files were found, an internal redirect to the -<argument>uri</argument> specified by the last argument is made. -As of version 0.7.51, the last argument can also be a -<argument>code</argument>: -<example> -location / { - try_files $uri $uri/index.html $uri.html =404; -} -</example> -</para> - -<para> -Example when proxying Mongrel: -<example> -location / { - try_files /system/maintenance.html - $uri $uri/index.html $uri.html - @mongrel; -} - -location @mongrel { - proxy_pass http://mongrel; -} -</example> -</para> - -<para> -Example for Drupal/FastCGI: -<example> -location / { - try_files $uri $uri/ @drupal; -} - -location ~ \.php$ { - try_files $uri @drupal; - - fastcgi_pass ...; - - 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_param SCRIPT_FILENAME /path/to/index.php; - fastcgi_param SCRIPT_NAME /index.php; - fastcgi_param QUERY_STRING q=$uri&$args; - - ... other fastcgi_param's -} -</example> -In the following example, -<example> -location / { - try_files $uri $uri/ @drupal; -} -</example> -the <code>try_files</code> directive is equivalent to -<example> -location / { - error_page 404 = @drupal; - log_not_found off; -} -</example> -And here, -<example> -location ~ \.php$ { - try_files $uri @drupal; - - fastcgi_pass ...; - - fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; - - ... -} -</example> -<code>try_files</code> checks the existence of the PHP file -before passing the request to the FastCGI server. -</para> - -<para> -Example for Wordpress and Joomla: -<example> -location / { - try_files $uri $uri/ @wordpress; -} - -location ~ \.php$ { - try_files $uri @wordpress; - - fastcgi_pass ...; - - fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; - ... other fastcgi_param's -} - -location @wordpress { - fastcgi_pass ...; - - fastcgi_param SCRIPT_FILENAME /path/to/index.php; - ... other fastcgi_param's -} -</example> -</para> - -</directive> - - -<directive name="types"> -<syntax>types { ... }</syntax> -<default>see below</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Maps file name extensions to MIME types of responses. -Several extensions can map to one type. -The following mappings are configured by default: -<example> -types { - text/html html; - image/gif gif; - image/jpeg jpg; -} -</example> -</para> - -<para> -A sufficiently full mapping table is distributed with nginx in the -<pathname>conf/mime.types</pathname> file. -</para> - -<para> -To make a particular location emit the -<dq><code>application/octet-stream</code></dq> -MIME type for all requests, try the following: -<example> -location /download/ { - types { } - default_type application/octet-stream; -} -</example> -</para> - -</directive> - - -<directive name="underscores_in_headers"> -<syntax>underscores_in_headers <value>on</value> | <value>off</value></syntax> -<default>underscores_in_headers off</default> -<context>http</context> -<context>server</context> - -<para> -Enables or disables the use of underscores in client request header fields. -</para> - -</directive> - -</section> - -<section id="variables" name="Embedded Variables"> - -<para> -The module <code>ngx_http_core_module</code> supports embedded variables with -names matching those of the Apache Server. -First of all, these are variables representing client request header -fields, such as, <var>$http_user_agent</var>, <var>$http_cookie</var>, -and so on. -It also supports other variables: -<list type="tag"> - -<tag-name><var>$args</var></tag-name> -<tag-desc> -arguments in the request line -</tag-desc> - -<tag-name><var>$arg_</var><argument>name</argument></tag-name> -<tag-desc> -argument <argument>name</argument> in the request line -</tag-desc> - -<tag-name><var>$binary_remote_addr</var></tag-name> -<tag-desc> -client address in a binary form, value's length is always 4 bytes -</tag-desc> - -<tag-name><var>$content_length</var></tag-name> -<tag-desc> -<header>Content-Length</header> request header field -</tag-desc> - -<tag-name><var>$content_type</var></tag-name> -<tag-desc> -<header>Content-Type</header> request header field -</tag-desc> - -<tag-name><var>$cookie_</var><argument>name</argument></tag-name> -<tag-desc> -the <argument>name</argument> cookie -</tag-desc> - -<tag-name><var>$document_root</var></tag-name> -<tag-desc> -<link id="root">root</link> directive's value for the current request -</tag-desc> - -<tag-name><var>$document_uri</var></tag-name> -<tag-desc> -same as <var>$uri</var> -</tag-desc> - -<tag-name><var>$host</var></tag-name> -<tag-desc> -<header>Host</header> request header field, -or the server name matching a request if this field is not present -</tag-desc> - -<tag-name><var>$hostname</var></tag-name> -<tag-desc> -host name -</tag-desc> - -<tag-name><var>$http_</var><argument>name</argument></tag-name> -<tag-desc> -the <argument>name</argument> request header field -</tag-desc> - -<tag-name><var>$is_args</var></tag-name> -<tag-desc> -<dq><code>?</code></dq> if a request line has arguments, -or an empty string otherwise -</tag-desc> - -<tag-name><var>$limit_rate</var></tag-name> -<tag-desc> -allows for connection rate limiting -</tag-desc> - -<tag-name><var>$pid</var></tag-name> -<tag-desc> -PID of the worker process -</tag-desc> - -<tag-name><var>$request_method</var></tag-name> -<tag-desc> -request method, usually -<dq><code>GET</code></dq> or <dq><code>POST</code></dq> -</tag-desc> - -<tag-name><var>$remote_addr</var></tag-name> -<tag-desc> -client address -</tag-desc> - -<tag-name><var>$remote_port</var></tag-name> -<tag-desc> -client port -</tag-desc> - -<tag-name><var>$remote_user</var></tag-name> -<tag-desc> -user name supplied with the Basic authentication -</tag-desc> - -<tag-name><var>$realpath_root</var></tag-name> -<tag-desc> -<link id="root">root</link> directive's value -for the current request, with all symbolic links resolved to real paths -</tag-desc> - -<tag-name><var>$request_filename</var></tag-name> -<tag-desc> -file path for the current query, based on the -<link id="root">root</link> and <link id="alias">alias</link> -directives, and the request URI -</tag-desc> - -<tag-name><var>$request_body</var></tag-name> -<tag-desc> -request body -<para> -The variable's value is made available in locations -processed by the -<link doc="ngx_http_proxy_module.xml" id="proxy_pass">proxy_pass</link> -and -<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass">fastcgi_pass</link> -directives. -</para> -</tag-desc> - -<tag-name><var>$request_body_file</var></tag-name> -<tag-desc> -name of a temporary file with the request body -<para> -At the end of processing, the file needs to be removed. -To always write a request body to a file, -<link id="client_body_in_file_only">client_body_in_file_only on</link> -needs be specified. -When passing the name of a temporary file in a proxied request, -or in a request to a FastCGI server, -passing of the request body should be disabled by the -<link doc="ngx_http_proxy_module.xml" -id="proxy_pass_request_body">proxy_pass_request_body</link> -and -<link doc="ngx_http_fastcgi_module.xml" -id="fastcgi_pass_request_body">fastcgi_pass_request_body</link> -directives, respectively. -</para> -</tag-desc> - -<tag-name><var>$request_uri</var></tag-name> -<tag-desc> -full original request URI (with arguments) -</tag-desc> - -<tag-name><var>$query_string</var></tag-name> -<tag-desc> -same as <var>$args</var> -</tag-desc> - -<tag-name><var>$scheme</var></tag-name> -<tag-desc> -request scheme, <dq><code>http</code></dq> or <dq><code>https</code></dq> -</tag-desc> - -<tag-name><var>$server_protocol</var></tag-name> -<tag-desc> -request protocol, usually -<dq><code>HTTP/1.0</code></dq> -or -<dq><code>HTTP/1.1</code></dq> -</tag-desc> - -<tag-name><var>$server_addr</var></tag-name> -<tag-desc> -an address of the server which accepted a request -<para> -Computing a value of this variable usually requires one system call. -To avoid a system call, the <link id="listen">listen</link> directives -must specify addresses and use the <parameter>bind</parameter> parameter -</para> -</tag-desc> - -<tag-name><var>$server_name</var></tag-name> -<tag-desc> -name of the server which accepted a request -</tag-desc> - -<tag-name><var>$server_port</var></tag-name> -<tag-desc> -port of the server which accepted a request -</tag-desc> - -<tag-name><var>$uri</var></tag-name> -<tag-desc> -current URI in request -<para> -It may differ from an original, e.g. when doing internal redirects, -or when using index files. -</para> -</tag-desc> - -</list> -</para> - -</section> - -</module>
deleted file mode 100644 --- a/docs/xml/http/ngx_http_mp4_module.xml +++ /dev/null @@ -1,156 +0,0 @@ -<?xml version="1.0"?> - -<!DOCTYPE module SYSTEM "../../dtd/module.dtd"> - -<module name="HTTP MP4 Module" id="http_mp4_module"> - -<section name="Summary"> - -<para> -The module <code>ngx_http_mp4_module</code> provides pseudo-streaming -server-side support for H.264/AAC files typically having filename extensions -<pathname>.mp4</pathname>, <pathname>.m4v</pathname>, -and <pathname>.m4a</pathname>. -</para> - -<para> -Pseudo-streaming works in alliance with conformant Flash players. -A player sends an HTTP request to the server with a start time -argument in the request URI’s query string (named simply -<parameter>start</parameter> -and specified in seconds), and the server responds with a stream -so that its start position corresponds to the requested time, -for example: -<example> -http://example.com/elephants_dream.mp4?start=238.88 -</example> -This allows for a random seeking at any time, or starting playback -in the middle of a timeline. -</para> - -<para> -To support seeking, H.264-based formats store the metadata -in the so-called “moov atom.” -It is a part of the file that holds the index information for the -whole file. -</para> - -<para> -To start playback, a player first needs to read metadata. -This is done by sending a special request with the -<parameter>start=0</parameter> -argument. Many encoding software will insert the metadata at -the end of the file. This is bad for pseudo-streaming: -the metadata needs to be located at the beginning of the file, -or else the entire file will have to be downloaded before it -starts playing. If a file is well-formed (with metadata at the -beginning of a file), nginx just sends back the contents of a file. -Otherwise, it has to read the file and prepare a new stream so that -metadata comes before media data. -This involves some CPU, memory, and disk I/O overhead, -so it is a good idea to -<link url="http://flowplayer.org/plugins/streaming/pseudostreaming.html#prepare"> -prepare an original file for pseudo-streaming</link>, -rather than having nginx do this on every such request. -</para> - -<para> -For a matching request with a non-zero -<parameter>start</parameter> -argument, nginx will read metadata from the file, prepare the -stream starting from the requested offset, and send it to a client. -This has the same overhead as described above. -</para> - -<para> -If a matching request does not include the -<parameter>start</parameter> -argument, there is no overhead, and the file is just sent as a static resource. -Some players also support byte-range requests, and thus do not require -this module at all. -</para> - -<para> -This module is not built by default, it should be enabled with the -<code>--with-http_mp4_module</code> -configuration parameter. -<note> -If you were using the third-party mp4 module, be sure to disable it. -</note> -</para> - -<para> -A similar pseudo-streaming support for FLV files is provided by the module -<link doc="ngx_http_flv_module.xml">ngx_http_flv_module</link>. -</para> - -</section> - - -<section id="example" name="Example Configuration"> - -<para> -<example> -location /video/ { - mp4; - mp4_buffer_size 1m; - mp4_max_buffer_size 5m; -} -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="mp4"> -<syntax>mp4</syntax> -<default/> -<context>location</context> - -<para> -Turns on module processing in a surrounding location. -</para> - -</directive> - - -<directive name="mp4_buffer_size"> -<syntax>mp4_buffer_size <argument>size</argument></syntax> -<default>mp4_buffer_size 512K</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets the initial size of a memory buffer used to process MP4 files. -</para> - -</directive> - - -<directive name="mp4_max_buffer_size"> -<syntax>mp4_max_buffer_size <argument>size</argument></syntax> -<default>mp4_max_buffer_size 10M</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -During metadata processing, a larger buffer may become necessary. -Its size cannot exceed the specified <argument>size</argument>, -or else nginx will return the server error -<http-status code="500" text="Internal Server Error"/>, -and log the following: -<example> -"/some/movie/file.mp4" mp4 moov atom is too large: -12583268, you may want to increase mp4_max_buffer_size -</example> -</para> - -</directive> - -</section> - -</module>
deleted file mode 100644 --- a/docs/xml/ngx_core_module.xml +++ /dev/null @@ -1,292 +0,0 @@ -<?xml version="1.0"?> - -<!DOCTYPE module SYSTEM "../dtd/module.dtd"> - -<module name="Core Module" id="core_module"> - -<section id="example" name="Example Configuration"> - -<para> -<example> -user www www; -worker_processes 2; - -error_log /var/log/nginx-error.log info; - -events { - use kqueue; - worker_connections 2048; -} - -... -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="daemon"> -<syntax>daemon <value>on</value> | <value>off</value></syntax> -<default>daemon on</default> -<context>main</context> - -<para> -Determines whether nginx should become a daemon. -Mainly used during development. -</para> - -</directive> - - -<directive name="env"> -<syntax>env <argument>VAR</argument>[=<argument>VALUE</argument>]</syntax> -<default>env TZ</default> -<context>main</context> - -<para> -Allows to limit a set of environment variables, change their values, -or create new environment variables, for the following cases: -<list type="bullet"> - -<listitem> -variable inheritance during a -<link doc="control.xml" id="upgrade">live upgrade</link> -of an executable file; -</listitem> - -<listitem> -use of variables by the module -<link doc="http/ngx_http_perl_module.xml">ngx_http_perl_module</link>; -</listitem> - -<listitem> -use of variables by worker processes. -Please bear in mind that controlling system libraries in this way -is not always possible as it is not uncommon for libraries to check -variables only during initialization, well before they can be set -using this directive. -An exception from this is an above mentioned -<link doc="control.xml" id="upgrade">live upgrade</link> -of an executable file. -</listitem> - -</list> -</para> - -<para> -The TZ variable is always inherited and made available to the module -<link doc="http/ngx_http_perl_module.xml">ngx_http_perl_module</link>, -unless configured explicitly. -</para> - -<para> -Usage example: -<example> -env MALLOC_OPTIONS; -env PERL5LIB=/data/site/modules; -env OPENSSL_ALLOW_PROXY_CERTS=1; -</example> -</para> - -</directive> - -<directive name="include"> -<syntax>include <argument>file</argument> | <argument>mask</argument></syntax> -<default/> -<context/> - -<para> -Includes another <argument>file</argument>, or files matching the -specified <argument>mask</argument>, into configuration. -Included files should consist of -syntactically correct directives and blocks. -</para> - -<para> -Usage example: -<example> -include mime.types; -include vhosts/*.conf; -</example> -</para> - -</directive> - - -<directive name="master_process"> -<syntax>master_process <value>on</value> | <value>off</value></syntax> -<default>master_process on</default> -<context>main</context> - -<para> -Determines whether worker processes are started. -This directive is intended for nginx developers. -</para> - -</directive> - - -<directive name="pid"> -<syntax>pid <argument>file</argument></syntax> -<default>pid nginx.pid</default> -<context>main</context> - -<para> -Defines a <argument>file</argument> which will store the process ID of the main process. -</para> - -</directive> - - -<directive name="ssl_engine"> -<syntax>ssl_engine <argument>device</argument></syntax> -<default/> -<context>main</context> - -<para> -Defines the name of the hardware SSL accelerator. -</para> - -</directive> - - -<directive name="user"> -<syntax>user <argument>user</argument> [<argument>group</argument>]</syntax> -<default>user nobody nobody</default> -<context>main</context> - -<para> -Defines <argument>user</argument> and <argument>group</argument> -credentials used by worker processes. -If <argument>group</argument> is omitted, a group whose name equals -that of <argument>user</argument> is used. -</para> - -</directive> - - -<directive name="timer_resolution"> -<syntax>timer_resolution <argument>interval</argument></syntax> -<default/> -<context>main</context> - -<para> -Reduces timer resolution in worker processes, thus reducing the -number of <c-func>gettimeofday</c-func> system calls made. -By default, <c-func>gettimeofday</c-func> is called each time -on receiving a kernel event. -With reduced resolution, <c-func>gettimeofday</c-func> is only -called once per specified <argument>interval</argument>. -</para> - -<para> -Example: -<example> -timer_resolution 100ms; -</example> -</para> - -<para> -An internal implementation of interval depends on the method used: -<list type="bullet"> - -<listitem> -an <c-def>EVFILT_TIMER</c-def> filter if <value>kqueue</value> is used; -</listitem> - -<listitem> -<c-func>timer_create</c-func> if <value>eventport</value> is used; -</listitem> - -<listitem> -<c-func>setitimer</c-func> otherwise. -</listitem> - -</list> -</para> - -</directive> - - -<directive name="worker_rlimit_core"> -<syntax>worker_rlimit_core <argument>size</argument></syntax> -<default/> -<context>main</context> - -<para> -Changes the limit on the largest size of a core file -(<c-def>RLIMIT_CORE</c-def>) for worker processes. -Used to increase the limit without restarting the main process. -</para> - -</directive> - - -<directive name="worker_rlimit_nofile"> -<syntax>worker_rlimit_nofile <argument>number</argument></syntax> -<default/> -<context>main</context> - -<para> -Changes the limit on the maximum number of open files -(<c-def>RLIMIT_NOFILE</c-def>) for worker processes. -Used to increase the limit without restarting the main process. -</para> - -</directive> - - -<directive name="worker_priority"> -<syntax>worker_priority <argument>number</argument></syntax> -<default>worker_priority 0</default> -<context>main</context> - -<para> -Defines a scheduling priority for worker processes like is -done by the <command>nice</command> command: a negative -<argument>number</argument> -means higher priority. -Allowed range normally varies from -20 to 20. -</para> - -<para> -Example: -<example> -worker_priority -10; -</example> -</para> - -</directive> - - -<directive name="worker_processes"> -<syntax>worker_processes <argument>number</argument></syntax> -<default>worker_processes 1</default> -<context>main</context> - -<para> -Defines the number of worker processes. -</para> - -</directive> - - -<directive name="working_directory"> -<syntax>working_directory <argument>directory</argument></syntax> -<default/> -<context>main</context> - -<para> -Defines a current working directory for a worker process. -It is primarily used when writing a core-file, in which case -a working process should have write permission for the -specified directory. -</para> - -</directive> - -</section> - -</module>
deleted file mode 100644 --- a/docs/xsls/content.xsls +++ /dev/null @@ -1,67 +0,0 @@ -X:stylesheet { - - X:template = "section[@id and @name]" { - <a name="{@id}" /> <center><h4> !{@name} </h4></center> - !!; - } - - X:template = "section[not(@id) and @name]" { - <center><h4> !{@name} </h4></center> - !!; - } - - X:template = "section[not(@id) and not(@name)]" { !!; } - - X:template = "para" { <p> !!; </p> } - - X:template = "c-def" { <code> !!; </code> } - - X:template = "c-func" { <code> !!; X:text{()} </code> } - - X:template = "code" { <code> !!; </code> } - - X:template = "command" { <code> !!; </code> } - - X:template = "dq" { - X:text disable-output-escaping="yes" {&ldquo;} - !!; - X:text disable-output-escaping="yes" {&rdquo;} - } - - X:template = "example" { <blockquote><pre> !!; </pre></blockquote> } - - X:template = "emphasis" { <strong> !!; </strong> } - - X:template = "header" { <code> !!; </code> } - - X:template = "http-status" { - !{@code} X:text{ (} !{@text} X:text{)} - } - - X:template = "link[@url]" { <a href="{@url}"> !!; </a> } - X:template = "link[@id and not(@doc)]" { <a href="#{@id}"> !!; </a> } - X:template = "link[@doc and not(@id)]" { - <a href="{substring-before(@doc, '.xml')}.html"> !!; </a> - } - X:template = "link[@id and @doc]" { - <a href="{substring-before(@doc, '.xml')}.html#{@id}"> !!; </a> - } - X:template = "link" { <u> !!; </u> } - - X:template = "list[@type='bullet']" { <ul> !!; </ul> } - X:template = "list[@type='enum']" { <ol> !!; </ol> } - X:template = "listitem" { <li> !!; </li> } - - X:template = "list[@type='tag']" { <dl compact=""> !!; </dl> } - X:template = "tag-name" { <dt> !!; </dt> } - X:template = "tag-desc" { <dd> !!; </dd> } - - X:template = "pathname" { <code> !!; </code> } - - X:template = "argument" { <code><i> !!; </i></code> } - X:template = "parameter" { <code> !!; </code> } - - X:template = "value" { <code> !!; </code> } - - X:template = "var" { <code> !!; </code> } -}
deleted file mode 100644 --- a/docs/xsls/directive.xsls +++ /dev/null @@ -1,51 +0,0 @@ -X:stylesheet { - - X:template = "directive" { - <hr/> - <a name="{@name}"/> - <!-- <center><h4> !{@name} </h4></center> --> - !! "syntax"; - !! "default"; - !! "context"; - X:if "(@appeared-in)" { - <strong>appeared in version</strong>: !{@appeared-in} - } - !! "para"; - } - - X:template = "syntax" { - X:if "position() = 1" { - <strong>syntax</strong>: - } else { - <code>       </code> - } - <code> !!; </code> <br/> - } - - X:template = "default" { - <strong>default</strong>: - X:if "count(text()) = 0" { - <strong>none</strong> - } else { - <code> !!; </code> - } - <br/> - } - - X:template = "context" { - X:if "position() = 1" { - <strong>context</strong>: - } - X:if "count(text()) = 0" { - <strong>any</strong> - } else { - <code> !!; </code> - } - X:if "position() != last()" { - X:text{, } - } else { - <br/> - } - } - -}
deleted file mode 100644 --- a/docs/xsls/module.xsls +++ /dev/null @@ -1,34 +0,0 @@ -X:stylesheet { - -X:output method="html" indent="no" encoding="utf-8"; - -X:strip-space elements = "*"; - -<!-- - -- a current directory of a XSLT script is where the script is stored, - -- but not where XSLT processor has been started to run the script - --> -X:param XML = "'../xml'"; - -X:var ID = "/module/@id"; - -X:include href = "directive.xslt"; -X:include href = "content.xslt"; - - -X:template = "/module" { - <html><head> - - <title> !{@name} </title> - - </head> - <body> - - <center><h3> !{@name} </h3></center> - !!; - - </body> - </html> -} - -}
deleted file mode 100644 --- a/docs/xslt/content.xslt +++ /dev/null @@ -1,199 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> - - <xsl:template match="section[@id and @name]"> - - <a name="{@id}"/> - <center> - <h4> - <xsl:value-of select="@name"/> - </h4> - </center> - - <xsl:apply-templates/> - </xsl:template> - - <xsl:template match="section[not(@id) and @name]"> - - <center> - <h4> - <xsl:value-of select="@name"/> - </h4> - </center> - - <xsl:apply-templates/> - </xsl:template> - - <xsl:template match="section[not(@id) and not(@name)]"> - <xsl:apply-templates/> - </xsl:template> - - <xsl:template match="para"> - <p> - <xsl:apply-templates/> - </p> - </xsl:template> - - <xsl:template match="c-def"> - <code> - <xsl:apply-templates/> - </code> - </xsl:template> - - <xsl:template match="c-func"> - <code> - <xsl:apply-templates/> - <xsl:text>()</xsl:text> - </code> - </xsl:template> - - <xsl:template match="code"> - <code> - <xsl:apply-templates/> - </code> - </xsl:template> - - <xsl:template match="command"> - <code> - <xsl:apply-templates/> - </code> - </xsl:template> - - <xsl:template match="dq"> - - <xsl:text disable-output-escaping="yes">&ldquo;</xsl:text> - - <xsl:apply-templates/> - - <xsl:text disable-output-escaping="yes">&rdquo;</xsl:text> - </xsl:template> - - <xsl:template match="example"> - <blockquote> - <pre> - <xsl:apply-templates/> - </pre> - </blockquote> - </xsl:template> - - <xsl:template match="emphasis"> - <strong> - <xsl:apply-templates/> - </strong> - </xsl:template> - - <xsl:template match="header"> - <code> - <xsl:apply-templates/> - </code> - </xsl:template> - - <xsl:template match="http-status"> - - <xsl:value-of select="@code"/> - <xsl:text> (</xsl:text> - <xsl:value-of select="@text"/> - <xsl:text>)</xsl:text> - </xsl:template> - - <xsl:template match="link[@url]"> - <a href="{@url}"> - <xsl:apply-templates/> - </a> - </xsl:template> - - <xsl:template match="link[@id and not(@doc)]"> - <a href="#{@id}"> - <xsl:apply-templates/> - </a> - </xsl:template> - - <xsl:template match="link[@doc and not(@id)]"> - - <a href="{substring-before(@doc, '.xml')}.html"> - <xsl:apply-templates/> - </a> - </xsl:template> - - <xsl:template match="link[@id and @doc]"> - - <a href="{substring-before(@doc, '.xml')}.html#{@id}"> - <xsl:apply-templates/> - </a> - </xsl:template> - - <xsl:template match="link"> - <u> - <xsl:apply-templates/> - </u> - </xsl:template> - - <xsl:template match="list[@type='bullet']"> - <ul> - <xsl:apply-templates/> - </ul> - </xsl:template> - - <xsl:template match="list[@type='enum']"> - <ol> - <xsl:apply-templates/> - </ol> - </xsl:template> - - <xsl:template match="listitem"> - <li> - <xsl:apply-templates/> - </li> - </xsl:template> - - <xsl:template match="list[@type='tag']"> - <dl compact=""> - <xsl:apply-templates/> - </dl> - </xsl:template> - - <xsl:template match="tag-name"> - <dt> - <xsl:apply-templates/> - </dt> - </xsl:template> - - <xsl:template match="tag-desc"> - <dd> - <xsl:apply-templates/> - </dd> - </xsl:template> - - <xsl:template match="pathname"> - <code> - <xsl:apply-templates/> - </code> - </xsl:template> - - <xsl:template match="argument"> - <code> - <i> - <xsl:apply-templates/> - </i> - </code> - </xsl:template> - - <xsl:template match="parameter"> - <code> - <xsl:apply-templates/> - </code> - </xsl:template> - - <xsl:template match="value"> - <code> - <xsl:apply-templates/> - </code> - </xsl:template> - - <xsl:template match="var"> - <code> - <xsl:apply-templates/> - </code> - </xsl:template> - -</xsl:stylesheet>
deleted file mode 100644 --- a/docs/xslt/directive.xslt +++ /dev/null @@ -1,102 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> - - <xsl:template match="directive"> - - <hr/> - - <a name="{@name}"/> - <!-- <center><h4><xsl:value-of select="@name"/> </h4></center> --> - - <xsl:apply-templates select="syntax"/> - - <xsl:apply-templates select="default"/> - - <xsl:apply-templates select="context"/> - - <xsl:if test="(@appeared-in)"> - - <strong>appeared in version</strong>: - <xsl:value-of select="@appeared-in"/> - </xsl:if> - - <xsl:apply-templates select="para"/> - </xsl:template> - - <xsl:template match="syntax"> - <xsl:choose> - - <xsl:when test="position() = 1"> - - <strong>syntax</strong>: - </xsl:when> - - <xsl:otherwise> - - <code> </code> - </xsl:otherwise> - </xsl:choose> - - <code> - - <xsl:apply-templates/> - </code> - <br/> - </xsl:template> - - <xsl:template match="default"> - - <strong>default</strong>: - <xsl:choose> - - <xsl:when test="count(text()) = 0"> - - <strong>none</strong> - </xsl:when> - - <xsl:otherwise> - - <code> - <xsl:apply-templates/> - </code> - </xsl:otherwise> - </xsl:choose> - - <br/> - </xsl:template> - - <xsl:template match="context"> - - <xsl:if test="position() = 1"> - - <strong>context</strong>: - </xsl:if> - <xsl:choose> - - <xsl:when test="count(text()) = 0"> - - <strong>any</strong> - </xsl:when> - - <xsl:otherwise> - - <code> - <xsl:apply-templates/> - </code> - </xsl:otherwise> - </xsl:choose> - <xsl:choose> - - <xsl:when test="position() != last()"> - - <xsl:text>, </xsl:text> - </xsl:when> - - <xsl:otherwise> - - <br/> - </xsl:otherwise> - </xsl:choose> - </xsl:template> - -</xsl:stylesheet>
deleted file mode 100644 --- a/docs/xslt/module.xslt +++ /dev/null @@ -1,42 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> - - <xsl:output indent="no" encoding="utf-8" method="html"/> - - <xsl:strip-space elements="*"/> - - <xsl:param select="'../xml'" name="XML"/> - - <xsl:variable select="/module/@id" name="ID"/> - - <xsl:include href="directive.xslt"/> - - <xsl:include href="content.xslt"/> - - <xsl:template match="/module"> - - <html> - <head> - - <title> - <xsl:value-of select="@name"/> - </title> - - </head> - - <body> - - <center> - <h3> - <xsl:value-of select="@name"/> - </h3> - </center> - - <xsl:apply-templates/> - - </body> - - </html> - </xsl:template> - -</xsl:stylesheet>