Mercurial > hg > nginx
changeset 4068:22364b1f61c9
Initial English translation of Core and HTTP Core modules.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Mon, 05 Sep 2011 09:39:24 +0000 |
parents | da811964e37c |
children | 4dbdfd985863 |
files | docs/GNUmakefile docs/xml/http/ngx_http_core_module.xml docs/xml/ngx_core_module.xml |
diffstat | 3 files changed, 2164 insertions(+), 13 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/GNUmakefile +++ b/docs/GNUmakefile @@ -24,6 +24,8 @@ define XSLT endef +all: changes html + changes: $(TEMP)/$(NGINX)/CHANGES.ru \ $(TEMP)/$(NGINX)/CHANGES @@ -55,8 +57,15 @@ docs/xslt/changes.xslt: docs/xsls/chang $(call XSLScript, docs/xsls/changes.xsls, $@) html: \ + docs/html/ngx_core_module.html \ docs/html/http/ngx_http_core_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 \
--- a/docs/xml/http/ngx_http_core_module.xml +++ b/docs/xml/http/ngx_http_core_module.xml @@ -1,22 +1,255 @@ +<?xml version="1.0"?> + <!DOCTYPE module SYSTEM "../../dtd/module.dtd"> -<module title="ngx_http_core_module" - link="/en/docs/http/ngx_http_core_module.html" - lang="en"> +<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 used 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's 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> +<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> -<section title="Directives"> +<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 tail 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 "/i/top.gif" will be responded +with the file "/data/w3/images/top.gif". +</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's 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 +<link doc="ngx_http_perl_module.xml">http_perl</link> module. +</para> + +<para> +When set to the value <code>on</code>, temporary files are not +removed after request processing. +</para> + +<para> +The value <code>clean</code> 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 <value>size</value></syntax> +<syntax>client_body_buffer_size <argument>size</argument></syntax> <default>client_body_buffer_size 8k/16k</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Directive sets client request body buffer size. -If the request body is larger than the buffer, -then the whole body or some its part is written to temporary file. -By default buffer size is equal to 2 memory page sizes. +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> @@ -24,14 +257,1630 @@ It is usually 16K on other 64-bit platfo </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 error +<http-error 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 line 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 error +<http-error 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 line. +If <argument>size</argument> is greater than the configured value, the +<http-error code="413" text="Request Entity Too Large"/> +error is returned to a client. +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 usage: +<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="bullet"> + +<listitem> +<value>off</value>—the +<header>If-Modified-Since</header> request header is ignored (0.7.34); +</listitem> + +<listitem> +<value>exact</value>—exact match; +</listitem> + +<listitem> +<value>before</value>—modification time of a response is +less than or equal to the time in the <header>If-Modified-Since</header> +request header. +</listitem> + +</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 <http-error code="404" text="Not found"/> +error 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 +<link doc="ngx_http_ssi_module.xml">http_ssi</link> module; +</listitem> + +<listitem> +requests changed by the +<link doc="ngx_http_rewrite_module.xml" id="rewrite">rewrite</link> +directive of the +<link doc="ngx_http_rewrite_module.xml">http_rewrite</link> module. +</listitem> + +</list> +</para> + +<para> +Example usage: +<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 +"<header>Keep-Alive: timeout=</header><argument>time</argument>" +response header. +Two arguments may differ. +</para> + +<para> +The +"<header>Keep-Alive: timeout=</header>" +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 +<http-error code="414" text="Request URI too large"/> +error is returned. +A request header line cannot exceed the size of one buffer as well, or the +<http-error code="400" text="Bad request"/> +error 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">http_access</link> +and +<link doc="ngx_http_auth_basic_module.xml">http_auth_basic</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="bullet"> + +<listitem> +<parameter>backlog</parameter>=<argument>number</argument>— +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. +</listitem> + +<listitem> +<parameter>rcvbuf</parameter>=<argument>size</argument>— +sets the <c-def>SO_RCVBUF</c-def> parameter for the listening socket. +</listitem> + +<listitem> +<parameter>sndbuf</parameter>=<argument>size</argument>— +sets the <c-def>SO_SNDBUF</c-def> parameter for the listening socket. +</listitem> + +<listitem> +<parameter>accept_filter</parameter>=<argument>filter</argument>— +sets the name of the accept filter. +This works only on FreeBSD, acceptable values are <value>dataready</value> +and <value>httpready</value>. +On receiving <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. +</listitem> + +<listitem> +<parameter>deferred</parameter>— +instructs to use a deferred <c-func>accept</c-func> on Linux +using the <c-def>TCP_DEFER_ACCEPT</c-def> option. +</listitem> + +<listitem> +<parameter>bind</parameter>— +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 and 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. +</listitem> + +<listitem> +<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>— +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. +</listitem> + +<listitem> +<parameter>ssl</parameter>— +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> +</listitem> + +</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 +"<value>~*</value>" prefix (for case-insensitive matching), or with the +"<value>~</value>" 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 "<value>^~</value>" prefix +then regular expressions are not checked. +</para> + +<para> +Also, using the "<value>=</value>" prefix it's 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. +</para> + +<para> +In versions from 0.7.1 to 0.8.41, if a request matched the prefix +location without the "<value>=</value>" and "<value>^~</value>" +prefixes, the search also terminated and regular expressions were +not checked. +</para> + +<para> +Let's illustrate the above by an example: +<example> +location = / { + [ configuration A ] +} + +location / { + [ configuration B ] +} + +location ^~ /images/ { + [ configuration C ] +} + +location ~* \.(gif|jpg|jpeg)$ { + [ configuration D ] +} +</example> +The "<code>/</code>" request will match configuration A, +the "<code>/documents/document.html</code>" request—configuration B, +the "<code>/images/1.gif</code>" request—configuration C, and +the "<code>/documents/1.jpg</code>" request—configuration D. +</para> + +<para> +The "<code>@</code>" prefix defines a named location. +Such a location isn't 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 "<code>//scripts/one.php</code>" request would not match +<example> +location /scripts/ { + ... +} +</example> +and might be processed as a static file, +so it gets converted to "<code>/scripts/one.php</code>". +</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's 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="bullet"> + +<listitem> +<parameter>max</parameter>— +sets the maximum number of elements in the cache; +on cache overflow the least recently used (LRU) elements get removed; +</listitem> + +<listitem> +<parameter>inactive</parameter>— +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; +</listitem> + +<listitem> +<value>off</value>—disables the cache. +</listitem> + +</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 doc="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> +the request of "/i/top.gif" will be responded +with the file "/data/w3/images/top.gif". +</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">http_access</link> +or <link doc="ngx_http_auth_basic_module.xml">http_auth_basic</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|off]</value></syntax> +<syntax>sendfile <value>on</value> | <value>off</value></syntax> <default>sendfile off</default> -<context>http, server, location</context> +<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> header string) +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="/docs/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 ("<code>*</code>") +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 ("<code>~</code>"): +<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—*.example.com +</listitem> + +<listitem> +names with the suffix mask—mail.* +</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 string +is used. +If there's no such a string, 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> -Directive enables or disables sendfile() usage. +Sets the maximum <argument>size</argument> of the server names hash tables. +For more information, please refer to +<link doc="/docs/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="/docs/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 string. +</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 ... 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. "<code>$uri/</code>". +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>
new file mode 100644 --- /dev/null +++ b/docs/xml/ngx_core_module.xml @@ -0,0 +1,293 @@ +<?xml version="1.0"?> + +<!DOCTYPE module SYSTEM "../dtd/module.dtd"> + +<module name="Core Module" id="core_module"> + +<section name="Example Configuration" id="example"> + +<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 name="Directives" id="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 +<link doc="http/ngx_http_perl_module.xml">http_perl</link> +module; +</listitem> + +<listitem> +use of variables by worker processes. +Please bear in mind that controlling system libraries in this way +isn't always possible as it's 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 +<link doc="http/ngx_http_perl_module.xml">http_perl</link> +module, 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 <code>kqueue</code> is used; +</listitem> + +<listitem> +<c-func>timer_create</c-func> if <code>eventport</code> 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>: 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's primarily used for writing a core-file, in which case +a working process should have write permission for the +specified directory. +</para> + +</directive> + +</section> + +</module>