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

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 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	48ab154edf10

comparison

equal deleted inserted replaced

-:28d580f1eb63
+:488a3f738db0
 <default/>
 <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>
 <para>
 The following optional parameters are supported:
 <list type="bullet">
 <listitem>
 <literal>interval</literal>
-sets interval between two consecutive health checks,
+sets the interval between two consecutive health checks,
-defaults to five seconds;
+by default, 5 seconds;
 </listitem>
 <listitem>
 <literal>fails</literal>
-sets a number of consecutive failed health checks
+sets the number of consecutive failed health checks of a particular server
-after which the server will be considered unhealthy,
+after which this server will be considered unhealthy,
-defaults to 1;
+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
+specifies the <literal>match</literal> block configuring the tests that a
-pass in order for a health check to pass,
+response should pass in order for a health check to pass;
-defaults to responses with status codes 2xx and 3xx.
+by default, the response should have status code 2xx or 3xx.
 </listitem>
 </list>
 </para>
 proxy_pass http://backend;
 health_check;
 }
 </example>
 will send “<literal>/</literal>” requests to each
-server in the group <literal>backend</literal> every five seconds.
+server in the <literal>backend</literal> group every five seconds.
-If any communication errors or timeouts occur, or if a
+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
+2xx or 3xx, the health check will fail, and the server will
-become unhealthy.
+be considered unhealthy.
-Client requests will not be passed to unhealthy servers.
+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.
+and the body contents.
-Tests are configured separately with the <link id="match"/> directives
+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 {
 ...
 location / {
 header Content-Type = text/html;
 body ~ "Welcome to nginx!";
 }
 }
 </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
+a single failure of any check will make the corresponding server be
-to become unhealthy.
+considered unhealthy.
 </para>
 <para>
 <note>
 This directive is available as part of our <commercial_version/> only.
 <para>
 Defines the named test set used to verify responses to health check requests.
 </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>
 <tag-desc>status is 200</tag-desc>
 <tag-name><literal>status ! 400-599;</literal></tag-name>
 <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>
 <list type="tag">
 </list>
 </para>
 <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>
 <para>
 Examples:
 <para>
 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
+If session affinity is enabled, requests from the same client are always passed
-same server (in a group of servers) once a session has been created.
+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
+The method that is used to create and track sessions must be specified in a
-directive, for example, <link id="sticky_cookie_insert"/>.
+separate directive, for example, <link id="sticky_cookie_insert"/>.
 <example>
 upstream backend {
 server backend1.example.com;
 server backend2.example.com;
 The directive must be specified after the <link id="ip_hash"/> or the
 <link id="least_conn"/> directives.
 </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.
+nginx looks up the session corresponding to the request.
-If the session is found, server identification data is extracted from it.
+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
+balancing method, server information from the session, and the real state of
-servers in a group (up or down, failed, etc.).
+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
+If the chosen server is not the one specified in the session
-(due to being down, for example), the session is cleared
+(for example, because it is down), the session is cleared
-and the request is processed as it had no session.
+and the request is processed as if it had no session.
 </listitem>
 <listitem>
 The server returns the response.
 </listitem>
 <listitem>
-If there was no session for the request, new session
+If there is no session for the request, a new session
-is created and server identification data is stored in it.
+is created and the server identification data is stored in it.
 </listitem>
 </list>
 </para>
 [<literal>path=</literal><value>path</value>]</syntax>
 <default/>
 <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.
 Example:
 <example>
 Additional parameters may be as follows:
 <list type="tag">
 <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.
 </tag-desc>
 <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>
 <note>
 This directive is available as part of our <commercial_version/> only.
 <syntax/>
 <default/>
 <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>
 <listitem>view an individual server;</listitem>
 <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 noted in the <link id="server"/> directive, specifying a server
-as a domain name may result in several servers being added.
+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>
 </para>
 <tag-name>
 <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>
 <tag-name>
 <literal>id=</literal><value>number</value></tag-name>
 </tag-desc>
 </list>
 The first three parameters select a target the command applies to.
-Without other parameters, configuration of the selected target
+Without other parameters, the command shows configuration of the selected
-is shown.
+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&amp;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&amp;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&amp;backup=&amp;id=42
 </example>
 </para>
 <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=&amp;upstream=appservers&amp;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=&amp;upstream=appservers&amp;backup=&amp;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=&amp;upstream=appservers&amp;server=127.0.0.1:8080&amp;weight=2&amp;max_fails=3&amp;fail_timeout=3s&amp;down=
 </example>
 </para>
 <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=&amp;upstream=appservers&amp;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=&amp;upstream=appservers&amp;backup=&amp;id=42
 </example>
 </para>
 <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&amp;id=42&amp;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&amp;backup=&amp;id=42&amp;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&amp;id=42&amp;max_fails=3&amp;weight=4
 </example>
 </para>

Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 956:488a3f738db0