Mercurial > hg > nginx-site
changeset 956:488a3f738db0
Text revision of commercial modules.
| author | Egor Nikitin <yegor.nikitin@gmail.com> |
|---|---|
| date | Fri, 02 Aug 2013 10:28:49 +0400 |
| parents | 28d580f1eb63 |
| children | 6d9d4bb571a9 |
| files | xml/en/docs/http/ngx_http_f4f_module.xml xml/en/docs/http/ngx_http_hls_module.xml xml/en/docs/http/ngx_http_log_module.xml xml/en/docs/http/ngx_http_mp4_module.xml xml/en/docs/http/ngx_http_session_log_module.xml xml/en/docs/http/ngx_http_upstream_module.xml |
| diffstat | 6 files changed, 131 insertions(+), 121 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_f4f_module.xml Fri Aug 02 13:01:50 2013 +0400 +++ b/xml/en/docs/http/ngx_http_f4f_module.xml Fri Aug 02 10:28:49 2013 +0400 @@ -14,13 +14,13 @@ <section id="summary"> <para> -The module <literal>ngx_http_f4f_module</literal> provides +The <literal>ngx_http_f4f_module</literal> module provides server-side support for Adobe HTTP Dynamic Streaming (HDS). </para> <para> -This module implements handling of HTTP Dynamic Streaming requests in a -“<literal>/videoSeg1-Frag1</literal>” form, extracting needed fragment +This module implements handling of HTTP Dynamic Streaming requests in the +“<literal>/videoSeg1-Frag1</literal>” form — extracting the needed fragment from the <path>videoSeg1.f4f</path> file using the <path>videoSeg1.f4x</path> index file. This module is an alternative to the Adobe’s f4f module (HTTP Origin Module) @@ -63,7 +63,7 @@ <context>location</context> <para> -Turns on module processing in a surrounding location. +Turns on module processing in the surrounding location. </para> </directive> @@ -77,7 +77,8 @@ <context>location</context> <para> -Sets the size of a memory buffer used for reading <path>.f4x</path> index file. +Sets the size of a memory buffer used for reading the <path>.f4x</path> index +file. </para> </directive>
--- a/xml/en/docs/http/ngx_http_hls_module.xml Fri Aug 02 13:01:50 2013 +0400 +++ b/xml/en/docs/http/ngx_http_hls_module.xml Fri Aug 02 10:28:49 2013 +0400 @@ -14,18 +14,19 @@ <section id="summary"> <para> -The module <literal>ngx_http_hls_module</literal> provides HTTP Live Streaming -(HLS) server-side support for H.264/AAC files typically having filename -extensions <path>.mp4</path>, <path>.m4v</path>, and <path>.m4a</path>. +The <literal>ngx_http_hls_module</literal> module provides HTTP Live Streaming +(HLS) server-side support for H.264/AAC files. +Such files typically have the <path>.mp4</path>, <path>.m4v</path>, +or <path>.m4a</path> filename extensions. </para> <para> -Two URIs are supported for each MP4 file: +nginx supports two URIs for each MP4 file: <list type="bullet"> <listitem> The playlist URI that ends with “<literal>.m3u8</literal>” and accepts -the optional “<literal>len</literal>” argument that defines fragment length +the optional “<literal>len</literal>” argument that defines the fragment length in seconds; </listitem> @@ -60,7 +61,7 @@ alias /var/video/; } </example> -For example, the following URIs are supported for +With this configuration, the following URIs are supported for the “<path>/var/video/test.mp4</path>” file: <example> http://hls.example.com/video/test.mp4.m3u8?len=8.000 @@ -79,7 +80,7 @@ <context>location</context> <para> -Turns on HLS streaming in a surrounding location. +Turns on HLS streaming in the surrounding location. </para> </directive> @@ -94,7 +95,7 @@ <para> Sets the maximum <value>number</value> and <value>size</value> of buffers -for reading and writing data frames. +that are used for reading and writing data frames. </para> </directive> @@ -108,7 +109,7 @@ <context>location</context> <para> -Defines fragment length for playlist URIs requested without the +Defines the default fragment length for playlist URIs requested without the “<literal>len</literal>” argument. </para> @@ -123,7 +124,7 @@ <context>location</context> <para> -Sets the initial <value>size</value> of a memory buffer used to +Sets the initial <value>size</value> of the memory buffer used to process MP4 files. </para> @@ -142,7 +143,7 @@ Its size cannot exceed the specified <value>size</value>, or else nginx will return the server error <http-status code="500" text="Internal Server Error"/>, -and log the following: +and log the following message: <example> "/some/movie/file.mp4" mp4 moov atom is too large: 12583268, you may want to increase hls_mp4_max_buffer_size
--- a/xml/en/docs/http/ngx_http_log_module.xml Fri Aug 02 13:01:50 2013 +0400 +++ b/xml/en/docs/http/ngx_http_log_module.xml Fri Aug 02 10:28:49 2013 +0400 @@ -185,10 +185,11 @@ <tag-name><literal>server=</literal><value>address</value></tag-name> <tag-desc> -Defines an address of a syslog server. -An address can be specified as a domain name or IP address, -and an optional port, or as a UNIX-domain socket path -specified after the “<literal>unix:</literal>” prefix. +Defines the address of a syslog server. +The address can be specified as a domain name, IP address, or +a UNIX-domain socket path (specified after the “<literal>unix:</literal>” +prefix). +With a domain name or IP address, the port can be specified. If port is not specified, the port 514 is used. If a domain name resolves to several IP addresses, the first resolved address is used. @@ -220,7 +221,7 @@ <tag-name><literal>tag=</literal><value>string</value></tag-name> <tag-desc> -Sets tag of syslog messages. +Sets the tag of syslog messages. Default is “<literal>nginx</literal>”. </tag-desc>
--- a/xml/en/docs/http/ngx_http_mp4_module.xml Fri Aug 02 13:01:50 2013 +0400 +++ b/xml/en/docs/http/ngx_http_mp4_module.xml Fri Aug 02 10:28:49 2013 +0400 @@ -172,11 +172,11 @@ <context>location</context> <para> -Enables or disables rate limiting based on an average bitrate of the +Enables or disables rate limiting based on the average bitrate of the MP4 file served. -To calculate the rate, bitrate is multiplied by the specified +To calculate the rate, the bitrate is multiplied by the specified <value>factor</value>. -The special value “<literal>on</literal>” corresponds to a factor of 1.1. +The special value “<literal>on</literal>” corresponds to the factor of 1.1. </para> <para> @@ -196,7 +196,7 @@ <context>location</context> <para> -Limits rate after sending the specified amount of media data. +Limits the rate after sending the specified amount of media data. </para> <para>
--- a/xml/en/docs/http/ngx_http_session_log_module.xml Fri Aug 02 13:01:50 2013 +0400 +++ b/xml/en/docs/http/ngx_http_session_log_module.xml Fri Aug 02 10:28:49 2013 +0400 @@ -14,8 +14,8 @@ <section id="summary"> <para> -The module <literal>ngx_http_session_log_module</literal> allows to log -sessions (i.e. aggregates of multiple HTTP requests) instead of +The <literal>ngx_http_session_log_module</literal> module enables logging +sessions (that is, aggregates of multiple HTTP requests) instead of individual HTTP requests. </para> @@ -31,7 +31,8 @@ <section id="example" name="Example Configuration"> <para> -Log sessions based on client address and <header>User-Agent</header> +The following configuration sets up a session log and maps requests to +sessions according to the request client address and <header>User-Agent</header> request header field: <example> session_log_zone /path/to/log format=combined @@ -57,10 +58,11 @@ <context>http</context> <para> -Specifies format of a log. -Value of the <var>$body_bytes_sent</var> variable is aggregated across -all requests in the session. -Everything else corresponds to the first request that started a session. +Specifies the output format of a log. +The value of the <var>$body_bytes_sent</var> variable is aggregated across +all requests in a session. +The values of all other variables available for logging correspond to the +first request in a session. </para> </directive> @@ -79,32 +81,34 @@ <context>http</context> <para> -Sets path to log file and shared memory zone used to store currently active -sessions. +Sets the path to a log file and configures the shared memory zone that is used +to store currently active sessions. </para> <para> -Sessions are considered active for as long as the time elapsed since -the last request in the session does not exceed a specified +A session is considered active for as long as the time elapsed since +the last request in the session does not exceed the specified <literal>timeout</literal> (by default, 30 seconds). -Session is logged once it is no longer active. +Once a session is no longer active, it is written to the log. </para> <para> -Requests are mapped into sessions based on the value of the -<literal>id</literal> parameter. -If <literal>id</literal> is not specified or does not represent the valid -MD5 hash, a new session is created using MD5 hash computed from the value -of the <literal>md5</literal> parameter. -Both <literal>id</literal> and <literal>md5</literal> parameters +The <literal>id</literal> parameter identifies the +session to which a request is mapped. +The <literal>id</literal> parameter is set to the hexadecimal representation +of an MD5 hash (for example, obtained from a cookie using variables). +If this parameter is not specified or does not represent the valid +MD5 hash, nginx computes the MD5 hash from the value of +the <literal>md5</literal> parameter and creates a new session using this hash. +Both the <literal>id</literal> and <literal>md5</literal> parameters can contain variables. </para> <para> -The <literal>format</literal> parameter can be used to set custom session log -format. -If <literal>format</literal> is not specified then the predefined format -“<literal>combined</literal>” is used. +The <literal>format</literal> parameter sets the custom session log +format configured by the <link id="session_log_format"/> directive. +If <literal>format</literal> is not specified, the predefined +“<literal>combined</literal>” format is used. </para> </directive> @@ -118,7 +122,7 @@ <context>location</context> <para> -Use the specified session log. +Enables the use of the specified session log. The special value <literal>off</literal> cancels all <literal>session_log</literal> directives inherited from the previous configuration level.
--- a/xml/en/docs/http/ngx_http_upstream_module.xml Fri Aug 02 13:01:50 2013 +0400 +++ b/xml/en/docs/http/ngx_http_upstream_module.xml Fri Aug 02 10:28:49 2013 +0400 @@ -447,7 +447,7 @@ <context>location</context> <para> -Enables periodic health checks of servers in a +Enables periodic health checks of the servers in a <link id="upstream">group</link> referenced in the surrounding location. </para> @@ -457,35 +457,35 @@ <listitem> <literal>interval</literal> -sets interval between two consecutive health checks, -defaults to five seconds; +sets the interval between two consecutive health checks, +by default, 5 seconds; </listitem> <listitem> <literal>fails</literal> -sets a number of consecutive failed health checks -after which the server will be considered unhealthy, -defaults to 1; +sets the number of consecutive failed health checks of a particular server +after which this server will be considered unhealthy, +by default, 1; </listitem> <listitem> <literal>passes</literal> -sets a number of consecutive passed health checks +sets the number of consecutive passed health checks of a particular server after which the server will be considered healthy, -defaults to 1; +by default, 1; </listitem> <listitem> <literal>uri</literal> defines the URI used in health check requests, -defaults to “<literal>/</literal>”; +by default, “<literal>/</literal>”; </listitem> <listitem> <literal>match</literal> -names tests that a response should -pass in order for a health check to pass, -defaults to responses with status codes 2xx and 3xx. +specifies the <literal>match</literal> block configuring the tests that a +response should pass in order for a health check to pass; +by default, the response should have status code 2xx or 3xx. </listitem> </list> @@ -500,21 +500,21 @@ } </example> will send “<literal>/</literal>” requests to each -server in the group <literal>backend</literal> every five seconds. -If any communication errors or timeouts occur, or if a +server in the <literal>backend</literal> group every five seconds. +If any communication error or timeout occurs, or a proxied server responds with the status code other than -2xx or 3xx, health check will fail, and the server will -become unhealthy. -Client requests will not be passed to unhealthy servers. +2xx or 3xx, the health check will fail, and the server will +be considered unhealthy. +Client requests are not passed to unhealthy servers. </para> <para> -Health checks can be configured to test status code of a response, +Health checks can be configured to test the status code of a response, presence of certain header fields and their values, -and/or the body contents. -Tests are configured separately with the <link id="match"/> directives +and the body contents. +Tests are configured separately using the <link id="match"/> directive and referenced in the <literal>match</literal> parameter. -For example, +For example: <example> http { server { @@ -532,19 +532,20 @@ } } </example> -tells that for a health check to pass, a response should succeed, +This configuration tells that for a health check to pass, the response to a +health check request should succeed, have status 200, content type “<literal>text/html</literal>”, and contain “<literal>Welcome to nginx!</literal>” in the body. </para> <para> -It is required that a group be in <link id="zone">shared memory</link>. +The server group must reside in the <link id="zone">shared memory</link>. </para> <para> If several health checks are defined for the same group of servers, -a single failure of any check will make the corresponding server -to become unhealthy. +a single failure of any check will make the corresponding server be +considered unhealthy. </para> <para> @@ -566,7 +567,7 @@ </para> <para> -The following can be tested in a response: +The following items can be tested in a response: <list type="tag"> <tag-name><literal>status 200;</literal></tag-name> @@ -588,7 +589,7 @@ <tag-desc>status is not in the 400..599 range</tag-desc> <tag-name><literal>status 301-303 307;</literal></tag-name> -<tag-desc>status is one of 301, 302, 303, or 307</tag-desc> +<tag-desc>status is either 301, 302, 303, or 307</tag-desc> </list> @@ -643,9 +644,9 @@ <para> If several tests are specified, -the response matches only if it passes all tests. +the response matches only if it matches all tests. <note> -Only the first 256k of body are examined. +Only the first 256k of the response body are examined. </note> </para> @@ -697,10 +698,10 @@ Enables session affinity support. The session is an object that is used to uniquely identify and maintain the state of a client during a given period of time. -If session affinity is enabled, a client’s requests are always passed to the -same server (in a group of servers) once a session has been created. -Method used to create and track sessions must be specified by a separate -directive, for example, <link id="sticky_cookie_insert"/>. +If session affinity is enabled, requests from the same client are always passed +to the same server (in a group of servers) once a session has been created. +The method that is used to create and track sessions must be specified in a +separate directive, for example, <link id="sticky_cookie_insert"/>. <example> upstream backend { server backend1.example.com; @@ -721,26 +722,26 @@ </para> <para> -Requests are processed as follows with the session affinity enabled: +When the session affinity is enabled, a request is processed as follows: <list type="enum"> <listitem> -The lookup of session corresponding to request is performed. -If the session is found, server identification data is extracted from it. +nginx looks up the session corresponding to the request. +If the session is found, the server identification data is extracted from it. This data is used by the server selection algorithm. </listitem> <listitem> The server to process the request is chosen according to the configured -balancing method, server information from session and the real state of -servers in a group (up or down, failed, etc.). +balancing method, server information from the session, and the real state of +servers in a group (such as failed, up or down). </listitem> <listitem> The request is passed to the chosen server for processing. -If the chosen server does not match specified in the session -(due to being down, for example), the session is cleared -and the request is processed as it had no session. +If the chosen server is not the one specified in the session +(for example, because it is down), the session is cleared +and the request is processed as if it had no session. </listitem> <listitem> @@ -748,8 +749,8 @@ </listitem> <listitem> -If there was no session for the request, new session -is created and server identification data is stored in it. +If there is no session for the request, a new session +is created and the server identification data is stored in it. </listitem> </list> @@ -773,7 +774,7 @@ <context>upstream</context> <para> -Enables and configures the session tracking method, based on keeping +Enables and configures the session tracking method that is based on keeping session information in HTTP cookies. The directive must be specified after the <link id="ip_hash"/> or the <link id="least_conn"/> directives. @@ -787,7 +788,7 @@ <tag-name><literal>expires</literal></tag-name> <tag-desc> -Sets a time during which a browser should keep the cookie. +Sets the time for which a browser should keep the cookie. The parameter “<literal>max</literal>” sets the time to “<literal>31 Dec 2037 23:55:55 GMT</literal>”. This is the maximum time understood by old browsers. @@ -795,16 +796,16 @@ <tag-name><literal>domain</literal></tag-name> <tag-desc> -Defines a domain for which the cookie is set. +Defines the domain for which the cookie is set. </tag-desc> <tag-name><literal>path</literal></tag-name> <tag-desc> -Defines a path for which the cookie is set. +Defines the path for which the cookie is set. </tag-desc> </list> -If some parameter is omitted, then the corresponding cookie field is not set. +If some parameter is omitted, the corresponding cookie field is not set. </para> <para> @@ -845,13 +846,14 @@ <context>location</context> <para> -Turns on upstream configuration HTTP interface in a surrounding location. +Turns on the HTTP interface of upstream configuration in the surrounding +location. Access to this location should be <link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. </para> <para> -Configuration commands allow to: +Configuration commands can be used to: <list type="bullet"> <listitem>view all primary or backup servers in a group;</listitem> @@ -860,22 +862,23 @@ <listitem>modify an individual server;</listitem> -<listitem>add a new server (see note below);</listitem> +<listitem>add a new server (see the note below);</listitem> <listitem>remove an individual server.</listitem> </list> <note> -As noted in the <link id="server"/> directive, adding a server specified -as a domain name may result in several servers being added. +As noted in the <link id="server"/> directive, specifying a server +as a domain name may result in several servers being added to the group. Since addresses in a group are not required to be unique, individual servers in a group can be uniquely referenced to only by their ID. -IDs are assigned automatically and shown when viewing group configuration. +IDs are assigned automatically and shown on viewing of the group configuration. </note> </para> <para> -A command consists of parameters passed as request arguments, for example: +A configuration command consists of parameters passed as request arguments, +for example: <example> http://127.0.0.1/upstream_conf?upstream=appservers </example> @@ -897,7 +900,7 @@ <literal>backup=</literal> </tag-name> <tag-desc> -If unset, selects primary servers in the group. +If not set, selects primary servers in the group. If set, selects backup servers in the group. </tag-desc> @@ -971,27 +974,27 @@ </list> The first three parameters select a target the command applies to. -Without other parameters, configuration of the selected target -is shown. +Without other parameters, the command shows configuration of the selected +target. </para> <para> -For example, to view the primary servers in the group: +For example, to view the primary servers in the group, send: <example> http://127.0.0.1/upstream_conf?upstream=appservers </example> -To view the backup servers in the group: +To view the backup servers in the group, send: <example> http://127.0.0.1/upstream_conf?upstream=appservers&backup= </example> -To view an individual primary server in the group: +To view an individual primary server in the group, send: <example> http://127.0.0.1/upstream_conf?upstream=appservers&id=42 </example> -To view an individual backup server in the group: +To view an individual backup server in the group, send: <example> http://127.0.0.1/upstream_conf?upstream=appservers&backup=&id=42 </example> @@ -999,25 +1002,25 @@ <para> To add a new primary or backup server to the group, -its address should be specified in the “<literal>server=</literal>” parameter. +specify its address in the “<literal>server=</literal>” parameter. Without other parameters specified, a server will be added with other parameters set to their default values (see the <link id="server"/> directive). </para> <para> -For example, to add a new primary server to the group: +For example, to add a new primary server to the group, send: <example> http://127.0.0.1/upstream_conf?add=&upstream=appservers&server=127.0.0.1:8080 </example> -To add a new backup server to the group: +To add a new backup server to the group, send: <example> http://127.0.0.1/upstream_conf?add=&upstream=appservers&backup=&server=127.0.0.1:8080 </example> To add a new primary server to the group, set its parameters to non-default values -and mark it “<literal>down</literal>”: +and mark it as “<literal>down</literal>” by sending: <example> http://127.0.0.1/upstream_conf?add=&upstream=appservers&server=127.0.0.1:8080&weight=2&max_fails=3&fail_timeout=3s&down= </example> @@ -1025,16 +1028,16 @@ <para> To remove an individual primary or backup server from the group, -it should be selected with the <literal>id=</literal> parameter. +select it with the <literal>id=</literal> parameter. </para> <para> -For example, to remove an individual primary server from the group: +For example, to remove an individual primary server from the group, send: <example> http://127.0.0.1/upstream_conf?remove=&upstream=appservers&id=42 </example> -To remove an individual backup server from the group: +To remove an individual backup server from the group, send: <example> http://127.0.0.1/upstream_conf?remove=&upstream=appservers&backup=&id=42 </example> @@ -1042,22 +1045,22 @@ <para> To modify an individual primary or backup server in the group, -it should be selected with the <literal>id=</literal> parameter. +select it with the <literal>id=</literal> parameter. </para> <para> For example, to modify an individual primary server in the group -by marking it “<literal>down</literal>”: +by marking it as “<literal>down</literal>”, send: <example> http://127.0.0.1/upstream_conf?upstream=appservers&id=42&down= </example> -To modify address of an individual backup server in the group: +To modify the address of an individual backup server in the group, send: <example> http://127.0.0.1/upstream_conf?upstream=appservers&backup=&id=42&server=192.0.2.3:8123 </example> -To modify other parameters of an individual primary server in the group: +To modify other parameters of an individual primary server in the group, send: <example> http://127.0.0.1/upstream_conf?upstream=appservers&id=42&max_fails=3&weight=4 </example>