| <?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 <command>alias</command> is used inside a location defined |
| with a regular expression then such regular expression should |
| contain captures and <command>alias</command> 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 |
| <command>error_page</command> |
| 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 <command>root</command> 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 <command>try_files</command> 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> |
| <command>try_files</command> 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 <command>listen</command> 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> |