Mercurial > hg > nginx-site
diff xml/en/docs/http/ngx_http_upstream_module.xml @ 953:aded7086e84f
Commercial version documentation.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 01 Aug 2013 16:31:02 +0400 |
parents | ba3d6ade3513 |
children | 28d580f1eb63 |
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_upstream_module.xml Wed Jul 31 23:46:04 2013 +0400 +++ b/xml/en/docs/http/ngx_http_upstream_module.xml Thu Aug 01 16:31:02 2013 +0400 @@ -10,7 +10,7 @@ <module name="Module ngx_http_upstream_module" link="/en/docs/http/ngx_http_upstream_module.html" lang="en" - rev="4"> + rev="5"> <section id="summary"> @@ -46,6 +46,36 @@ </example> </para> +<para> +Dynamically configurable group, +available as part of our <commercial_version/> only: +<example> +upstream <emphasis>appservers</emphasis> { + zone appservers 64k; + + server appserv1.example.com weight=5; + server appserv2.example.com:8080 fail_timeout=5s; + server 192.0.2.1 max_fails=3; + + server reserve1.example.com:8080 backup; + server reserve2.example.com:8080 backup; +} + +server { + location / { + proxy_pass http://<emphasis>appservers</emphasis>; + health_check; + } + + location /upstream_conf { + upstream_conf; + allow 127.0.0.1; + deny all; + } +} +</example> +</para> + </section> @@ -180,6 +210,30 @@ </directive> +<directive name="zone"> +<syntax><value>name</value> <value>size</value></syntax> +<default/> +<context>upstream</context> + +<para> +Makes the group dynamically configurable. +Defines the <value>name</value> and <value>size</value> of a shared +memory zone that keeps group’s configuration and run-time state that are +shared between worker processes. +Such groups allow to add, remove, and modify servers at run time. +The configuration is accessible via a special location handled by +<link id="upstream_conf"/>. +</para> + +<para> +<note> +This directive is available as part of our <commercial_version/> only. +</note> +</para> + +</directive> + + <directive name="ip_hash"> <syntax/> <default/> @@ -364,6 +418,640 @@ </directive> + +<directive name="health_check"> +<syntax> + [<literal>interval=</literal><value>time</value>] +<!-- + [<literal>jitter=</literal><value>time</value>] +--> + [<literal>fails=</literal><value>number</value>] + [<literal>passes=</literal><value>number</value>] + [<literal>uri=</literal><value>uri</value>] + [<literal>match=</literal><value>name</value>]</syntax> + +<default/> +<context>location</context> + +<para> +Enables periodic health checks of 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, +defaults to five 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; +</listitem> + +<listitem> +<literal>passes</literal> +sets a number of consecutive passed health checks +after which the server will be considered healthy, +defaults to 1; +</listitem> + +<listitem> +<literal>uri</literal> +defines the URI used in health check requests, +defaults to “<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. +</listitem> + +</list> +</para> + +<para> +For example, +<example> +location / { + proxy_pass http://backend; + health_check; +} +</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 +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. +</para> + +<para> +Health checks can be configured to test 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 referenced in the <literal>match</literal> parameter. +For example, +<example> +http { + server { + ... + location / { + proxy_pass http://backend; + health_check match=welcome; + } + } + + match welcome { + status 200; + header Content-Type = text/html; + body ~ "Welcome to nginx!"; + } +} +</example> +tells that for a health check to pass, a response 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>. +</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. +</para> + +<para> +<note> +This directive is available as part of our <commercial_version/> only. +</note> +</para> + +</directive> + + +<directive name="match"> +<syntax block="yes"><value>name</value></syntax> +<default/> +<context>http</context> + +<para> +Defines the named test set used to verify responses to health check requests. +</para> + +<para> +The following 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 ! 500;</literal></tag-name> +<tag-desc>status is not 500</tag-desc> + +<tag-name><literal>status 200 204;</literal></tag-name> +<tag-desc>status is 200 or 204</tag-desc> + +<tag-name><literal>status ! 301 302;</literal></tag-name> +<tag-desc>status is neither 301 nor 302</tag-desc> + +<tag-name><literal>status 200-399;</literal></tag-name> +<tag-desc>status is in the 200..399 range</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> + +</list> + +<list type="tag"> + +<tag-name><literal>header Content-Type = text/html;</literal></tag-name> +<tag-desc> +header contains <header>Content-Type</header> +with value <literal>text/html</literal> +</tag-desc> + +<tag-name><literal>header Content-Type != text/html;</literal></tag-name> +<tag-desc> +header contains <header>Content-Type</header> +with value other than <literal>text/html</literal> +</tag-desc> + +<tag-name><literal>header Connection ~ close;</literal></tag-name> +<tag-desc> +header contains <header>Connection</header> +with value matching regular expression <literal>close</literal> +</tag-desc> + +<tag-name><literal>header Connection !~ close;</literal></tag-name> +<tag-desc> +header contains <header>Connection</header> +with value not matching regular expression <literal>close</literal> +</tag-desc> + +<tag-name><literal>header Host;</literal></tag-name> +<tag-desc>header contains <header>Host</header></tag-desc> + +<tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name> +<tag-desc>header lacks <header>X-Accel-Redirect</header></tag-desc> + +</list> + +<list type="tag"> + +<tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name> +<tag-desc> +body matches regular expression “<literal>Welcome to nginx!</literal>” +</tag-desc> + +<tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name> +<tag-desc> +body does not match regular expression “<literal>Welcome to nginx!</literal>” +</tag-desc> + +</list> +</para> + +<para> +If several tests are specified, +the response matches only if it passes all tests. +<note> +Only the first 256k of body are examined. +</note> +</para> + +<para> +Examples: +<example> +# status is 200, content type is "text/html", +# and body contains "Welcome to nginx!" +match welcome { + status 200; + header Content-Type = text/html; + body ~ "Welcome to nginx!"; +} +</example> + +<example> +# status is not one of 301, 302, 303, or 307, and header does not have "Refresh:" +match not_redirect { + status ! 301-303 307; + header ! Refresh; +} +</example> + +<example> +# status ok and not in maintenance mode +match server_ok { + status 200-399; + body !~ "maintenance mode"; +} +</example> + +</para> + +<para> +<note> +This directive is available as part of our <commercial_version/> only. +</note> +</para> + +</directive> + + +<directive name="sticky"> +<syntax/> +<default/> +<context>upstream</context> + +<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 +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"/>. +<example> +upstream backend { + server backend1.example.com; + server backend2.example.com; + + sticky; + sticky_cookie_insert "sticky"; +} + +server { + location / { + proxy_pass http://backend; + } +} +</example> +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: +<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. +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.). +</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. +</listitem> + +<listitem> +The server returns the response. +</listitem> + +<listitem> +If there was no session for the request, new session +is created and server identification data is stored in it. +</listitem> + +</list> +</para> + +<para> +<note> +This directive is available as part of our <commercial_version/> only. +</note> +</para> + +</directive> + + +<directive name="sticky_cookie_insert"> +<syntax><value>name</value> +[<literal>expires=</literal><value>time</value>] +[<literal>domain=</literal><value>host</value>] +[<literal>path=</literal><value>path</value>]</syntax> +<default/> +<context>upstream</context> + +<para> +Enables and configures the session tracking method, 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> +sticky_cookie_insert "srv_id" "expires=1h 7m" domain=example.com path=/; +</example> +The first parameter sets the name of the cookie to be inserted or inspected. +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. +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. +</tag-desc> + +<tag-name><literal>path</literal></tag-name> +<tag-desc> +Defines a path for which the cookie is set. +</tag-desc> + +</list> +If some parameter is omitted, then the corresponding cookie field is not set. +</para> + +<para> +<note> +This directive is available as part of our <commercial_version/> only. +</note> +</para> + +</directive> + + +<directive name="sticky_log_requests"> +<syntax><literal>debug</literal> | +<literal>info</literal> | +<literal>notice</literal> | +<literal>warn</literal> | +<literal>error</literal></syntax> +<default/> +<context>upstream</context> + +<para> +Enables logging of session-related operations and sets the desired +logging level. +</para> + +<para> +<note> +This directive is available as part of our <commercial_version/> only. +</note> +</para> + +</directive> + + +<directive name="upstream_conf"> +<syntax/> +<default/> +<context>location</context> + +<para> +Turns on upstream configuration HTTP interface in a 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: +<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>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. +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. +</note> +</para> + +<para> +A command consists of parameters passed as request arguments, for example: +<example> +http://127.0.0.1/upstream_conf?upstream=appservers +</example> +</para> + +<para> +The following parameters are supported: + +<list type="tag" compact="no"> + +<tag-name> +<literal>upstream=</literal><value>name</value></tag-name> +<tag-desc> +Selects a group. +This parameter is mandatory. +</tag-desc> + +<tag-name> +<literal>backup=</literal> +</tag-name> +<tag-desc> +If unset, 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> +Selects an individual primary or backup server in the group. +</tag-desc> + +<tag-name> +<literal>remove=</literal></tag-name> +<tag-desc> +Removes an individual primary or backup server from the group. +</tag-desc> + +<tag-name> +<literal>add=</literal></tag-name> +<tag-desc> +Adds a new primary or backup server to the group. +</tag-desc> + +<tag-name> +<literal>server=</literal><value>address</value></tag-name> +<tag-desc> +Same as the “<literal>address</literal>” parameter +of the <link id="server"/> directive. +</tag-desc> + +<tag-name> +<literal>weight=</literal><value>number</value></tag-name> +<tag-desc> +Same as the “<literal>weight</literal>” parameter +of the <link id="server"/> directive. +</tag-desc> + +<tag-name> +<literal>max_fails=</literal><value>number</value></tag-name> +<tag-desc> +Same as the “<literal>max_fails</literal>” parameter +of the <link id="server"/> directive. +</tag-desc> + +<tag-name> +<literal>fail_timeout=</literal><value>time</value></tag-name> +<tag-desc> +Same as the “<literal>fail_timeout</literal>” parameter +of the <link id="server"/> directive. +</tag-desc> + +<tag-name> +<literal>down=</literal></tag-name> +<tag-desc> +Same as the “<literal>down</literal>” parameter +of the <link id="server"/> directive. +</tag-desc> + +<tag-name> +<literal>up=</literal></tag-name> +<tag-desc> +The opposite of the “<literal>down</literal>” parameter +of the <link id="server"/> directive. +</tag-desc> + +</list> + +The first three parameters select a target the command applies to. +Without other parameters, configuration of the selected target +is shown. +</para> + +<para> +For example, to view the primary servers in the group: +<example> +http://127.0.0.1/upstream_conf?upstream=appservers +</example> + +To view the backup servers in the group: +<example> +http://127.0.0.1/upstream_conf?upstream=appservers&backup= +</example> + +To view an individual primary server in the group: +<example> +http://127.0.0.1/upstream_conf?upstream=appservers&id=42 +</example> + +To view an individual backup server in the group: +<example> +http://127.0.0.1/upstream_conf?upstream=appservers&backup=&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. +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: +<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: +<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>”: +<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> +</para> + +<para> +To remove an individual primary or backup server from the group, +it should be selected with the <literal>id=</literal> parameter. +</para> + +<para> +For example, to remove an individual primary server from the group: +<example> +http://127.0.0.1/upstream_conf?remove=&upstream=appservers&id=42 +</example> + +To remove an individual backup server from the group: +<example> +http://127.0.0.1/upstream_conf?remove=&upstream=appservers&backup=&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. +</para> + +<para> +For example, to modify an individual primary server in the group +by marking it “<literal>down</literal>”: +<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: +<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: +<example> +http://127.0.0.1/upstream_conf?upstream=appservers&id=42&max_fails=3&weight=4 +</example> + +</para> + +<para> +<note> +This directive is available as part of our <commercial_version/> only. +</note> +</para> + +</directive> + </section>