Mercurial > hg > nginx-site
diff xml/en/docs/stream/ngx_stream_upstream_hc_module.xml @ 1947:6b6d0e844bf7
Moved "health_check" and "match" to ngx_stream_upstream_hc_module.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Fri, 24 Mar 2017 19:48:53 +0300 |
parents | xml/en/docs/stream/ngx_stream_upstream_module.xml@a58b35cc0823 |
children | 25962922969a |
line wrap: on
line diff
copy from xml/en/docs/stream/ngx_stream_upstream_module.xml copy to xml/en/docs/stream/ngx_stream_upstream_hc_module.xml --- a/xml/en/docs/stream/ngx_stream_upstream_module.xml +++ b/xml/en/docs/stream/ngx_stream_upstream_hc_module.xml @@ -6,18 +6,26 @@ <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> -<module name="Module ngx_stream_upstream_module" - link="/en/docs/stream/ngx_stream_upstream_module.html" +<module name="Module ngx_stream_upstream_hc_module" + link="/en/docs/stream/ngx_stream_upstream_hc_module.html" lang="en" - rev="24"> + rev="1"> <section id="summary"> <para> -The <literal>ngx_stream_upstream_module</literal> module (1.9.0) -is used to define groups of servers that can be referenced -by the <link doc="ngx_stream_proxy_module.xml" id="proxy_pass"/> -directive. +The <literal>ngx_stream_upstream_hc_module</literal> module (1.9.0) +allows enabling periodic health checks of the servers in a +<link doc="ngx_stream_upstream_module.xml" id="upstream">group</link>. +The server group must reside in the +<link doc="ngx_stream_upstream_module.xml" id="zone">shared memory</link>. +</para> + +<para> +<note> +This module is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> </para> </section> @@ -27,47 +35,20 @@ directive. <para> <example> -upstream <emphasis>backend</emphasis> { - hash $remote_addr consistent; - - server backend1.example.com:12345 weight=5; - server backend2.example.com:12345; - server unix:/tmp/backend3; - - server backup1.example.com:12345 backup; - server backup2.example.com:12345 backup; -} - -server { - listen 12346; - proxy_pass <emphasis>backend</emphasis>; -} -</example> -</para> - -<para> -Dynamically configurable group, -available as part of our -<commercial_version>commercial subscription</commercial_version>: -<example> -resolver 10.0.0.1; - -upstream <emphasis>dynamic</emphasis> { - zone upstream_dynamic 64k; +upstream tcp { + zone upstream_tcp 64k; server backend1.example.com:12345 weight=5; server backend2.example.com:12345 fail_timeout=5s slow_start=30s; server 192.0.2.1:12345 max_fails=3; - server backend3.example.com:12345 resolve; - server backend4.example.com service=http resolve; server backup1.example.com:12345 backup; server backup2.example.com:12345 backup; } server { - listen 12346; - proxy_pass <emphasis>dynamic</emphasis>; + listen 12346; + proxy_pass tcp; health_check; } </example> @@ -78,420 +59,6 @@ server { <section id="directives" name="Directives"> -<directive name="upstream"> -<syntax block="yes"><value>name</value></syntax> -<default/> -<context>stream</context> - -<para> -Defines a group of servers. -Servers can listen on different ports. -In addition, servers listening on TCP and UNIX-domain sockets -can be mixed. -</para> - -<para> -Example: -<example> -upstream backend { - server backend1.example.com:12345 weight=5; - server 127.0.0.1:12345 max_fails=3 fail_timeout=30s; - server unix:/tmp/backend2; - server backend3.example.com:12345 resolve; - - server backup1.example.com:12345 backup; -} -</example> -</para> - -<para> -By default, connections are distributed between the servers using a -weighted round-robin balancing method. -In the above example, each 7 connections will be distributed as follows: -5 connections go to <literal>backend1.example.com:12345</literal> -and one connection to each of the second and third servers. -If an error occurs during communication with a server, the connection will -be passed to the next server, and so on until all of the functioning -servers will be tried. -If communication with all servers fails, the connection will be closed. -</para> - -</directive> - - -<directive name="server"> -<syntax><value>address</value> [<value>parameters</value>]</syntax> -<default/> -<context>upstream</context> - -<para> -Defines the <value>address</value> and other <value>parameters</value> -of a server. -The address can be specified as a domain name or IP address -with an obligatory port, or as a UNIX-domain socket path -specified after the “<literal>unix:</literal>” prefix. -A domain name that resolves to several IP addresses defines -multiple servers at once. -</para> - -<para> -The following parameters can be defined: -<list type="tag"> - -<tag-name id="weight"> -<literal>weight</literal>=<value>number</value> -</tag-name> -<tag-desc> -sets the weight of the server, by default, 1. -</tag-desc> - -<tag-name id="max_conns"> -<literal>max_conns</literal>=<value>number</value> -</tag-name> -<tag-desc> -limits the maximum <value>number</value> of simultaneous -connections to the proxied server (1.11.5). -Default value is zero, meaning there is no limit. -If the server group does not reside in the <link id="zone">shared memory</link>, -the limitation works per each worker process. -<note> -Prior to version 1.11.5, this parameter was available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</tag-desc> - -<tag-name id="max_fails"> -<literal>max_fails</literal>=<value>number</value> -</tag-name> -<tag-desc> -sets the number of unsuccessful attempts to communicate with the server -that should happen in the duration set by the <literal>fail_timeout</literal> -parameter to consider the server unavailable for a duration also set by the -<literal>fail_timeout</literal> parameter. -By default, the number of unsuccessful attempts is set to 1. -The zero value disables the accounting of attempts. -Here, an unsuccessful attempt is an error or timeout -while establishing a connection with the server. -</tag-desc> - -<tag-name id="fail_timeout"> -<literal>fail_timeout</literal>=<value>time</value> -</tag-name> -<tag-desc> -sets -<list type="bullet"> - -<listitem> -the time during which the specified number of unsuccessful attempts to -communicate with the server should happen to consider the server unavailable; -</listitem> - -<listitem> -and the period of time the server will be considered unavailable. -</listitem> - -</list> -By default, the parameter is set to 10 seconds. -</tag-desc> - -<tag-name id="backup"> -<literal>backup</literal> -</tag-name> -<tag-desc> -marks the server as a backup server. -Connections to the backup server will be passed -when the primary servers are unavailable. -</tag-desc> - -<tag-name id="down"> -<literal>down</literal> -</tag-name> -<tag-desc> -marks the server as permanently unavailable. -</tag-desc> - -</list> -</para> - -<para> -Additionally, -the following parameters are available as part of our -<commercial_version>commercial subscription</commercial_version>: -<list type="tag"> - -<tag-name id="resolve"> -<literal>resolve</literal> -</tag-name> -<tag-desc> -monitors changes of the IP addresses -that correspond to a domain name of the server, -and automatically modifies the upstream configuration -without the need of restarting nginx. -The server group must reside in the <link id="zone">shared memory</link>. -<para> -In order for this parameter to work, -the <link doc="ngx_stream_core_module.xml" id="resolver"/> directive -must be specified in the -<link doc="ngx_stream_core_module.xml" id="stream"/> block. -Example: -<example> -stream { - resolver 10.0.0.1; - - upstream u { - zone ...; - ... - server example.com:12345 resolve; - } -} -</example> -</para> -</tag-desc> - -<tag-name id="service"> -<literal>service</literal>=<value>name</value> -</tag-name> -<tag-desc> -enables resolving of DNS -<link url="https://tools.ietf.org/html/rfc2782">SRV</link> -records and sets the service <value>name</value> (1.9.13). -In order for this parameter to work, it is necessary to specify -the <link id="resolve"/> parameter for the server -and specify a hostname without a port number. -<para> -If the service name does not contain a dot (“<literal>.</literal>”), then -the <link url="https://tools.ietf.org/html/rfc2782">RFC</link>-compliant name -is constructed -and the TCP protocol is added to the service prefix. -For example, to look up the -<literal>_http._tcp.backend.example.com</literal> SRV record, -it is necessary to specify the directive: -<example> -server backend.example.com service=http resolve; -</example> -If the service name contains one or more dots, then the name is constructed -by joining the service prefix and the server name. -For example, to look up the <literal>_http._tcp.backend.example.com</literal> -and <literal>server1.backend.example.com</literal> SRV records, -it is necessary to specify the directives: -<example> -server backend.example.com service=_http._tcp resolve; -server example.com service=server1.backend resolve; -</example> -</para> - -<para> -Highest-priority SRV records -(records with the same lowest-number priority value) -are resolved as primary servers, -the rest of SRV records are resolved as backup servers. -If the <link id="backup"/> parameter is specified for the server, -high-priority SRV records are resolved as backup servers, -the rest of SRV records are ignored. -</para> -</tag-desc> - -<tag-name id="slow_start"> -<literal>slow_start</literal>=<value>time</value> -</tag-name> -<tag-desc> -sets the <value>time</value> during which the server will recover its weight -from zero to a nominal value, when unhealthy server becomes -<link id="health_check">healthy</link>, -or when the server becomes available after a period of time -it was considered <link id="fail_timeout">unavailable</link>. -Default value is zero, i.e. slow start is disabled. -<note> -The parameter cannot be used along with the -<link id="hash"/> load balancing method. -</note> -</tag-desc> - -</list> -</para> - -<para> -<note> -If there is only a single server in a group, <literal>max_fails</literal>, -<literal>fail_timeout</literal> and <literal>slow_start</literal> parameters -are ignored, and such a server will never be considered unavailable. -</note> -</para> - -</directive> - - -<directive name="zone"> -<syntax><value>name</value> [<value>size</value>]</syntax> -<default/> -<context>upstream</context> - -<para> -Defines the <value>name</value> and <value>size</value> of the shared -memory zone that keeps the group’s configuration and run-time state that are -shared between worker processes. -Several groups may share the same zone. -In this case, it is enough to specify the zone size only once. -</para> - -<para> -Additionally, -as part of our <commercial_version>commercial subscription</commercial_version>, -such groups allow changing the group membership -or modifying the settings of a particular server -without the need of restarting nginx. -The configuration is accessible via a special location -handled by -<link doc="../http/ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. -</para> - -</directive> - - -<directive name="state"> -<syntax><value>file</value></syntax> -<default/> -<context>upstream</context> -<appeared-in>1.9.7</appeared-in> - -<para> -Specifies a <value>file</value> that keeps the state -of the dynamically configurable group. -</para> - -<para> -Examples: -<example> -state /var/lib/nginx/state/servers.conf; # path for Linux -state /var/db/nginx/state/servers.conf; # path for FreeBSD -</example> -</para> - -<para> -The state is currently limited to the list of servers with their parameters. -The file is read when parsing the configuration and is updated each time -the upstream configuration is -<link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf">changed</link>. -Changing the file content directly should be avoided. -The directive cannot be used -along with the <link id="server"/> directive. -</para> - -<para> -<note> -Changes made during -<link doc="../control.xml" id="reconfiguration">configuration reload</link> -or <link doc="../control.xml" id="upgrade">binary upgrade</link> -can be lost. -</note> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="hash"> -<syntax><value>key</value> [<literal>consistent</literal>]</syntax> -<default/> -<context>upstream</context> - -<para> -Specifies a load balancing method for a server group -where client-server mapping is based on the hashed <value>key</value> value. -The <value>key</value> can contain text, variables, -and their combinations (1.11.2). -Usage example: -<example> -hash $remote_addr; -</example> -Note that adding or removing a server from the group -may result in remapping most of the keys to different servers. -The method is compatible with the -<link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached">Cache::Memcached</link> -Perl library. -</para> - -<para> -If the <literal>consistent</literal> parameter is specified, -the <link url="http://www.last.fm/user/RJ/journal/2007/04/10/392555/">ketama</link> -consistent hashing method will be used instead. -The method ensures that only a few keys -will be remapped to different servers -when a server is added to or removed from the group. -This helps to achieve a higher cache hit ratio for caching servers. -The method is compatible with the -<link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached%3A%3AFast">Cache::Memcached::Fast</link> -Perl library with the <value>ketama_points</value> parameter set to 160. -</para> - -</directive> - - -<directive name="least_conn"> -<syntax/> -<default/> -<context>upstream</context> - -<para> -Specifies that a server group should use a load balancing method -where a connection -is passed to the server with the least number of active connections, -taking into account weights of servers. -If there are several such servers, they are tried in turn using a -weighted round-robin balancing method. -</para> - -</directive> - - -<directive name="least_time"> -<syntax> - <literal>connect</literal> | - <literal>first_byte</literal> | - <literal>last_byte</literal> - [<literal>inflight</literal>]</syntax> -<default/> -<context>upstream</context> - -<para> -Specifies that a group should use a load balancing method where a connection -is passed to the server with the least average time and -least number of active connections, taking into account weights of servers. -If there are several such servers, they are tried in turn using a -weighted round-robin balancing method. -</para> - -<para> -If the <literal>connect</literal> parameter is specified, -time to connect to the upstream server is used. -If the <literal>first_byte</literal> parameter is specified, -time to receive the first byte of data is used. -If the <literal>last_byte</literal> is specified, -time to receive the last byte of data is used. -If the <literal>inflight</literal> parameter is specified (1.11.6), -incomplete connections are also taken into account. -<note> -Prior to version 1.11.6, -incomplete connections were taken into account by default. -</note> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="health_check"> <syntax>[<value>parameters</value>]</syntax> <default/> @@ -499,7 +66,7 @@ This directive is available as part of o <para> Enables periodic health checks of the servers in a -<link id="upstream">group</link>. +<link doc="ngx_stream_upstream_module.xml" id="upstream">group</link>. </para> <para> @@ -576,7 +143,8 @@ parameters. <tag-desc> defines the port used when connecting to a server to perform a health check (1.9.7). -By default, equals the <link id="server"/> port. +By default, equals the +<link doc="ngx_stream_upstream_module.xml" id="server"/> port. </tag-desc> <tag-name id="health_check_udp"> @@ -614,7 +182,8 @@ and referenced in the <literal>match</li </para> <para> -The server group must reside in the <link id="zone">shared memory</link>. +The server group must reside in the +<link doc="ngx_stream_upstream_module.xml" id="zone">shared memory</link>. </para> <para> @@ -623,13 +192,6 @@ a single failure of any check will make considered unhealthy. </para> -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - </directive> @@ -645,13 +207,6 @@ Overrides the value for health checks. </para> -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - </directive> @@ -747,79 +302,8 @@ bytes of data obtained from the server a </note> </para> -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - </directive> </section> - -<section id="variables" name="Embedded Variables"> - -<para> -The <literal>ngx_stream_upstream_module</literal> module -supports the following embedded variables: -<list type="tag"> - -<tag-name id="var_upstream_addr"><var>$upstream_addr</var></tag-name> -<tag-desc> -keeps the IP address and port, -or the path to the UNIX-domain socket of the upstream server (1.11.4). -If several servers were contacted during proxying, -their addresses are separated by commas, e.g. -“<literal>192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock</literal>”. -</tag-desc> - -<tag-name id="var_upstream_bytes_sent"><var>$upstream_bytes_sent</var></tag-name> -<tag-desc> -number of bytes sent to an upstream server (1.11.4). -Values from several connections -are separated by commas like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -<tag-name id="var_upstream_bytes_received"><var>$upstream_bytes_received</var></tag-name> -<tag-desc> -number of bytes received from an upstream server (1.11.4). -Values from several connections -are separated by commas like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -<tag-name id="var_upstream_connect_time"><var>$upstream_connect_time</var></tag-name> -<tag-desc> -time to connect to the upstream server (1.11.4); -the time is kept in seconds with millisecond resolution. -Times of several connections -are separated by commas like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -<tag-name id="var_upstream_first_byte_time"><var>$upstream_first_byte_time</var></tag-name> -<tag-desc> -time to receive the first byte of data (1.11.4); -the time is kept in seconds with millisecond resolution. -Times of several connections -are separated by commas like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -<tag-name id="var_upstream_session_time"><var>$upstream_session_time</var></tag-name> -<tag-desc> -session duration in seconds with millisecond resolution (1.11.4). -Times of several connections -are separated by commas like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -</list> -</para> - -</section> - </module>