nginx-site: xml/en/docs/http/ngx_http_core

comparison xml/en/docs/http/ngx_http_core_module.xml @ 958:fd1f8e0a405e

Text review of ngx_http_core_module.

author	Egor Nikitin <yegor.nikitin@gmail.com>
date	Tue, 06 Aug 2013 17:03:33 +0400
parents	7d1d53d4d293
children	95c3c3bbf1ce

comparison

equal deleted inserted replaced

-:6d9d4bb571a9
+:fd1f8e0a405e
 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&nbsp;4.3.
+On FreeBSD, AIO can be used starting from FreeBSD&nbsp;4.3.
 AIO can either be linked statically into a kernel:
 <example>
 options VFS_AIO
 </example>
 or loaded dynamically as a kernel loadable module:
 </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.
+to use the Giant lock, which can impact overall performance negatively.
 This limitation has been removed in FreeBSD&nbsp;6.4-STABLE in 2009, and in
 FreeBSD&nbsp;7.
 However, starting from FreeBSD&nbsp;5.3 it is possible to enable AIO
 without the penalty of running the networking subsystem under a
 Giant lock&mdash;for this to work, the AIO module needs to be loaded
 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.
+However, since nginx uses AIO only for disk I/O, no problems should arise.
 </note>
 </para>
 <para>
 For AIO to work,
 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
+the <c-def>SF_NODISKIO</c-def> flag which causes it not to block on disk I/O,
-block on disk I/O and instead report back when the data are not in
+but, instead, report back that the data are not in memory.
-memory; nginx then initiates an asynchronous data load by reading
+nginx then initiates an asynchronous data load by reading one byte.
-one byte.
+On the first read, the FreeBSD kernel loads the first 128K bytes
-The FreeBSD kernel then loads the first 128K bytes
+of a file into memory, although next reads will only load data in 16K chunks.
-of a file into memory, however next reads will only load data
+This can be changed using the
-in 16K chunks.
+<link id="read_ahead"/> directive.
-This can be tuned using the
+</para>
-<link id="read_ahead"/>
-directive.
+<para>
-</para>
+On Linux, AIO can be used starting from kernel version 2.6.22.
+Also, it is necessary to enable
-<para>
-On Linux, AIO is usable starting from kernel version 2.6.22;
-plus, it is also necessary to enable
 <link id="directio"/>,
-otherwise reading will be blocking:
+or otherwise reading will be blocking:
 <example>
 location /video/ {
 aio            on;
 directio       512;
 output_buffers 1 128k;
 <para>
 On Linux,
 <link id="directio"/>
 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.
+File’s unaligned end is read in blocking mode.
-The same holds true for byte range requests, and for FLV requests
+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"/>
-explicitly as it is turned off automatically when
+explicitly, as it is turned off automatically when
 <link id="directio"/>
 is used.
 </para>
 </directive>
 <example>
 location /i/ {
 alias /data/w3/images/;
 }
 </example>
-the request of
+on request of
-“<literal>/i/top.gif</literal>” will be responded
+“<literal>/i/top.gif</literal>”, the file
-with the file
+<path>/data/w3/images/top.gif</path> will be sent.
-<path>/data/w3/images/top.gif</path>.
+</para>
-</para>
+<para>
-<para>
+The <value>path</value> value can contain variables,
-The <value>path</value> value can contain variables
 except <var>$document_root</var> and <var>$realpath_root</var>.
 </para>
 <para>
 If <literal>alias</literal> is used inside a location defined
 <context>location</context>
 <para>
 Allows disabling chunked transfer encoding in HTTP/1.1.
 It may come in handy when using a software failing to support
-chunked encoding though the standard requires it.
+chunked encoding despite the standard’s requirement.
 </para>
 </directive>
 <context>server</context>
 <context>location</context>
 <para>
 Sets buffer size for reading client request body.
-In case request body is larger than the buffer,
+In case the request body is larger than the buffer,
 the whole body or only its part is written to a
 <link id="client_body_temp_path">temporary file</link>.
 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.
 <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
+Up to three-level subdirectory hierarchy can be used under 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:
+a path to a temporary file might look like this:
 <example>
 /spool/nginx/client_temp/7/45/00000123457
 </example>
 </para>
 <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,
+The timeout is only set for a period between two successive read operations,
 not for the transmission of the whole request body.
-If a client does not transmit anything within this time,
+If a client does not transmit anything within this time, the
-the client error
 <http-status code="408" text="Request Time-out"/>
-is returned.
+error is returned to the client.
 </para>
 </directive>
 <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
+If a request line or a request header field does not fit into
-this buffer then larger buffers are allocated, configured by the
+this buffer then larger buffers, configured by the
-<link id="large_client_header_buffers"/>
+<link id="large_client_header_buffers"/> directive,
-directive.
+are allocated.
 </para>
 </directive>
 <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,
+If a client does not transmit the entire header within this time, the
-the client error
 <http-status code="408" text="Request Time-out"/>
-is returned.
+error is returned to the client.
 </para>
 </directive>
 <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
+If the size in a request exceeds the configured value, the
 <http-status code="413" text="Request Entity Too Large"/>
-is returned.
+error is returned to the client.
 Please be aware that
 <!--link doc="/web/upload.xml"-->browsers cannot correctly display
 this error<!--/link-->.
-Setting <value>size</value> to 0 disables client
+Setting <value>size</value> to 0 disables checking of client
-request body size checking.
+request body size.
 </para>
 </directive>
 <default>256</default>
 <context>http</context>
 <context>server</context>
 <para>
-Allows to fine tune per-connection memory allocations.
+Allows accurate tuning of per-connection memory allocations.
-This directive has minimal impact on performance,
+This directive has minimal impact on performance
 and should not generally be used.
 </para>
 </directive>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 <para>
-Defines a default MIME-type of a response.
+Defines the default MIME-type of a response.
 Mapping of file name extensions to MIME types can be set
 with the <link id="types"/> directive.
 </para>
 </directive>
 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 or equal to
 the specified <value>size</value>.
-It automatically disables (0.7.15) the use of
+The directive automatically disables (0.7.15) the use of
 <link id="sendfile"/>
 for a given request.
-It could be useful for serving large files:
+It can be useful for serving large files:
 <example>
 directio 4m;
 </example>
 or when using <link id="aio"/> on Linux.
 </para>
 <context>server</context>
 <context>location</context>
 <appeared-in>0.8.11</appeared-in>
 <para>
-Sets an alignment for
+Sets the alignment for
 <link id="directio"/>.
-In most cases, a 512-byte alignment is enough, however, when
+In most cases, a 512-byte alignment is enough.
-using XFS under Linux, it needs to be increased to 4K.
+However, when using XFS under Linux, it needs to be increased to 4K.
 </para>
 </directive>
 <tag-desc>
 When checking symbolic links
 (parameters <literal>on</literal> and <literal>if_not_owner</literal>),
 all components of the pathname are normally checked.
 Checking of symbolic links in the initial part of the pathname
-may be avoided by also specifying the
+may be avoided by specifying additionally the
 <literal>from</literal>=<value>part</value> parameter.
 In this case, symbolic links are checked only from
-the component of the pathname following the specified initial part.
+the pathname component that follows the specified initial part.
-If a value is not an initial part of the checked pathname, the whole
+If the value is not an initial part of the pathname checked, the whole
 pathname is checked as if this parameter was not specified at all.
-If a value fully matches the file name,
+If the value matches the whole file name,
 symbolic links are not checked.
 The parameter value can contain variables.
 </tag-desc>
 </list>
 </para>
 <para>
 This directive is only available on systems that have the
 <c-func>openat</c-func> and <c-func>fstatat</c-func> interfaces.
-This includes modern versions of FreeBSD, Linux, and Solaris.
+Such systems include modern versions of FreeBSD, Linux, and Solaris.
 </para>
 <para>
 Parameters <literal>on</literal> and <literal>if_not_owner</literal>
 add a processing overhead.
 <note>
-On systems that do not support opening directories for search only,
+On systems that do not support opening of directories only for search,
-the use of these parameters requires that worker processes
+to use these parameters it is required that worker processes
-have read permissions for all checked directories.
+have read permissions for all directories being checked.
 </note>
 </para>
 <para>
 <note>
 <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
+<literal>error_page</literal> directives are inherited from the previous
-only if there are no
+level only if there are no <literal>error_page</literal>
-<literal>error_page</literal>
+directives defined on the current level.
-directives on
-the current level.
 A <literal>uri</literal> value can contain variables.
 </para>
 <para>
 Example:
 error_page 404 =200 /empty.gif;
 </example>
 </para>
 <para>
-If an error response is processed by a proxied server, or a FastCGI server,
+If an error response is processed by a proxied server or a FastCGI server,
 and the server may return different response codes (e.g., 200, 302, 401
-or 404), it is possible to respond with a returned code:
+or 404), it is possible to respond with the code it returns:
 <example>
 error_page 404 = /404.php;
 </example>
 </para>
 directive).
 </para>
 <para>
 A directive can be specified on the <link id="server"/> level
-in a default server.
+in the default server.
 In this case, its value will cover all virtual servers
 listening on the same address and port.
 </para>
 </directive>
 <para>
 Disables keep-alive connections with misbehaving browsers.
 The <value>browser</value> parameters specify which
 browsers will be affected.
 The value <literal>msie6</literal> disables keep-alive connections
-with old versions of MSIE, after seeing a POST request.
+with old versions of MSIE, once a POST request is received.
 The value <literal>safari</literal> disables keep-alive connections
 with Safari and Safari-like browsers on Mac OS X and Mac OS X-like
 operating systems.
 The value <literal>none</literal> enables keep-alive connections
 with all browsers.
 <context>location</context>
 <appeared-in>0.8.0</appeared-in>
 <para>
 Sets the maximum number of requests that can be
-made through one keep-alive connection.
+served through one keep-alive connection.
-After this many requests are made, the connection is closed.
+After the maximum number of requests are made, the connection is closed.
 </para>
 </directive>
 <context>location</context>
 <para>
 The first parameter sets a timeout during which a keep-alive
 client connection will stay open on the server side.
-The value of zero disables keep-alive client connections.
+The zero value disables keep-alive client connections.
 The optional second parameter sets a value in the
 <header>Keep-Alive: timeout=<value>time</value></header>
 response header field.
 Two parameters may differ.
 </para>
 <para>
 The
 <header>Keep-Alive: timeout=<value>time</value></header>
-header field is understood by Mozilla and Konqueror.
+header field is recognized by Mozilla and Konqueror.
-MSIE will close keep-alive connection in about 60 seconds.
+MSIE closes keep-alive connections by itself in about 60 seconds.
 </para>
 </directive>
 <context>http</context>
 <context>server</context>
 <para>
 Sets the maximum <value>number</value> and <value>size</value> of
-buffers used when reading large client request header.
+buffers used for reading large client request header.
-A request line cannot exceed the size of one buffer, or the client error
+A request line cannot exceed the size of one buffer, or the
 <http-status code="414" text="Request-URI Too Large"/>
-is returned.
+error is returned to the client.
 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.
+error is returned to the client.
 Buffers are allocated only on demand.
 By default, the buffer size is equal to 8K bytes.
 If after the end of request processing a connection is transitioned
-into the keep-alive state, these buffers are freed.
+into the keep-alive state, these buffers are released.
 </para>
 </directive>
 <literal>PROPPATCH</literal>,
 <literal>LOCK</literal>,
 <literal>UNLOCK</literal>,
 or
 <literal>PATCH</literal>.
-Allowing the <literal>GET</literal> method also allows the
+Allowing the <literal>GET</literal> method makes the
-<literal>HEAD</literal> method.
+<literal>HEAD</literal> method also allowed.
 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:
 <context>server</context>
 <context>location</context>
 <context>if in location</context>
 <para>
-Rate limits the transmission of a response to a client.
+Limits the rate of response transmission to a client.
 The <value>rate</value> is specified in bytes per second.
 The value 0 disables rate limiting.
 <!--
 The smaller the rate, the more accurate will be the limitation.
 -->
-The limit is set per request, so if a client simultaneously opens
+The limit is set per a request, and so if a client simultaneously opens
-two connections, an overall rate will be twice as much
+two connections, the overall rate will be twice as much
 as the specified limit.
 </para>
 <para>
 Rate limit can also be set in the <var>$limit_rate</var> variable.
 }
 </example>
 </para>
 <para>
-In addition, rate limit can also be set in the
+Rate limit can also be set in the
 <header>X-Accel-Limit-Rate</header> header field of a proxied server response.
-This ability can be disabled using the
+This capability can be disabled using the
 <link doc="ngx_http_proxy_module.xml" id="proxy_ignore_headers"/>
 and
 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_ignore_headers"/>
 directives.
 </para>
 </para>
 <para>
 The value “<literal>off</literal>” tells nginx to never wait for
 more data and close the connection immediately.
-This breaks the protocol and should not be used under normal circumstances.
+This behavior breaks the protocol and should not be used under normal
+circumstances.
 </para>
 </directive>
 <context>server</context>
 <context>location</context>
 <para>
 When <link id="lingering_close"/> is in effect,
-this directive specifies a maximum time during which nginx
+this directive specifies the maximum time during which nginx
 will process (read and ignore) additional data coming from a client.
-After that, the connection is closed, even if there are more data.
+After that, the connection will be closed, even if there will be
+more data.
 </para>
 </directive>
 <context>server</context>
 <context>location</context>
 <para>
 When <link id="lingering_close"/> is in effect, this directive specifies
-a maximum waiting time for more client data to arrive.
+the maximum waiting time for more client data to arrive.
 If data are not received during this time, the connection is closed.
-Otherwise, data are read and ignored, then nginx waits again for more data.
+Otherwise, the data are read and ignored, and nginx starts waiting
+for more data again.
 The “wait-read-ignore” cycle is repeated, but no longer than specified by the
 <link id="lingering_time"/> directive.
 </para>
 </directive>
 <default>*:80 | *:8000</default>
 <context>server</context>
 <para>
 Sets an <value>address</value> and a <value>port</value> for IP,
-or a <value>path</value> for a UNIX-domain socket, on which
+or a <value>path</value> for a UNIX-domain socket on which
 the server will accept requests.
-Only one of <value>address</value> or <value>port</value> may be
+Both <value>address</value> and <value>port</value>,
-specified.
+or only <value>address</value> or only <value>port</value> can be specified.
 An <value>address</value> may also be a hostname, for example:
 <example>
 listen 127.0.0.1:8000;
 listen 127.0.0.1;
 listen 8000;
 <para>
 If only <value>address</value> is given, the port 80 is used.
 </para>
 <para>
-If directive is not present then either the <literal>*:80</literal> is used
+If the directive is not present then either <literal>*:80</literal> is used
-if nginx runs with superuser privileges, or <literal>*:8000</literal> otherwise.
+if nginx runs with the superuser privileges, or <literal>*:8000</literal>
+otherwise.
 </para>
 <para>
 The <literal>default_server</literal> parameter, if present,
 will cause the server to become the default server for the specified
 <literal>default</literal>.
 </note>
 </para>
 <para>
-The <literal>ssl</literal> parameter (0.7.14) allows to specify that all
+The <literal>ssl</literal> parameter (0.7.14) allows specifying that all
 connections accepted on this port should work in SSL mode.
 This allows for a more compact <link doc="configuring_https_servers.xml"
 id="single_http_https_server">configuration</link> for the server that
 handles both HTTP and HTTPS requests.
 </para>
 <para>
-The <literal>spdy</literal> parameter (1.3.15) allows to accept
+The <literal>spdy</literal> parameter (1.3.15) allows accepting
 <link doc="ngx_http_spdy_module.xml">SPDY</link> connections on this port.
 Normally, for this to work the <literal>ssl</literal> parameter should be
 specified as well, but nginx can also be configured to accept SPDY
 connections without SSL.
 </para>
 <para>
 A <literal>listen</literal> directive
 can have several additional parameters specific to socket-related system calls.
-They can be specified in any
+These parameters can be specified in any
-<literal>listen</literal> directive, but only once for the given
+<literal>listen</literal> directive, but only once for a given
 <value>address</value>:<value>port</value> pair.
 <note>
 In versions prior to 0.8.21, they could only be
-specified in the <literal>listen</literal> directive along with the
+specified in the <literal>listen</literal> directive together with the
 <literal>default</literal> parameter.
 </note>
 <list type="tag">
 <tag-name>
 <literal>setfib</literal>=<value>number</value>
 </tag-name>
 <tag-desc>
-this parameter (0.8.44) sets an associated routing table, FIB
+this parameter (0.8.44) sets the associated routing table, FIB
 (the <c-def>SO_SETFIB</c-def> option) for the listening socket.
 This currently works only on FreeBSD.
 </tag-desc>
 <tag-name>
 <tag-name>
 <literal>rcvbuf</literal>=<value>size</value>
 </tag-name>
 <tag-desc>
-sets receive buffer size
+sets the receive buffer size
 (the <c-def>SO_RCVBUF</c-def> option) for the listening socket.
 </tag-desc>
 <tag-name>
 <literal>sndbuf</literal>=<value>size</value>
 </tag-name>
 <tag-desc>
-sets send buffer size
+sets the send buffer size
 (the <c-def>SO_SNDBUF</c-def> option) for the listening socket.
 </tag-desc>
 <tag-name>
 <literal>accept_filter</literal>=<value>filter</value>
 </tag-name>
 <tag-desc>
 sets the name of accept filter
 (the <c-def>SO_ACCEPTFILTER</c-def> option) for the listening socket
-that filters incoming connections before presenting them to
+that filters incoming connections before passing them to
 <c-func>accept</c-func>.
 This works only on FreeBSD and NetBSD 5.0+.
-Acceptable values are
+Possible values are
 <link url="http://man.freebsd.org/accf_data">dataready</link>
 and
 <link url="http://man.freebsd.org/accf_http">httpready</link>.
 </tag-desc>
 <literal>bind</literal>
 </tag-name>
 <tag-desc>
 instructs to make a separate <c-func>bind</c-func> call for a given
 <value>address</value>:<value>port</value> pair.
-This is because nginx will <c-func>bind</c-func> only to
+This is useful because if there are several <literal>listen</literal>
-<literal>*:</literal><value>port</value>
+directives with the same port but different addresses, and one of the
-if there are several <literal>listen</literal> directives with
-the same port but different addresses, and one of the
 <literal>listen</literal> directives listens on all addresses
-for the given port (<literal>*:</literal><value>port</value>).
+for the given port (<literal>*:</literal><value>port</value>), nginx
-It should be noted that in this case a <c-func>getsockname</c-func>
+will <c-func>bind</c-func> only to <literal>*:</literal><value>port</value>.
-system call will be made to determine an address that accepted a
+It should be noted that in this case the address that accepted the
-connection.
+connection is determined by a <c-func>getsockname</c-func> system call.
-If parameters <literal>backlog</literal>, <literal>rcvbuf</literal>,
+If the <literal>backlog</literal>, <literal>rcvbuf</literal>,
 <literal>sndbuf</literal>, <literal>accept_filter</literal>,
-<literal>deferred</literal>, or <literal>so_keepalive</literal>
+<literal>deferred</literal>, or <literal>so_keepalive</literal> parameters
 are used then for a given
 <value>address</value>:<value>port</value> pair
 a separate <c-func>bind</c-func> call will always be made.
 </tag-desc>
 <literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>
 </tag-name>
 <tag-desc>
 this parameter (0.7.42) determines
 (via the <c-def>IPV6_V6ONLY</c-def> socket option)
-whether IPv6 socket listening on a wildcard address <literal>[::]</literal>
+whether an IPv6 socket listening on a wildcard address <literal>[::]</literal>
-will accept only IPv6 connections, or both IPv6 and IPv4 connections.
+will accept only IPv6 connections or both IPv6 and IPv4 connections.
 This parameter is turned on by default.
 It can only be set once on start.
 <note>
 Prior to version 1.3.4,
 if this parameter was omitted then the operating system’s settings were
 <tag-desc>
 this parameter (1.1.11) configures the “TCP keepalive” behavior
 for the listening socket.
 If this parameter is omitted then the operating system’s settings will be
 in effect for the socket.
-If set to the value “<literal>on</literal>”, the <c-def>SO_KEEPALIVE</c-def>
+If it is set to the value “<literal>on</literal>”, the
-socket option is turned on for the socket.
+<c-def>SO_KEEPALIVE</c-def> option is turned on for the socket.
-If set to the value “<literal>off</literal>”, the <c-def>SO_KEEPALIVE</c-def>
+If it is set to the value “<literal>off</literal>”, the
-socket option is turned off for the socket.
+<c-def>SO_KEEPALIVE</c-def> option is turned off for the socket.
-Some operating systems support tuning TCP keepalive parameters on a per-socket
+Some operating systems support setting of TCP keepalive parameters on
-basis using the <c-def>TCP_KEEPIDLE</c-def>, <c-def>TCP_KEEPINTVL</c-def>,
+a per-socket basis using the <c-def>TCP_KEEPIDLE</c-def>,
-and <c-def>TCP_KEEPCNT</c-def> socket options.
+<c-def>TCP_KEEPINTVL</c-def>, and <c-def>TCP_KEEPCNT</c-def> socket options.
 On such systems (currently, Linux 2.4+, NetBSD 5+, and
-FreeBSD 9.0-STABLE) they can be configured
+FreeBSD 9.0-STABLE), they can be configured
 using the <value>keepidle</value>, <value>keepintvl</value>, and
 <value>keepcnt</value> parameters.
 One or two parameters may be omitted, in which case the system default setting
 for the corresponding socket option will be in effect.
 For example,
 <example>so_keepalive=30m::10</example>
-will set idle timeout (<c-def>TCP_KEEPIDLE</c-def>) to 30 minutes,
+will set the idle timeout (<c-def>TCP_KEEPIDLE</c-def>) to 30 minutes,
-leave probe interval (<c-def>TCP_KEEPINTVL</c-def>) at its system default,
+leave the probe interval (<c-def>TCP_KEEPINTVL</c-def>) at its system default,
-and set probes count (<c-def>TCP_KEEPCNT</c-def>) to 10 probes.
+and set the probes count (<c-def>TCP_KEEPCNT</c-def>) to 10 probes.
 </tag-desc>
 </list>
 </para>
 <default/>
 <context>server</context>
 <context>location</context>
 <para>
-Sets a configuration based on a request URI.
+Sets configuration depending on a request URI.
 </para>
 <para>
 The matching is performed against a normalized URI,
-after decoding a text encoded in the “<literal>%XX</literal>” form,
+after decoding the text encoded in the “<literal>%XX</literal>” form,
 resolving references to relative path components “<literal>.</literal>”
 and “<literal>..</literal>”, and possible
 <link id="merge_slashes">compression</link> of two or more
 adjacent slashes into a single slash.
 </para>
 <para>
 A location can either be defined by a prefix string, or by a regular expression.
-Regular expressions are specified by prepending them with the
+Regular expressions are specified with the preceding
-“<literal>~*</literal>” modifier (for case-insensitive matching), or with the
+“<literal>~*</literal>” modifier (for case-insensitive matching), or the
 “<literal>~</literal>” modifier (for case-sensitive matching).
-To find a location matching a given request, nginx first checks
+To find location matching a given request, nginx first checks
 locations defined using the prefix strings (prefix locations).
-Among them, the most specific one is searched.
+Among them, the location with the longest matching
+prefix is selected and remembered.
 Then regular expressions are checked, in the order of their appearance
-in a configuration file.
+in the configuration file.
-A search of regular expressions terminates on the first match,
+The search of regular expressions terminates on the first match,
 and the corresponding configuration is used.
-If no match with a regular expression is found then a
+If no match with a regular expression is found then the
-configuration of the most specific prefix location is used.
+configuration of the prefix location remembered earlier is used.
 </para>
 <para>
-Locations can be nested, with some exceptions mentioned below.
+<literal>location</literal> blocks can be nested, with some exceptions
+mentioned below.
 </para>
 <para>
 For case-insensitive operating systems such as Mac OS X and Cygwin,
 matching with prefix strings ignores a case (0.7.7).
 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 “<literal>^~</literal>” modifier
+If the longest matching prefix location has the “<literal>^~</literal>” modifier
 then regular expressions are not checked.
 </para>
 <para>
 Also, using the “<literal>=</literal>” modifier it is possible to define
 not checked.
 </note>
 </para>
 <para>
-Let’s illustrate the above by example:
+Let’s illustrate the above by an example:
 <example>
 location = / {
 [ configuration A ]
 }
 <link doc="ngx_http_memcached_module.xml" id="memcached_pass"/>,
 then in response to a request with URI equal to this string,
 but without the trailing slash,
 a permanent redirect with the code 301 will be returned to the requested URI
 with the slash appended.
-If this is undesired, an exact match of the URI and location could be
+If this is not desired, an exact match of the URI and location could be
 defined like this:
 <example>
 location /user/ {
 proxy_pass http://user.example.com;
 }
 <context>http</context>
 <context>server</context>
 <context>location</context>
 <para>
-Enables or disables logging of errors about not found files into the
+Enables or disables logging of errors about not found files into
 <link doc="../ngx_core_module.xml" id="error_log"/>.
 </para>
 </directive>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 <para>
-Enables or disables logging of subrequests into the
+Enables or disables logging of subrequests into
 <link doc="ngx_http_log_module.xml" id="access_log"/>.
 </para>
 </directive>
 <para>
 Limits the maximum allowed number of ranges in byte-range requests.
 Requests that exceed the limit are processed as if there were no
 byte ranges specified.
-By default, there is no limit.
+By default, the number of ranges is not limited.
-The value of zero disables the byte-range support completely.
+The zero value disables the byte-range support completely.
 </para>
 </directive>
 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
+Note that compression is essential for the correct matching of prefix string
-and regular expressions location matching.
+and regular expression locations.
 Without it, the “<literal>//scripts/one.php</literal>” request would not match
 <example>
 location /scripts/ {
 ...
 }
 </example>
-and might be processed as a static file,
+and might be processed as a static file.
-so it gets converted to “<literal>/scripts/one.php</literal>”.
+So it gets converted to “<literal>/scripts/one.php</literal>”.
 </para>
 <para>
 Turning the compression <literal>off</literal> can become necessary if a URI
 contains base64-encoded names, since base64 uses the “<literal>/</literal>”
 character internally.
-However, for security considerations, it is better to avoid turning off
+However, for security considerations, it is better to avoid turning
-the compression.
+the compression off.
 </para>
 <para>
 A directive can be specified on the <link id="server"/> level
-in a default server.
+in the default server.
-In this case, its value will cover all virtual servers
+In this case, its value will apply to all virtual servers
 listening on the same address and port.
 </para>
 </directive>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 <para>
-Enables or disables adding of comments to responses with status
+Enables or disables adding comments to responses for MSIE clients with status
-greater than 400 for MSIE clients, to pad the response size to 512 bytes.
+greater than 400 to increase the response size to 512 bytes.
 </para>
 </directive>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 <para>
-Enables or disables issuing refreshes instead of redirects, for MSIE clients.
+Enables or disables issuing refreshes instead of redirects for MSIE clients.
 </para>
 </directive>
 <listitem>
 open file descriptors, their sizes and modification times;
 </listitem>
 <listitem>
-directory lookups;
+information on existence of directories;
 </listitem>
 <listitem>
 file lookup errors, such as “file not found”, “no read permission”,
 and so on.
 <tag-name>
 <literal>max</literal>
 </tag-name>
 <tag-desc>
 sets the maximum number of elements in the cache;
-on cache overflow the least recently used (LRU) elements get removed;
+on cache overflow the least recently used (LRU) elements are removed;
 </tag-desc>
 <tag-name>
 <literal>inactive</literal>
 </tag-name>
 <tag-desc>
-defines a time, after which an element gets removed from the cache
+defines a time after which an element is removed from the cache
-if there were no accesses to it during this time;
+if it has not been accessed during this time;
 by default, it is 60 seconds;
 </tag-desc>
 <tag-name>
 <literal>off</literal>
 <context>location</context>
 <para>
 Sets the minimum <value>number</value> of file accesses during
 the period configured by the <literal>inactive</literal> parameter
-of the <link id="open_file_cache"/> directive,
+of the <link id="open_file_cache"/> directive, required for a file
-after which a file descriptor will remain open in the cache.
+descriptor to remain open in the cache.
 </para>
 </directive>
 <default>off</default>
 <context>http</context>
 <context>server</context>
 <para>
-This directive is made obsolete by the
+This directive is obsolete.
-<link id="server_name_in_redirect"/> directive.
+The <link id="server_name_in_redirect"/> directive should be used instead.
 </para>
 <!--
 <para>
 Enables or disables optimization of hostname checking in name-based
 <para>
 Enables or disables specifying the port in redirects issued by nginx.
 </para>
 <para>
-The use of a primary server name in redirects is controlled by
+The use of the primary server name in redirects is controlled by
 the <link id="server_name_in_redirect"/> directive.
 </para>
 </directive>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 <para>
-If possible, the output of client data will be postponed until
+If possible, the transmission of client data will be postponed until
 nginx has at least <value>size</value> bytes of data to send.
-Value of zero disables postponing.
+The zero value disables postponing data transmission.
 </para>
 </directive>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 <para>
-Sets the amount of pre-reading when working with files, in the kernel.
+Sets the amount of pre-reading for the kernel when working with file.
 </para>
 <para>
 On Linux, the
 <literal>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</literal>
-system call is used, so the <value>size</value> parameter is ignored.
+system call is used, and so the <value>size</value> parameter is ignored.
 </para>
 <para>
 On FreeBSD, the
 <literal>fcntl(O_READAHEAD,</literal>
 <value>size</value><literal>)</literal>
-system call is used, supported in FreeBSD&nbsp;9.0-CURRENT.
+system call, supported since FreeBSD&nbsp;9.0-CURRENT, is used.
-FreeBSD&nbsp;7 needs to be
+FreeBSD&nbsp;7 has to be
 <link url="http://sysoev.ru/freebsd/patch.readahead.txt">patched</link>.
 </para>
 </directive>
 <para>
 Enables or disables doing several redirects using the
 <link id="error_page"/>
 directive.
-There is a <link id="internal">limit</link> on a number of such redirects.
+The number of such redirects is <link id="internal">limited</link>.
 </para>
 </directive>
 <default>4k</default>
 <context>http</context>
 <context>server</context>
 <para>
-Allows to fine tune per-request memory allocations.
+Allows accurate tuning of per-request memory allocations.
-This directive has minimal impact on performance,
+This directive has minimal impact on performance
 and should not generally be used.
 </para>
 </directive>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 <para>
-Enables or disables resetting of timed out connections.
+Enables or disables resetting timed out connections.
-The reset is performed as follows: before closing a socket, the
+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
+When the socket is closed, TCP RST is sent to the client, and all memory
-occupied by this socket is freed.
+occupied by this socket is released.
-This avoids keeping of an already closed socket with filled buffers
+This helps avoid keeping an already closed socket with filled buffers
-for a long time, in a FIN_WAIT1 state.
+in a FIN_WAIT1 state for a long time.
 </para>
 <para>
-It should be noted that timed out keep-alive connections are still
+It should be noted that timed out keep-alive connections are
 closed normally.
 </para>
 </directive>
 Before version 1.1.7, only a single name server could be configured.
 Specifying name servers using IPv6 addresses is supported
 starting from versions 1.3.1 and 1.2.2.
 </note>
 By default, nginx caches answers using the TTL value of a response.
-An optional <literal>valid</literal> parameter allows to override it:
+An optional <literal>valid</literal> parameter allows overriding it:
 <example>
 resolver 127.0.0.1 [::1]:5353 valid=30s;
 </example>
 <note>
 Before version 1.1.9, tuning of caching time was not possible,
 <example>
 location /i/ {
 root /data/w3;
 }
 </example>
-“<literal>/i/top.gif</literal>” will be responded
+The <path>/data/w3/i/top.gif</path> file will be sent in response to
-with the file
+the “<literal>/i/top.gif</literal>” request.
-<path>/data/w3/i/top.gif</path>.
+</para>
-</para>
+<para>
-<para>
+The <value>path</value> value can contain variables,
-The <value>path</value> value can contain variables
 except <var>$document_root</var> and <var>$realpath_root</var>.
 </para>
 <para>
 A path to the file is constructed by merely adding a URI to the value
 of the <literal>root</literal> directive.
-If a URI need to be modified, the
+If a URI has to be modified, the
 <link id="alias"/> directive should be used.
 </para>
 </directive>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 <para>
-Allows access if <literal>all</literal> or <literal>any</literal> of the
+Allows access if both (<literal>all</literal>) or at least one
+(<literal>any</literal>) 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.
+modules allow access.
 </para>
 <para>
 Example:
 <example>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 <para>
-If set to a non-zero value, nginx will try to minimize the number
+If the directive is set to a non-zero value, nginx will try to minimize
-of send operations on client sockets by using either
+the number of send operations on client sockets by using either
 <c-def>NOTE_LOWAT</c-def> flag of the
-<link doc="../events.xml" id="kqueue"/> method,
+<link doc="../events.xml" id="kqueue"/> method
-or the <c-def>SO_SNDLOWAT</c-def> socket option,
+or the <c-def>SO_SNDLOWAT</c-def> socket option.
-with the specified <value>size</value>.
+In both cases the specified <value>size</value> is used.
 </para>
 <para>
 This directive is ignored on Linux, Solaris, and Windows.
 </para>
 <context>location</context>
 <para>
 When set to a non-zero value, limits the amount of data that can be
 transferred in a single <c-func>sendfile</c-func> call.
-Without the limit, one fast connection may seize the worker process.
+Without the limit, one fast connection may seize the worker process entirely.
 </para>
 </directive>
 <syntax block="yes"/>
 <default/>
 <context>http</context>
 <para>
-Sets a configuration for the virtual server.
+Sets configuration for a virtual server.
-There is no clean separation between IP-based (based on the IP address)
+There is no clear 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"/> directives describe all
-addresses and ports that should accept connections for a server, and the
+addresses and ports that should accept connections for the server, and the
 <link id="server_name"/> directive lists all server names.
 Example configurations are provided in the
 “<link doc="request_processing.xml"/>” document.
 </para>
 <syntax><value>name</value> ...</syntax>
 <default>""</default>
 <context>server</context>
 <para>
-Sets names of the virtual server, for example:
+Sets names of a virtual server, for example:
 <example>
 server {
 server_name example.com www.example.com;
 }
 </example>
 The first name becomes the primary server name.
 </para>
 <para>
 Server names can include an asterisk (“<literal>*</literal>”)
-to replace the first or last part of a name:
+replacing the first or last part of a name:
 <example>
 server {
 server_name example.com *.example.com www.example.*;
 }
 </example>
 Such names are called wildcard names.
 </para>
 <para>
-The first two of the above mentioned names can be combined:
+The first two of the names mentioned above can be combined in one:
 <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 (“<literal>~</literal>”):
+preceeding the name with a tilde (“<literal>~</literal>”):
 <example>
 server {
 server_name www.example.com ~^www\d+\.example\.com$;
 }
 </example>
 }
 </example>
 </para>
 <para>
-If the parameter equals “<var>$hostname</var>” (0.9.4), the
+If the directive’s parameter is set to “<var>$hostname</var>” (0.9.4), the
-machine’s hostname is substituted.
+machine’s hostname is inserted.
 </para>
 <para>
 It is also possible to specify an empty server name (0.7.11):
 <example>
 server {
 server_name www.example.com "";
 }
 </example>
 It allows this server to process requests without the <header>Host</header>
-header field, instead of the default server for the given address:port pair.
+header field — instead of the default server — for the given address:port pair.
 This is the default setting.
 <note>
 Before 0.8.48, the machine’s hostname was used by default.
 </note>
 </para>
 <para>
-When searching for a virtual server by name,
+During searching for a virtual server by name,
-if name matches more than one of the specified variants,
+if the name matches more than one of the specified variants,
-e.g. both wildcard name and regular expression match, the first matching
+(e.g. both a wildcard name and regular expression match), the first matching
-variant will be chosen, in the following order of precedence:
+variant will be chosen, in the following order of priority:
 <list type="enum">
 <listitem>
-exact name
+the exact name
 </listitem>
 <listitem>
-longest wildcard name starting with an asterisk,
+the longest wildcard name starting with an asterisk,
 e.g. “<literal>*.example.com</literal>”
 </listitem>
 <listitem>
-longest wildcard name ending with an asterisk,
+the longest wildcard name ending with an asterisk,
 e.g. “<literal>mail.*</literal>”
 </listitem>
 <listitem>
-first matching regular expression
+the first matching regular expression
-(in order of appearance in a configuration file)
+(in order of appearance in the configuration file)
 </listitem>
 </list>
 </para>
 <para>
 Enables or disables the use of the primary server name, specified by the
 <link id="server_name"/>
 directive, in redirects issued by nginx.
-When disabled, the name from the <header>Host</header> request header field
+When the use of the primary server name is disabled, the name from the
-is used.
+<header>Host</header> request header field is used.
-If this field is not present, an IP address of the server is used.
+If this field is not present, the IP address of the server is used.
 </para>
 <para>
 The use of a port in redirects is controlled by
 the <link id="port_in_redirect"/> directive.
 <default>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.
+The default value depends on the size of the processor’s cache line.
 Details of setting up hash tables are provided in a separate
 <link doc="../hash.xml">document</link>.
 </para>
 </directive>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 <para>
-Enables or disables emitting of nginx version in error messages and in the
+Enables or disables emitting nginx version in error messages and in the
 <header>Server</header> response header field.
 </para>
 </directive>
 <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.
-Options are enabled only when <link id="sendfile"/> is used.
+The options are enabled only when <link id="sendfile"/> is used.
-Enabling the option allows to
+Enabling the option allows
 <list type="bullet">
 <listitem>
-send the response header and the beginning of a file in one packet,
+sending the response header and the beginning of a file in one packet,
 on Linux and FreeBSD&nbsp;4.*;
 </listitem>
 <listitem>
-send a file in full packets.
+sending a file in full packets.
 </listitem>
 </list>
 </para>
 <default/>
 <context>server</context>
 <context>location</context>
 <para>
-Checks the existence of files in the specified order, and uses
+Checks the existence of files in the specified order and uses
 the first found file for request processing; the processing
 is performed in the current context.
-A path to the file is constructed from the
+The path to a file is constructed from the
 <value>file</value> parameter
 according to the
 <link id="root"/> and <link id="alias"/> directives.
-It is possible to check the directory existence by specifying
+It is possible to check directory’s existence by specifying
 a slash at the end of a name, e.g. “<literal>$uri/</literal>”.
 If none of the files were found, an internal redirect to the
-<value>uri</value> specified by the last parameter is made.
+<value>uri</value> specified in the last parameter is made.
 For example:
 <example>
 location /images/ {
 try_files $uri /images/default.gif;
 }
 expires 30s;
 }
 </example>
 The last parameter can also point to a named location,
 as shown in examples below.
-As of version 0.7.51, the last parameter can also be a
+Starting from version 0.7.51, the last parameter can also be a
 <value>code</value>:
 <example>
 location / {
 try_files $uri $uri/index.html $uri.html =404;
 }
 </example>
 </para>
 <para>
-Example when proxying Mongrel:
+Example in proxying Mongrel:
 <example>
 location / {
 try_files /system/maintenance.html
 $uri $uri/index.html $uri.html
 @mongrel;
 <context>location</context>
 <para>
 Maps file name extensions to MIME types of responses.
 Extensions are case-insensitive.
-Several extensions can map to one type, for example:
+Several extensions can be mapped to one type, for example:
 <example>
 types {
 application/octet-stream bin exe dll;
 application/octet-stream deb;
 application/octet-stream dmg;
 </para>
 <para>
 To make a particular location emit the
 “<literal>application/octet-stream</literal>”
-MIME type for all requests, try the following:
+MIME type for all requests, the following configuration can be used:
 <example>
 location /download/ {
 types        { }
 default_type application/octet-stream;
 }
 <context>server</context>
 <context>location</context>
 <para>
 Sets the bucket size for the types hash tables.
-Default value depends on the size of the processor’s cache line.
+The default value depends on the size of the processor’s cache line.
 Details of setting up hash tables are provided in a separate
 <link doc="../hash.xml">document</link>.
 </para>
 </directive>
 <context>http</context>
 <context>server</context>
 <para>
 Enables or disables the use of underscores in client request header fields.
-When disabled, request header fields whose names contain underscores are
+When the use of underscores is disabled, request header fields whose names
-marked as invalid and are subject to the <link id="ignore_invalid_headers"/>
+contain underscores are
-directive.
+marked as invalid and become subject to the
+<link id="ignore_invalid_headers"/> directive.
 </para>
 <para>
 A directive can be specified on the <link id="server"/> level
 in a default server.
-In this case, its value will cover all virtual servers
+In this case, its value will apply to all virtual servers
 listening on the same address and port.
 </para>
 </directive>
 <section id="variables" name="Embedded Variables">
 <para>
-The module <literal>ngx_http_core_module</literal> supports embedded variables
+The <literal>ngx_http_core_module</literal> module supports embedded variables
-with names matching those of the Apache Server.
+with names matching the Apache Server variables.
 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:
+Also there are other variables:
 <list type="tag">
 <tag-name id="var_arg_"><var>$arg_</var><value>name</value></tag-name>
 <tag-desc>
 argument <value>name</value> in the request line
 or an empty string otherwise
 </tag-desc>
 <tag-name id="var_limit_rate"><var>$limit_rate</var></tag-name>
 <tag-desc>
-setting this variable allows for response rate limiting;
+setting this variable enables response rate limiting;
 see <link id="limit_rate"/>
 </tag-desc>
 <tag-name id="var_msec"><var>$msec</var></tag-name>
 <tag-desc>
-current time in seconds with a milliseconds resolution (1.3.9, 1.2.6)
+current time in seconds with the milliseconds resolution (1.3.9, 1.2.6)
 </tag-desc>
 <tag-name id="var_nginx_version"><var>$nginx_version</var></tag-name>
 <tag-desc>
 nginx version
 <tag-name id="var_request_body_file"><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,
+To always write the request body to a file,
 <link id="client_body_in_file_only"/> needs to be enabled.
-When passing the name of a temporary file in a proxied request,
+When the name of a temporary file is passed in a proxied request
 or in a request to a FastCGI server,
-passing of the request body should be disabled by the
+passing the request body should be disabled by the
 <link doc="ngx_http_proxy_module.xml" id="proxy_pass_request_body">
 proxy_pass_request_body off</link>
 and
 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass_request_body">
 fastcgi_pass_request_body off</link>

Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_core_module.xml @ 958:fd1f8e0a405e