Mercurial > hg > nginx-site
changeset 1450:f5b5eefc43cb
Updated commercial docs for the upcoming release.
| author | Ruslan Ermilov <ru@nginx.com> |
|---|---|
| date | Thu, 09 Apr 2015 19:18:54 +0300 |
| parents | c79501e16e26 |
| children | 45869c3eb9c3 |
| files | xml/en/GNUmakefile xml/en/docs/http/ngx_http_status_module.xml xml/en/docs/http/ngx_http_upstream_conf_module.xml xml/en/docs/http/ngx_http_upstream_module.xml xml/en/docs/index.xml xml/en/docs/ngx_core_module.xml xml/en/docs/stream/ngx_stream_core_module.xml xml/en/docs/stream/ngx_stream_proxy_module.xml xml/en/docs/stream/ngx_stream_ssl_module.xml xml/en/docs/stream/ngx_stream_upstream_module.xml xml/ru/GNUmakefile xml/ru/docs/http/ngx_http_status_module.xml xml/ru/docs/http/ngx_http_upstream_conf_module.xml xml/ru/docs/http/ngx_http_upstream_module.xml xml/ru/docs/index.xml xml/ru/docs/ngx_core_module.xml |
| diffstat | 16 files changed, 1694 insertions(+), 2847 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -80,6 +80,7 @@ REFS = \ http/ngx_http_stub_status_module \ http/ngx_http_sub_module \ http/ngx_http_upstream_module \ + http/ngx_http_upstream_conf_module \ http/ngx_http_userid_module \ http/ngx_http_uwsgi_module \ http/ngx_http_xslt_module \ @@ -92,6 +93,7 @@ REFS = \ mail/ngx_mail_ssl_module \ stream/ngx_stream_core_module \ stream/ngx_stream_proxy_module \ + stream/ngx_stream_ssl_module \ stream/ngx_stream_upstream_module \ TOP = \
--- a/xml/en/docs/http/ngx_http_status_module.xml +++ b/xml/en/docs/http/ngx_http_status_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_http_status_module" link="/en/docs/http/ngx_http_status_module.html" lang="en" - rev="4"> + rev="6"> <section id="summary"> @@ -32,40 +32,58 @@ This module is available as part of our <para> <example> -upstream <emphasis>backend</emphasis> { - <emphasis>zone</emphasis> upstream_backend 64k; +http { + upstream <emphasis>backend</emphasis> { + <emphasis>zone</emphasis> http_backend 64k; + + server backend1.example.com weight=5; + server backend2.example.com; + } + + proxy_cache_path /data/nginx/cache_backend keys_zone=<emphasis>cache_backend</emphasis>:10m; + + server { + server_name backend.example.com; + + location / { + proxy_pass http://backend; + proxy_cache cache_backend; - server backend1.example.com weight=5; - server backend2.example.com; + health_check; + } + + <emphasis>status_zone server_backend;</emphasis> + } + + server { + listen 127.0.0.1; + + location /upstream_conf { + upstream_conf; + } + + location /status { + status; + } + + location = /status.html { + } + } } -proxy_cache_path /data/nginx/cache_backend keys_zone=<emphasis>cache_backend</emphasis>:10m; - -server { - server_name backend.example.com; +stream { + upstream <emphasis>backend</emphasis> { + <emphasis>zone</emphasis> stream_backend 64k; - location / { - proxy_pass http://backend; - proxy_cache cache_backend; - - health_check; + server backend1.example.com:12345 weight=5; + server backend2.example.com:12345; } - <emphasis>status_zone server_backend;</emphasis> -} - -server { - listen 127.0.0.1; - - location /upstream_conf { - upstream_conf; - } - - location /status { - status; - } - - location = /status.html { + server { + listen 127.0.0.1:12345; + proxy_pass backend; + <emphasis>status_zone server_backend;</emphasis> + health_check; } } </example> @@ -81,6 +99,11 @@ http://127.0.0.1/status/upstreams http://127.0.0.1/status/upstreams/backend http://127.0.0.1/status/upstreams/backend/1 http://127.0.0.1/status/upstreams/backend/1/weight +http://127.0.0.1/status/stream +http://127.0.0.1/status/stream/upstreams +http://127.0.0.1/status/stream/upstreams/backend +http://127.0.0.1/status/stream/upstreams/backend/1 +http://127.0.0.1/status/stream/upstreams/backend/1/weight </example> </para> @@ -138,9 +161,11 @@ then “<literal>ngx_status_jsonp_callback</literal>” is used. <para> Enables collection of virtual -<link doc="ngx_http_core_module.xml" id="server"/> -status information in the specified <value>zone</value>. -Several virtual servers may share the same zone. +<link doc="ngx_http_core_module.xml" id="server">http</link> +or +<link doc="../stream/ngx_stream_core_module.xml" id="server">stream</link> +(1.7.11) server status information in the specified <value>zone</value>. +Several servers may share the same zone. </para> </directive> @@ -157,7 +182,7 @@ The following status information is prov <tag-name id="version"><literal>version</literal></tag-name> <tag-desc> Version of the provided data set. -The current version is 4. +The current version is 5. </tag-desc> <tag-name><literal>nginx_version</literal></tag-name> @@ -170,6 +195,12 @@ Version of nginx. The address of the server that accepted status request. </tag-desc> +<tag-name id="generation"><literal>generation</literal></tag-name> +<tag-desc> +The total number of configuration +<link doc="../control.xml" id="reconfiguration">reloads</link>. +</tag-desc> + <tag-name id="load_timestamp"><literal>load_timestamp</literal></tag-name> <tag-desc> Time of the last reload of configuration, in milliseconds since Epoch. @@ -180,6 +211,19 @@ Time of the last reload of configuration Current time in milliseconds since Epoch. </tag-desc> +<tag-name id="processes"><literal>processes</literal></tag-name> +<tag-desc> +<list type="tag"> + +<tag-name id="respawned"><literal>respawned</literal></tag-name> +<tag-desc> +The total number of abnormally terminated and respawned +child processes. +</tag-desc> + +</list> +</tag-desc> + <tag-name><literal>connections</literal></tag-name> <tag-desc> <list type="tag"> @@ -330,11 +374,13 @@ or The current number of active connections. </tag-desc> +<!-- <tag-name><literal>keepalive</literal></tag-name> <tag-desc> The current number of idle <link doc="ngx_http_upstream_module.xml" id="keepalive"/> connections. </tag-desc> +--> <tag-name id="max_conns"><literal>max_conns</literal></tag-name> <tag-desc> @@ -451,6 +497,26 @@ The time (in milliseconds since Epoch) when the server was last selected to process a request (1.7.5). </tag-desc> +<tag-name id="header_time"><literal>header_time</literal></tag-name> +<tag-desc> +The average time to get the +<link doc="ngx_http_upstream_module.xml" id="var_upstream_header_time">response +header</link> from the server (1.7.10). +The field is available when using the +<link doc="ngx_http_upstream_module.xml" id="least_time"/> +load balancing method. +</tag-desc> + +<tag-name id="response_time"><literal>response_time</literal></tag-name> +<tag-desc> +The average time to get the +<link doc="ngx_http_upstream_module.xml" id="var_upstream_response_time">full +response</link> from the server (1.7.10). +The field is available when using the +<link doc="ngx_http_upstream_module.xml" id="least_time"/> +load balancing method. +</tag-desc> + </list> </tag-desc> @@ -537,6 +603,206 @@ The total number of bytes written to the </list> </tag-desc> +<tag-name id="stream"><literal>stream</literal></tag-name> +<tag-desc> + +<list type="tag"> +<tag-name><literal>server_zones</literal></tag-name> +<tag-desc> +For each <link id="status_zone"/>: +<list type="tag"> + +<tag-name><literal>processing</literal></tag-name> +<tag-desc> +The number of +client connections that are currently being processed. +</tag-desc> + +<tag-name><literal>connections</literal></tag-name> +<tag-desc> +The total number of +connections accepted from clients. +</tag-desc> + +<tag-name><literal>received</literal></tag-name> +<tag-desc> +The total number of bytes received from clients. +</tag-desc> + +<tag-name><literal>sent</literal></tag-name> +<tag-desc> +The total number of bytes sent to clients. +</tag-desc> + +</list> +</tag-desc> + +<tag-name><literal>upstreams</literal></tag-name> +<tag-desc> +For each +<link doc="../stream/ngx_stream_upstream_module.xml" id="server"/> +in the +<link doc="../stream/ngx_stream_upstream_module.xml" id="zone">dynamically +configurable</link> +<link doc="../stream/ngx_stream_upstream_module.xml" id="upstream">group</link>, +the following data are provided: +<list type="tag"> + +<tag-name><literal>id</literal></tag-name> +<tag-desc> +The ID of the server. +</tag-desc> + +<tag-name><literal>server</literal></tag-name> +<tag-desc> +An +<link doc="../stream/ngx_stream_upstream_module.xml" id="server">address</link> +of the server. +</tag-desc> + +<tag-name><literal>backup</literal></tag-name> +<tag-desc> +A boolean value indicating whether the server is a +<link doc="../stream/ngx_stream_upstream_module.xml" id="backup"/> +server. +</tag-desc> + +<tag-name><literal>weight</literal></tag-name> +<tag-desc> +<link doc="../stream/ngx_stream_upstream_module.xml" id="weight">Weight</link> +of the server. +</tag-desc> + +<tag-name><literal>state</literal></tag-name> +<tag-desc> +Current state, which may be one of +“<literal>up</literal>”, +“<literal>down</literal>”, +“<literal>unavail</literal>”, +or +“<literal>unhealthy</literal>”. +</tag-desc> + +<tag-name><literal>active</literal></tag-name> +<tag-desc> +The current number of connections. +</tag-desc> + +<tag-name><literal>connections</literal></tag-name> +<tag-desc> +The total number of +client connections forwarded to this server. +</tag-desc> + +<tag-name><literal>connect_time</literal></tag-name> +<tag-desc> +The average time to connect to the upstream server. +The field is available when using the +<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/> +load balancing method. +</tag-desc> + +<tag-name><literal>first_byte_time</literal></tag-name> +<tag-desc> +The average time to receive the first byte of data. +The field is available when using the +<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/> +load balancing method. +</tag-desc> + +<tag-name><literal>response_time</literal></tag-name> +<tag-desc> +The average time to receive the last byte of data. +The field is available when using the +<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/> +load balancing method. +</tag-desc> + +<tag-name><literal>sent</literal></tag-name> +<tag-desc> +The total number of bytes sent to this server. +</tag-desc> + +<tag-name><literal>received</literal></tag-name> +<tag-desc> +The total number of bytes received from this server. +</tag-desc> + +<tag-name><literal>fails</literal></tag-name> +<tag-desc> +The total number of +unsuccessful attempts to communicate with the server. +</tag-desc> + +<tag-name><literal>unavail</literal></tag-name> +<tag-desc> +How many times +the server became unavailable for client connections +(state “<literal>unavail</literal>”) +due to the number of unsuccessful attempts reaching the +<link doc="../stream/ngx_stream_upstream_module.xml" id="max_fails"/> +threshold. +</tag-desc> + +<tag-name><literal>health_checks</literal></tag-name> +<tag-desc> +<list type="tag"> + +<tag-name><literal>checks</literal></tag-name> +<tag-desc> +The total number of +<link doc="../stream/ngx_stream_upstream_module.xml" id="health_check">health check</link> +requests made. +</tag-desc> + +<tag-name><literal>fails</literal></tag-name> +<tag-desc> +The number of failed health checks. +</tag-desc> + +<tag-name><literal>unhealthy</literal></tag-name> +<tag-desc> +How many times +the server became unhealthy (state “<literal>unhealthy</literal>”). +</tag-desc> + +<tag-name><literal>last_passed</literal></tag-name> +<tag-desc> +Boolean indicating +if the last health check request was successful and passed +<link doc="../stream/ngx_stream_upstream_module.xml" id="match">tests</link>. +</tag-desc> + +</list> +</tag-desc> + +<tag-name><literal>downtime</literal></tag-name> +<tag-desc> +Total time +the server was in the “<literal>unavail</literal>” +and “<literal>unhealthy</literal>” states. +</tag-desc> + +<tag-name><literal>downstart</literal></tag-name> +<tag-desc> +The time (in milliseconds since Epoch) +when the server became +“<literal>unavail</literal>” +or “<literal>unhealthy</literal>”. +</tag-desc> + +<tag-name><literal>selected</literal></tag-name> +<tag-desc> +The time (in milliseconds since Epoch) +when the server was last selected to process a connection. +</tag-desc> + +</list> +</tag-desc> + +</list> +</tag-desc> + </list> </para> @@ -548,6 +814,36 @@ The total number of bytes written to the <list type="bullet"> <listitem> +The <literal>keepalive</literal> field of an upstream server +was removed in <link id="version"/> 5. +</listitem> + +<listitem> +The <link id="stream">stream</link> status data +were added in <link id="version"/> 5. +</listitem> + +<listitem> +The +<link id="generation"/> field +was added in <link id="version"/> 5. +</listitem> + +<listitem> +The +<link id="respawned"/> field in +<link id="processes"/> +was added in <link id="version"/> 5. +</listitem> + +<listitem> +The +<link id="header_time"/> and <link id="response_time"/> fields in +<link id="upstreams"/> +were added in <link id="version"/> 5. +</listitem> + +<listitem> The <link id="selected"/> field in <link id="upstreams"/>
copy from xml/en/docs/http/ngx_http_upstream_module.xml copy to xml/en/docs/http/ngx_http_upstream_conf_module.xml --- a/xml/en/docs/http/ngx_http_upstream_module.xml +++ b/xml/en/docs/http/ngx_http_upstream_conf_module.xml @@ -1,27 +1,27 @@ <?xml version="1.0"?> <!-- - Copyright (C) Igor Sysoev Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> -<module name="Module ngx_http_upstream_module" - link="/en/docs/http/ngx_http_upstream_module.html" +<module name="Module ngx_http_upstream_conf_module" + link="/en/docs/http/ngx_http_upstream_conf_module.html" lang="en" - rev="35"> + rev="1"> <section id="summary"> <para> -The <literal>ngx_http_upstream_module</literal> module -is used to define groups of servers that can be referenced -by the <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>, -<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>, -<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_pass"/>, -<link doc="ngx_http_scgi_module.xml" id="scgi_pass"/>, and -<link doc="ngx_http_memcached_module.xml" id="memcached_pass"/> directives. +The <literal>ngx_http_upstream_conf_module</literal> module +allows configuring upstream server groups on-the-fly +via a simple HTTP interface without the need of restarting nginx. +The +<link doc="ngx_http_upstream_module.xml" id="zone">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="zone">stream</link> +server group must reside in the shared memory. </para> </section> @@ -31,47 +31,15 @@ by the <link doc="ngx_http_proxy_module. <para> <example> -upstream <emphasis>backend</emphasis> { - server backend1.example.com weight=5; - server backend2.example.com:8080; - server unix:/tmp/backend3; +upstream backend { + zone upstream_backend 64k; - server backup1.example.com:8080 backup; - server backup2.example.com:8080 backup; + ... } server { - location / { - proxy_pass http://<emphasis>backend</emphasis>; - } -} -</example> -</para> - -<para> -Dynamically configurable group, -available as part of our -<commercial_version>commercial subscription</commercial_version>: -<example> -upstream <emphasis>dynamic</emphasis> { - zone upstream_dynamic 64k; - - server backend1.example.com weight=5; - server backend2.example.com:8080 fail_timeout=5s slow_start=30s; - server 192.0.2.1 max_fails=3; - - server backup1.example.com:8080 backup; - server backup2.example.com:8080 backup; -} - -server { - location / { - proxy_pass http://<emphasis>dynamic</emphasis>; - health_check; - } - location /upstream_conf { - upstream_conf; + <emphasis>upstream_conf</emphasis>; allow 127.0.0.1; deny all; } @@ -84,955 +52,6 @@ server { <section id="directives" name="Directives"> -<directive name="upstream"> -<syntax block="yes"><value>name</value></syntax> -<default/> -<context>http</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 weight=5; - server 127.0.0.1:8080 max_fails=3 fail_timeout=30s; - server unix:/tmp/backend3; - - server backup1.example.com backup; -} -</example> -</para> - -<para> -By default, requests are distributed between the servers using a -weighted round-robin balancing method. -In the above example, each 7 requests will be distributed as follows: -5 requests go to <literal>backend1.example.com</literal> -and one request to each of the second and third servers. -If an error occurs during communication with a server, the request will -be passed to the next server, and so on until all of the functioning -servers will be tried. -If a successful response could not be obtained from any of the servers, -the client will receive the result of the communication with the last server. -</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 optional port, or as a UNIX-domain socket path -specified after the “<literal>unix:</literal>” prefix. -If a port is not specified, the port 80 is used. -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_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. -What is considered an unsuccessful attempt is defined by the -<link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>, -<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>, -<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_next_upstream"/>, -<link doc="ngx_http_scgi_module.xml" id="scgi_next_upstream"/>, and -<link doc="ngx_http_memcached_module.xml" id="memcached_next_upstream"/> -directives. -</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. -It will be passed requests 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="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.5.9). -Default value is zero, meaning there is no limit. -</tag-desc> - -<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 (1.5.12). -<para> -In order for this parameter to work, -the <link doc="ngx_http_core_module.xml" id="resolver"/> directive -must be specified in the -<link doc="ngx_http_core_module.xml" id="http"/> block. -Example: -<example> -http { - resolver 10.0.0.1; - - upstream u { - zone ...; - ... - server example.com resolve; - } -} -</example> -</para> -</tag-desc> - -<tag-name id="route"> -<literal>route</literal>=<value>string</value> -</tag-name> -<tag-desc> -sets the server route name. -</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. -</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. -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 id="upstream_conf"/>. -</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> -<appeared-in>1.7.2</appeared-in> - -<para> -Specifies a load balancing method for a server group -where the client-server mapping is based on the hashed <value>key</value> value. -The <value>key</value> can contain text, variables, and their combinations. -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="ip_hash"> -<syntax/> -<default/> -<context>upstream</context> - -<para> -Specifies that a group should use a load balancing method where requests -are distributed between servers based on client IP addresses. -The first three octets of the client IPv4 address, or the entire IPv6 address, -are used as a hashing key. -The method ensures that requests from the same client will always be -passed to the same server except when this server is unavailable. -In the latter case client requests will be passed to another server. -Most probably, it will always be the same server as well. -<note> -IPv6 addresses are supported starting from versions 1.3.2 and 1.2.2. -</note> -</para> - -<para> -If one of the servers needs to be temporarily removed, it should -be marked with the <literal>down</literal> parameter in -order to preserve the current hashing of client IP addresses. -</para> - -<para> -Example: -<example> -upstream backend { - ip_hash; - - server backend1.example.com; - server backend2.example.com; - server backend3.example.com <emphasis>down</emphasis>; - server backend4.example.com; -} -</example> -</para> - -<para> -<note> -Until versions 1.3.1 and 1.2.2, it was not possible to specify a weight for -servers using the <literal>ip_hash</literal> load balancing method. -</note> -</para> - -</directive> - - -<directive name="keepalive"> -<syntax><value>connections</value></syntax> -<default/> -<context>upstream</context> -<appeared-in>1.1.4</appeared-in> - -<para> -Activates the cache for connections to upstream servers. -</para> - -<para> -The <value>connections</value> parameter sets the maximum number of -idle keepalive connections to upstream servers that are preserved in -the cache of each worker process. -When this number is exceeded, the least recently used connections -are closed. -<note> -It should be particularly noted that the <literal>keepalive</literal> directive -does not limit the total number of connections to upstream servers -that an nginx worker process can open. -The <value>connections</value> parameter should be set to a number small enough -to let upstream servers process new incoming connections as well. -</note> -</para> - -<para> -Example configuration of memcached upstream with keepalive connections: -<example> -upstream memcached_backend { - server 127.0.0.1:11211; - server 10.0.0.2:11211; - - keepalive 32; -} - -server { - ... - - location /memcached/ { - set $memcached_key $uri; - memcached_pass memcached_backend; - } - -} -</example> -</para> - -<para> -For HTTP, the <link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/> -directive should be set to “<literal>1.1</literal>” -and the <header>Connection</header> header field should be cleared: -<example> -upstream http_backend { - server 127.0.0.1:8080; - - keepalive 16; -} - -server { - ... - - location /http/ { - proxy_pass http://http_backend; - proxy_http_version 1.1; - proxy_set_header Connection ""; - ... - } -} -</example> -</para> - -<para> -<note> -Alternatively, HTTP/1.0 persistent connections can be used by passing the -<header>Connection: Keep-Alive</header> header field to an upstream server, -though this method is not recommended. -</note> -</para> - -<para> -For FastCGI servers, it is required to set -<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_keep_conn"/> -for keepalive connections to work: -<example> -upstream fastcgi_backend { - server 127.0.0.1:9000; - - keepalive 8; -} - -server { - ... - - location /fastcgi/ { - fastcgi_pass fastcgi_backend; - fastcgi_keep_conn on; - ... - } -} -</example> -</para> - -<para> -<note> -When using load balancer methods other than the default -round-robin method, it is necessary to activate them before -the <literal>keepalive</literal> directive. -</note> - -<note> -SCGI and uwsgi protocols do not have a notion of keepalive connections. -</note> -</para> - -</directive> - - -<directive name="least_conn"> -<syntax/> -<default/> -<context>upstream</context> -<appeared-in>1.3.1</appeared-in> -<appeared-in>1.2.2</appeared-in> - -<para> -Specifies that a group should use a load balancing method where a request -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="health_check"> -<syntax>[<value>parameters</value>]</syntax> -<default/> -<context>location</context> - -<para> -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="tag"> - -<tag-name id="interval"> -<literal>interval</literal>=<value>time</value> -</tag-name> -<tag-desc> -sets the interval between two consecutive health checks, -by default, 5 seconds; -</tag-desc> - -<tag-name id="fails"> -<literal>fails</literal>=<value>number</value> -</tag-name> -<tag-desc> -sets the number of consecutive failed health checks of a particular server -after which this server will be considered unhealthy, -by default, 1; -</tag-desc> - -<tag-name id="passes"> -<literal>passes</literal>=<value>number</value> -</tag-name> -<tag-desc> -sets the number of consecutive passed health checks of a particular server -after which the server will be considered healthy, -by default, 1; -</tag-desc> - -<tag-name id="uri"> -<literal>uri</literal>=<value>uri</value> -</tag-name> -<tag-desc> -defines the URI used in health check requests, -by default, “<literal>/</literal>”; -</tag-desc> - -<tag-name id="hc_match"> -<literal>match</literal>=<value>name</value> -</tag-name> -<tag-desc> -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. -</tag-desc> - -</list> -</para> - -<para> -For example, -<example> -location / { - proxy_pass http://backend; - health_check; -} -</example> -will send “<literal>/</literal>” requests to each -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, 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 the status code of a response, -presence of certain header fields and their values, -and the body contents. -Tests are configured separately using the <link id="match"/> directive -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> -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> -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 be -considered unhealthy. -</para> - -<para> -<note> -Please note that most of the variables will have empty values -when used with health checks. -</note> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</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 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 ! 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 range from 200 to 399</tag-desc> - -<tag-name><literal>status ! 400-599;</literal></tag-name> -<tag-desc>status is not in the range from 400 to 599</tag-desc> - -<tag-name><literal>status 301-303 307;</literal></tag-name> -<tag-desc>status is either 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 matches all tests. -<note> -Only the first 256k of the response 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>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="queue"> -<syntax> -<value>number</value> -[<literal>timeout</literal>=<value>time</value>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.5.12</appeared-in> - -<para> -If an upstream server cannot be selected immediately -while processing a request, -and there are the servers in the group that have reached the -<link id="max_conns"/> limit, -the request will be placed into the queue. -The directive specifies the maximum number of requests that can be in the queue -at the same time. -If the queue is filled up, -or the server to pass the request to cannot been selected within -the time period specified in the <literal>timeout</literal> parameter, -an error will be returned to the client. -</para> - -<para> -The default value of the <literal>timeout</literal> parameter is 60 seconds. -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="sticky"> -<syntax> - <literal>cookie</literal> <value>name</value> - [<literal>expires=</literal><value>time</value>] - [<literal>domain=</literal><value>domain</value>] - [<literal>path=</literal><value>path</value>]</syntax> -<syntax> - <literal>route</literal> <value>$variable</value> ...</syntax> -<syntax> - <literal>learn</literal> - <literal>create=</literal><value>$variable</value> - <literal>lookup=</literal><value>$variable</value> - <literal>zone=</literal><value>name</value>:<value>size</value> - [<literal>timeout=</literal><value>time</value>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Enables session affinity, which causes requests from the same client to be -passed to the same server in a group of servers. -Three methods are available: -<list type="tag"> -<tag-name id="sticky_cookie"><literal>cookie</literal></tag-name> -<tag-desc> - -<para> -When the <literal>cookie</literal> method is used, information about the -designated server is passed in an HTTP cookie generated by nginx: -<example> -upstream backend { - server backend1.example.com; - server backend2.example.com; - - sticky cookie srv_id expires=1h domain=.example.com path=/; -} -</example> -</para> - -<para> -A request that comes from a client not yet bound to a particular server -is passed to the server selected by the configured balancing method. -Further requests with this cookie will be passed to the designated server. -If the designated server cannot process a request, the new server is -selected as if the client has not been bound yet. -</para> - -<para> -The first parameter sets the name of the cookie to be set or inspected. -Additional parameters may be as follows: -<list type="tag"> - -<tag-name><literal>expires</literal></tag-name> -<tag-desc> -Sets the time for which a browser should keep the cookie. -The special value <literal>max</literal> will cause the cookie to expire on -“<literal>31 Dec 2037 23:55:55 GMT</literal>”. -If the parameter is not specified, it will cause the cookie to expire at -the end of a browser session. -</tag-desc> - -<tag-name><literal>domain</literal></tag-name> -<tag-desc> -Defines the domain for which the cookie is set. -</tag-desc> - -<tag-name><literal>path</literal></tag-name> -<tag-desc> -Defines the path for which the cookie is set. -</tag-desc> - -</list> -If any parameters are omitted, the corresponding cookie fields are not set. -</para> -</tag-desc> - -<tag-name id="sticky_route"><literal>route</literal></tag-name> -<tag-desc> - -<para> -When the <literal>route</literal> method is used, proxied server assigns -client a route on receipt of the first request. -All subsequent requests from this client will carry routing information -in a cookie or URI. -This information is compared with the “<literal>route</literal>” parameter -of the <link id="server"/> directive to identify the server to which the -request should be proxied. -If the designated server cannot process a request, the new server is -selected by the configured balancing method as if there is no routing -information in the request. -</para> - -<para> -The parameters of the <literal>route</literal> method specify variables that -may contain routing information. -The first non-empty variable is used to find the matching server. -</para> - -<para> -Example: -<example> -map $cookie_jsessionid $route_cookie { - ~.+\.(?P<route>\w+)$ $route; -} - -map $request_uri $route_uri { - ~jsessionid=.+\.(?P<route>\w+)$ $route; -} - -upstream backend { - server backend1.example.com route=a; - server backend2.example.com route=b; - - sticky route $route_cookie $route_uri; -} -</example> -Here, the route is taken from the “<literal>JSESSIONID</literal>” cookie -if present in a request. -Otherwise, the route from the URI is used. -</para> - -</tag-desc> - -<tag-name id="sticky_learn"><literal>learn</literal></tag-name> -<tag-desc> -<para> -When the <literal>learn</literal> method (1.7.1) is used, nginx -analyzes upstream server responses and learns server-initiated sessions -usually passed in an HTTP cookie. -<example> -upstream backend { - server backend1.example.com:8080; - server backend2.example.com:8081; - - sticky learn - create=$upstream_cookie_sessionid - lookup=$cookie_sessionid - zone=client_sessions:1m; -} -</example> - -In the example, the upstream server creates a session by setting the -cookie “<literal>SESSIONID</literal>” in the response. -Further requests with this cookie will be passed to the same server. -If the server cannot process the request, the new server is -selected as if the client has not been bound yet. -</para> - -<para> -The parameters <literal>create</literal> and <literal>lookup</literal> -specify variables that indicate how new sessions are created and existing -sessions are searched, respectively. -Both parameters may be specified more than once, in which case the first -non-empty variable is used. -</para> - -<para> -Sessions are stored in a shared memory zone, whose <value>name</value> and -<value>size</value> are configured by the <literal>zone</literal> parameter. -One megabyte zone can store about 8000 sessions on the 64-bit platform. -The sessions that are not accessed during the time specified by the -<literal>timeout</literal> parameter get removed from the zone. -By default, <literal>timeout</literal> is set to 10 minutes. -</para> - -</tag-desc> -</list> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="sticky_cookie_insert"> -<syntax><value>name</value> -[<literal>expires=</literal><value>time</value>] -[<literal>domain=</literal><value>domain</value>] -[<literal>path=</literal><value>path</value>]</syntax> -<default/> -<context>upstream</context> - -<para> -This directive is obsolete since version 1.5.7. -An equivalent -<link id="sticky"/> directive with a new syntax should be used instead: -<note> -<literal>sticky cookie</literal> <value>name</value> -[<literal>expires=</literal><value>time</value>] -[<literal>domain=</literal><value>domain</value>] -[<literal>path=</literal><value>path</value>]; -</note> -</para> - -</directive> - - <directive name="upstream_conf"> <syntax/> <default/> @@ -1068,7 +87,7 @@ or viewing the group configuration. A configuration command consists of parameters passed as request arguments, for example: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic +http://127.0.0.1/upstream_conf?upstream=backend </example> </para> @@ -1078,6 +97,17 @@ The following parameters are supported: <list type="tag" compact="no"> <tag-name> +<literal>stream=</literal></tag-name> +<tag-desc> +Selects a +<link doc="../stream/ngx_stream_upstream_module.xml">stream</link> +upstream server group. +Without this parameter, selects an +<link doc="ngx_http_upstream_module.xml">http</link> +upstream server group. +</tag-desc> + +<tag-name> <literal>upstream=</literal><value>name</value></tag-name> <tag-desc> Selects a group to work with. @@ -1116,17 +146,27 @@ was also required to view, modify, or re <literal>server=</literal><value>address</value></tag-name> <tag-desc> Same as the “<literal>address</literal>” parameter -of the <link id="server"/> directive. +of the +<link doc="ngx_http_upstream_module.xml" id="server">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link> +upstream server. <para> When adding a server, it is possible to specify it as a domain name. In this case, changes of the IP addresses that correspond to a domain name will be monitored and automatically applied to the upstream configuration without the need of restarting nginx (1.7.2). -This requires the -<link doc="ngx_http_core_module.xml" id="resolver"/> directive in the -<link doc="ngx_http_core_module.xml" id="http"/> block. -See also -the <link id="resolve"/> parameter of the <link id="server"/> directive. +This requires the “<literal>resolver</literal>” directive in the +<link doc="ngx_http_core_module.xml" id="resolver">http</link> +or +<link doc="../stream/ngx_stream_core_module.xml" id="resolver">stream</link> +block. +See also the “<literal>resolve</literal>” parameter +of the +<link doc="ngx_http_upstream_module.xml" id="resolve">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="resolve">stream</link> +upstream server. </para> </tag-desc> @@ -1134,48 +174,75 @@ the <link id="resolve"/> parameter of th <literal>weight=</literal><value>number</value></tag-name> <tag-desc> Same as the “<literal>weight</literal>” parameter -of the <link id="server"/> directive. +of the +<link doc="ngx_http_upstream_module.xml" id="weight">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="weight">stream</link> +upstream server. </tag-desc> <tag-name> <literal>max_conns=</literal><value>number</value></tag-name> <tag-desc> Same as the “<literal>max_conns</literal>” parameter -of the <link id="server"/> directive. +of the +<link doc="ngx_http_upstream_module.xml" id="max_conns">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="max_conns">stream</link> +upstream server. </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. +of the +<link doc="ngx_http_upstream_module.xml" id="max_fails">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="max_fails">stream</link> +upstream server. </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. +of the +<link doc="ngx_http_upstream_module.xml" id="fail_timeout">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="fail_timeout">stream</link> +upstream server. </tag-desc> <tag-name> <literal>slow_start=</literal><value>time</value></tag-name> <tag-desc> Same as the “<literal>slow_start</literal>” parameter -of the <link id="server"/> directive. +of the +<link doc="ngx_http_upstream_module.xml" id="slow_start">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="slow_start">stream</link> +upstream server. </tag-desc> <tag-name> <literal>down=</literal></tag-name> <tag-desc> Same as the “<literal>down</literal>” parameter -of the <link id="server"/> directive. +of the +<link doc="ngx_http_upstream_module.xml" id="down">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link> +upstream server. </tag-desc> <tag-name id="drain"><literal>drain=</literal></tag-name> <tag-desc> -Puts the upstream server in the “draining” mode (1.7.5). -In this mode, only requests <link id="sticky">bound</link> to the server +Puts the +<link doc="ngx_http_upstream_module.xml">http</link> +upstream server in the “draining” mode (1.7.5). +In this mode, only requests of the +<link doc="ngx_http_upstream_module.xml" id="sticky">bound</link> to the server will be proxied to it. </tag-desc> @@ -1183,20 +250,26 @@ will be proxied to it. <literal>up=</literal></tag-name> <tag-desc> The opposite of the “<literal>down</literal>” parameter -of the <link id="server"/> directive. +of the +<link doc="ngx_http_upstream_module.xml" id="down">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link> +upstream server. </tag-desc> <tag-name> <literal>route=</literal><value>string</value></tag-name> <tag-desc> -Same as the “<literal>route</literal>” parameter -of the <link id="server"/> directive. +Same as the “<literal>route</literal>” parameter of the +<link doc="ngx_http_upstream_module.xml" id="route">http</link> +upstream server. </tag-desc> </list> -The first two parameters select an object. -This can be either the whole group or a specific server. +The first three parameters select an object. +This can be either the whole http or stream upstream server group, +or a specific server. Without other parameters, the configuration of the selected group or server is shown. </para> @@ -1204,12 +277,12 @@ group or server is shown. <para> For example, to view the configuration of the whole group, send: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic +http://127.0.0.1/upstream_conf?upstream=backend </example> To view the configuration of a specific server, also specify its ID: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42 +http://127.0.0.1/upstream_conf?upstream=backend&id=42 </example> </para> @@ -1217,158 +290,61 @@ http://127.0.0.1/upstream_conf?upstream= To add a new server, 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). +parameters set to their default values (see the +<link doc="ngx_http_upstream_module.xml" id="server">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link> +“<literal>server</literal>” directive). </para> <para> For example, to add a new primary server, send: <example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080 +http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080 </example> To add a new backup server, send: <example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&backup=&server=127.0.0.1:8080 +http://127.0.0.1/upstream_conf?add=&upstream=backend&backup=&server=127.0.0.1:8080 </example> To add a new primary server, set its parameters to non-default values and mark it as “<literal>down</literal>”, send: <example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080&weight=2&down= +http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080&weight=2&down= </example> -</para> -<para> To remove a server, specify its ID: <example> -http://127.0.0.1/upstream_conf?remove=&upstream=dynamic&id=42 +http://127.0.0.1/upstream_conf?remove=&upstream=backend&id=42 </example> -</para> -<para> To mark an existing server as “<literal>down</literal>”, send: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&down= +http://127.0.0.1/upstream_conf?upstream=backend&id=42&down= </example> To modify the address of an existing server, send: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&server=192.0.2.3:8123 +http://127.0.0.1/upstream_conf?upstream=backend&id=42&server=192.0.2.3:8123 </example> To modify other parameters of an existing server, send: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&max_fails=3&weight=4 +http://127.0.0.1/upstream_conf?upstream=backend&id=42&max_fails=3&weight=4 </example> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> +The above examples are for an +<link doc="ngx_http_upstream_module.xml">http</link> +upstream server group. +Similar examples for a +<link doc="../stream/ngx_stream_upstream_module.xml">stream</link> +upstream server group require the “<literal>stream=</literal>” parameter. </para> </directive> </section> - -<section id="variables" name="Embedded Variables"> - -<para> -The <literal>ngx_http_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. -If several servers were contacted during request processing, -their addresses are separated by commas, e.g. -“<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock</literal>”. -If an internal redirect from one server group to another happens, -initiated by -<header>X-Accel-Redirect</header> or -<link doc="ngx_http_core_module.xml" id="error_page"/>, -then the server addresses from different groups are separated by colons, e.g. -“<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80</literal>”. -</tag-desc> - -<tag-name id="var_upstream_cache_status"><var>$upstream_cache_status</var> -</tag-name> -<tag-desc> -keeps the status of accessing a response cache (0.8.3). -The status can be either “<literal>MISS</literal>”, -“<literal>BYPASS</literal>”, “<literal>EXPIRED</literal>”, -“<literal>STALE</literal>”, “<literal>UPDATING</literal>”, -“<literal>REVALIDATED</literal>”, or “<literal>HIT</literal>”. -</tag-desc> - -<tag-name id="var_upstream_cookie_"><var>$upstream_cookie_</var><value>name</value> -</tag-name> -<tag-desc> -cookie with the specified <value>name</value> sent by the upstream server -in the <header>Set-Cookie</header> response header field (1.7.1). -Only the cookies from the response of the last server are saved. -</tag-desc> - -<tag-name id="var_upstream_header_time"><var>$upstream_header_time</var> -</tag-name> -<tag-desc> -keeps time -spent on receiving the response header from the upstream server (1.7.10); -the time is kept in seconds with millisecond resolution. -Times of several responses -are separated by commas and colons like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -<tag-name id="var_upstream_http_"><var>$upstream_http_</var><value>name</value></tag-name> -<tag-desc> -keep server response header fields. -For example, the <header>Server</header> response header field -is available through the <var>$upstream_http_server</var> variable. -The rules of converting header field names to variable names are the same -as for the variables that start with the -“<link doc="ngx_http_core_module.xml" id="var_http_">$http_</link>” prefix. -Only the header fields from the response of the last server are saved. -</tag-desc> - -<tag-name id="var_upstream_response_length"><var>$upstream_response_length</var> -</tag-name> -<tag-desc> -keeps the length of the response obtained from the upstream server (0.7.27); -the length is kept in bytes. -Lengths of several responses -are separated by commas and colons like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -<tag-name id="var_upstream_response_time"><var>$upstream_response_time</var> -</tag-name> -<tag-desc> -keeps time spent on receiving the response from the upstream server; -the time is kept in seconds with millisecond resolution. -Times of several responses -are separated by commas and colons like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -<tag-name id="var_upstream_status"><var>$upstream_status</var></tag-name> -<tag-desc> -keeps status code of the response obtained from the upstream server. -Status codes of several responses -are separated by commas and colons like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -</list> -</para> - -</section> - </module>
--- a/xml/en/docs/http/ngx_http_upstream_module.xml +++ b/xml/en/docs/http/ngx_http_upstream_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_upstream_module" link="/en/docs/http/ngx_http_upstream_module.html" lang="en" - rev="35"> + rev="36"> <section id="summary"> @@ -53,12 +53,15 @@ 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; server backend1.example.com weight=5; server backend2.example.com:8080 fail_timeout=5s slow_start=30s; server 192.0.2.1 max_fails=3; + server backend3.example.com resolve; server backup1.example.com:8080 backup; server backup2.example.com:8080 backup; @@ -69,12 +72,6 @@ server { proxy_pass http://<emphasis>dynamic</emphasis>; health_check; } - - location /upstream_conf { - upstream_conf; - allow 127.0.0.1; - deny all; - } } </example> </para> @@ -298,7 +295,8 @@ Such groups allow changing the group mem 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 id="upstream_conf"/>. +handled by +<link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. </para> <para> @@ -528,6 +526,39 @@ weighted round-robin balancing method. </directive> +<directive name="least_time"> +<syntax><literal>header</literal> | <literal>last_byte</literal></syntax> +<default/> +<context>upstream</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies that a group should use a load balancing method where a request +is passed to the server with the least average response 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>header</literal> parameter is specified, +time to receive the +<link id="var_upstream_header_time">response header</link> is used. +If the <literal>last_byte</literal> parameter is specified, +time to receive the <link id="var_upstream_response_time">full response</link> +is used. +</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/> @@ -836,6 +867,8 @@ This directive is available as part of o <literal>cookie</literal> <value>name</value> [<literal>expires=</literal><value>time</value>] [<literal>domain=</literal><value>domain</value>] + [<literal>httponly</literal>] + [<literal>secure</literal>] [<literal>path=</literal><value>path</value>]</syntax> <syntax> <literal>route</literal> <value>$variable</value> ...</syntax> @@ -883,23 +916,34 @@ The first parameter sets the name of the Additional parameters may be as follows: <list type="tag"> -<tag-name><literal>expires</literal></tag-name> +<tag-name><literal>expires=</literal><value>time</value></tag-name> <tag-desc> -Sets the time for which a browser should keep the cookie. +Sets the <value>time</value> for which a browser should keep the cookie. The special value <literal>max</literal> will cause the cookie to expire on “<literal>31 Dec 2037 23:55:55 GMT</literal>”. If the parameter is not specified, it will cause the cookie to expire at the end of a browser session. </tag-desc> -<tag-name><literal>domain</literal></tag-name> +<tag-name><literal>domain=</literal><value>domain</value></tag-name> <tag-desc> -Defines the domain for which the cookie is set. +Defines the <value>domain</value> for which the cookie is set. +</tag-desc> + +<tag-name><literal>httponly</literal></tag-name> +<tag-desc> +Adds the <literal>HttpOnly</literal> attribute to the cookie (1.7.11). </tag-desc> -<tag-name><literal>path</literal></tag-name> +<tag-name><literal>secure</literal></tag-name> <tag-desc> -Defines the path for which the cookie is set. +Adds the <literal>Secure</literal> attribute to the cookie (1.7.11). + +</tag-desc> + +<tag-name><literal>path=</literal><value>path</value></tag-name> +<tag-desc> +Defines the <value>path</value> for which the cookie is set. </tag-desc> </list> @@ -1032,247 +1076,6 @@ An equivalent </directive> - -<directive name="upstream_conf"> -<syntax/> -<default/> -<context>location</context> - -<para> -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 can be used to: -<list type="bullet"> - -<listitem>view the group configuration;</listitem> - -<listitem>view, modify, or remove a server;</listitem> - -<listitem>add a new server.</listitem> - -</list> -<note> -Since addresses in a group are not required to be unique, specific -servers in a group are referenced by their IDs. -IDs are assigned automatically and shown when adding a new server -or viewing the group configuration. -</note> -</para> - -<para> -A configuration command consists of parameters passed as request arguments, -for example: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic -</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 to work with. -This parameter is mandatory. -</tag-desc> - -<tag-name> -<literal>id=</literal><value>number</value></tag-name> -<tag-desc> -Selects a server for viewing, modifying, or removing. -</tag-desc> - -<tag-name> -<literal>remove=</literal></tag-name> -<tag-desc> -Removes a server from the group. -</tag-desc> - -<tag-name> -<literal>add=</literal></tag-name> -<tag-desc> -Adds a new server to the group. -</tag-desc> - -<tag-name> -<literal>backup=</literal></tag-name> -<tag-desc> -Required to add a backup server. -<note> -Before version 1.7.2, <literal>backup=</literal> -was also required to view, modify, or remove existing backup servers. -</note> -</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. -<para> -When adding a server, it is possible to specify it as a domain name. -In this case, changes of the IP addresses that correspond to a domain name -will be monitored and automatically applied to the upstream -configuration without the need of restarting nginx (1.7.2). -This requires the -<link doc="ngx_http_core_module.xml" id="resolver"/> directive in the -<link doc="ngx_http_core_module.xml" id="http"/> block. -See also -the <link id="resolve"/> parameter of the <link id="server"/> directive. -</para> -</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_conns=</literal><value>number</value></tag-name> -<tag-desc> -Same as the “<literal>max_conns</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>slow_start=</literal><value>time</value></tag-name> -<tag-desc> -Same as the “<literal>slow_start</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 id="drain"><literal>drain=</literal></tag-name> -<tag-desc> -Puts the upstream server in the “draining” mode (1.7.5). -In this mode, only requests <link id="sticky">bound</link> to the server -will be proxied to it. -</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> - -<tag-name> -<literal>route=</literal><value>string</value></tag-name> -<tag-desc> -Same as the “<literal>route</literal>” parameter -of the <link id="server"/> directive. -</tag-desc> - -</list> - -The first two parameters select an object. -This can be either the whole group or a specific server. -Without other parameters, the configuration of the selected -group or server is shown. -</para> - -<para> -For example, to view the configuration of the whole group, send: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic -</example> - -To view the configuration of a specific server, also specify its ID: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42 -</example> -</para> - -<para> -To add a new server, -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, send: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080 -</example> - -To add a new backup server, send: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&backup=&server=127.0.0.1:8080 -</example> - -To add a new primary server, -set its parameters to non-default values -and mark it as “<literal>down</literal>”, send: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080&weight=2&down= -</example> -</para> - -<para> -To remove a server, specify its ID: -<example> -http://127.0.0.1/upstream_conf?remove=&upstream=dynamic&id=42 -</example> -</para> - -<para> -To mark an existing server as “<literal>down</literal>”, send: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&down= -</example> - -To modify the address of an existing server, send: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&server=192.0.2.3:8123 -</example> - -To modify other parameters of an existing server, send: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&max_fails=3&weight=4 -</example> - -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - </section>
--- a/xml/en/docs/index.xml +++ b/xml/en/docs/index.xml @@ -8,7 +8,7 @@ <article name="nginx documentation" link="/en/docs/" lang="en" - rev="17" + rev="19" toc="no"> @@ -405,6 +405,11 @@ ngx_http_upstream_module</link> </listitem> <listitem> +<link doc="http/ngx_http_upstream_conf_module.xml"> +ngx_http_upstream_conf_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_userid_module.xml"> ngx_http_userid_module</link> </listitem> @@ -477,6 +482,11 @@ ngx_stream_proxy_module</link> </listitem> <listitem> +<link doc="stream/ngx_stream_ssl_module.xml"> +ngx_stream_ssl_module</link> +</listitem> + +<listitem> <link doc="stream/ngx_stream_upstream_module.xml"> ngx_stream_upstream_module</link> </listitem>
--- a/xml/en/docs/ngx_core_module.xml +++ b/xml/en/docs/ngx_core_module.xml @@ -10,7 +10,7 @@ <module name="Core functionality" link="/en/docs/ngx_core_module.html" lang="en" - rev="12"> + rev="13"> <section id="example" name="Example Configuration"> @@ -158,6 +158,7 @@ analysis using a system debugger. <default>logs/error.log error</default> <context>main</context> <context>http</context> +<context>stream</context> <context>server</context> <context>location</context> @@ -195,6 +196,12 @@ For <literal>debug</literal> logging to be built with <literal>--with-debug</literal>, see “<link doc="debugging_log.xml"/>”. </note> + +<note> +The directive can be specified on the +<literal>stream</literal> level +starting from version 1.7.11. +</note> </para> </directive>
--- a/xml/en/docs/stream/ngx_stream_core_module.xml +++ b/xml/en/docs/stream/ngx_stream_core_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_stream_core_module" link="/en/docs/stream/ngx_stream_core_module.html" lang="en" - rev="1"> + rev="2"> <section id="summary"> @@ -63,6 +63,7 @@ stream { <directive name="listen"> <syntax> <value>address</value>:<value>port</value> + [<literal>ssl</literal>] [<literal>bind</literal>] [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>] [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax> @@ -94,11 +95,16 @@ listen unix:/var/run/nginx.sock; </para> <para> -The directive supports the following parameters: +The <literal>ssl</literal> parameter (1.7.10) allows specifying that all +connections accepted on this port should work in SSL mode. +</para> +<para> +The <literal>listen</literal> directive +can have several additional parameters specific to socket-related system calls. <list type="tag"> -<tag-name id="bind"> +<tag-name> <literal>bind</literal> </tag-name> <tag-desc> @@ -118,7 +124,7 @@ are used then for a given a separate <c-func>bind</c-func> call will always be made. </tag-desc> -<tag-name id="ipv6only"> +<tag-name> <literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal> </tag-name> <tag-desc> @@ -130,7 +136,7 @@ This parameter is turned on by default. It can only be set once on start. </tag-desc> -<tag-name id="so_keepalive"> +<tag-name> <literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>] </tag-name> <tag-desc> @@ -157,6 +163,7 @@ will set the idle timeout (<c-def>TCP_KE leave the probe interval (<c-def>TCP_KEEPINTVL</c-def>) at its system default, and set the probes count (<c-def>TCP_KEEPCNT</c-def>) to 10 probes. </tag-desc> + </list> </para> @@ -168,6 +175,62 @@ Different servers must listen on differe </directive> +<directive name="resolver"> +<syntax> + <value>address</value> ... + [<literal>valid</literal>=<value>time</value>] + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> +<default/> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Configures name servers used to resolve names of upstream servers +into addresses, for example: +<example> +resolver 127.0.0.1 [::1]:5353; +</example> +An address can be specified as a domain name or IP address, +and an optional port. +If port is not specified, the port 53 is used. +Name servers are queried in a round-robin fashion. +</para> + +<para> +By default, nginx will look up both IPv4 and IPv6 addresses while resolving. +If looking up of IPv6 addresses is not desired, +the <literal>ipv6=off</literal> parameter can be specified. +</para> + +<para> +By default, nginx caches answers using the TTL value of a response. +The optional <literal>valid</literal> parameter allows overriding it: +<example> +resolver 127.0.0.1 [::1]:5353 valid=30s; +</example> +</para> + +</directive> + + +<directive name="resolver_timeout"> +<syntax><value>time</value></syntax> +<default>30s</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Sets a timeout for name resolution, for example: +<example> +resolver_timeout 5s; +</example> +</para> + +</directive> + + <directive name="server"> <syntax block="yes"/> <default/>
--- a/xml/en/docs/stream/ngx_stream_proxy_module.xml +++ b/xml/en/docs/stream/ngx_stream_proxy_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_stream_proxy_module" link="/en/docs/stream/ngx_stream_proxy_module.html" lang="en" - rev="2"> + rev="3"> <section id="summary"> @@ -83,6 +83,59 @@ buffer used for reading data from the cl </directive> +<directive name="proxy_next_upstream"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +When a connection to the proxied server cannot be established, determines +whether a client connection will be passed to the next server. +</para> + +<para> +Passing a connection to the next server can be limited by +<link id="proxy_next_upstream_tries">the number of tries</link> +and by <link id="proxy_next_upstream_timeout">time</link>. +</para> + +</directive> + + +<directive name="proxy_next_upstream_timeout"> +<syntax><value>time</value></syntax> +<default>0</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Limits the time allowed to pass a connection to the +<link id="proxy_next_upstream">next server</link>. +The <literal>0</literal> value turns off this limitation. +</para> + +</directive> + + +<directive name="proxy_next_upstream_tries"> +<syntax><value>number</value></syntax> +<default>0</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Limits the number of possible tries for passing a connection to the +<link id="proxy_next_upstream">next server</link>. +The <literal>0</literal> value turns off this limitation. +</para> + +</directive> + + <directive name="proxy_pass"> <syntax><value>address</value></syntax> <default/> @@ -111,6 +164,223 @@ In addition, an address can be specified </directive> +<directive name="proxy_ssl"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Enables the SSL/TLS protocol for connections to a proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_certificate"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies a <value>file</value> with the certificate in the PEM format +used for authentication to a proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_certificate_key"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies a <value>file</value> with the secret key in the PEM format +used for authentication to a proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_ciphers"> +<syntax><value>ciphers</value></syntax> +<default>DEFAULT</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies the enabled ciphers for connections to a proxied server. +The ciphers are specified in the format understood by the OpenSSL library. +</para> + +<para> +The full list can be viewed using the +“<command>openssl ciphers</command>” command. +</para> + +</directive> + + +<directive name="proxy_ssl_crl"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies a <value>file</value> with revoked certificates (CRL) +in the PEM format used to <link id="proxy_ssl_verify">verify</link> +the certificate of the proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_name"> +<syntax><value>name</value></syntax> +<default>host from proxy_pass</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Allows to override the server name used to +<link id="proxy_ssl_verify">verify</link> +the certificate of the proxied server and to be +<link id="proxy_ssl_server_name">passed through SNI</link> +when establishing a connection with the proxied server. +</para> + +<para> +By default, the host part of the <link id="proxy_pass"/> address is used. +</para> + +</directive> + + +<directive name="proxy_ssl_password_file"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies a <value>file</value> with passphrases for +<link id="proxy_ssl_certificate_key">secret keys</link> +where each passphrase is specified on a separate line. +Passphrases are tried in turn when loading the key. +</para> + +</directive> + + +<directive name="proxy_ssl_server_name"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Enables or disables passing of the server name through +<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">TLS +Server Name Indication extension</link> (SNI, RFC 6066) +when establishing a connection with the proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_session_reuse"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Determines whether SSL sessions can be reused when working with +the proxied server. +If the errors +“<literal>SSL3_GET_FINISHED:digest check failed</literal>” +appear in the logs, try disabling session reuse. +</para> + +</directive> + + +<directive name="proxy_ssl_protocols"> +<syntax> + [<literal>SSLv2</literal>] + [<literal>SSLv3</literal>] + [<literal>TLSv1</literal>] + [<literal>TLSv1.1</literal>] + [<literal>TLSv1.2</literal>]</syntax> +<default>SSLv3 TLSv1 TLSv1.1 TLSv1.2</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Enables the specified protocols for connections to a proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_trusted_certificate"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies a <value>file</value> with trusted CA certificates in the PEM format +used to <link id="proxy_ssl_verify">verify</link> +the certificate of the proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_verify"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Enables or disables verification of the proxied server certificate. +</para> + +</directive> + + +<directive name="proxy_ssl_verify_depth"> +<syntax><value>number</value></syntax> +<default>1</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Sets the verification depth in the proxied server certificates chain. +</para> + +</directive> + + <directive name="proxy_timeout"> <syntax><value>timeout</value></syntax> <default>10m</default>
new file mode 100644 --- /dev/null +++ b/xml/en/docs/stream/ngx_stream_ssl_module.xml @@ -0,0 +1,326 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_stream_ssl_module" + link="/en/docs/stream/ngx_stream_ssl_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_stream_ssl_module</literal> module (1.7.10) +provides the necessary support for a stream proxy server to work with +the SSL/TLS protocol. +</para> + +<para> +<note> +This module is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="ssl_certificate"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Specifies a file with the certificate in the PEM format for the given +server. +If intermediate certificates should be specified in addition to a primary +certificate, they should be specified in the same file in the following +order: the primary certificate comes first, then the intermediate certificates. +A secret key in the PEM format may be placed in the same file. +</para> + +</directive> + + +<directive name="ssl_certificate_key"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Specifies a file with the secret key in the PEM format for the given +server. +</para> + +</directive> + + +<directive name="ssl_ciphers"> +<syntax><value>ciphers</value></syntax> +<default>HIGH:!aNULL:!MD5</default> +<context>stream</context> +<context>server</context> + +<para> +Specifies the enabled ciphers. +The ciphers are specified in the format understood by the +OpenSSL library, for example: +<example> +ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; +</example> +</para> + +<para> +The full list can be viewed using the +“<command>openssl ciphers</command>” command. +</para> + +</directive> + + +<directive name="ssl_dhparam"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Specifies a <value>file</value> with DH parameters for EDH ciphers. +</para> + +</directive> + + +<directive name="ssl_ecdh_curve"> +<syntax><value>curve</value></syntax> +<default>prime256v1</default> +<context>stream</context> +<context>server</context> + +<para> +Specifies a <value>curve</value> for ECDHE ciphers. +</para> + +</directive> + + +<directive name="ssl_handshake_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>stream</context> +<context>server</context> + +<para> +Specifies a timeout for the SSL handshake to complete. +</para> + +</directive> + + +<directive name="ssl_password_file"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Specifies a <value>file</value> with passphrases for +<link id="ssl_certificate_key">secret keys</link> +where each passphrase is specified on a separate line. +Passphrases are tried in turn when loading the key. +</para> + +<para> +Example: +<example> +stream { + ssl_password_file /etc/keys/global.pass; + ... + + server { + listen 127.0.0.1:12345; + ssl_certificate_key /etc/keys/first.key; + } + + server { + listen 127.0.0.1:12346; + + # named pipe can also be used instead of a file + ssl_password_file /etc/keys/fifo; + ssl_certificate_key /etc/keys/second.key; + } +} +</example> +</para> + +</directive> + + +<directive name="ssl_prefer_server_ciphers"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> + +<para> +Specifies that server ciphers should be preferred over client ciphers +when the SSLv3 and TLS protocols are used. +</para> + +</directive> + + +<directive name="ssl_protocols"> +<syntax> + [<literal>SSLv2</literal>] + [<literal>SSLv3</literal>] + [<literal>TLSv1</literal>] + [<literal>TLSv1.1</literal>] + [<literal>TLSv1.2</literal>]</syntax> +<default>SSLv3 TLSv1 TLSv1.1 TLSv1.2</default> +<context>stream</context> +<context>server</context> + +<para> +Enables the specified protocols. +The <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> parameters work +only when the OpenSSL library of version 1.0.1 or higher is used. +</para> + +</directive> + + +<directive name="ssl_session_cache"> +<syntax> + <literal>off</literal> | + <literal>none</literal> | + [<literal>builtin</literal>[:<value>size</value>]] + [<literal>shared</literal>:<value>name</value>:<value>size</value>]</syntax> +<default>none</default> +<context>stream</context> +<context>server</context> + +<para> +Sets the types and sizes of caches that store session parameters. +A cache can be of any of the following types: +<list type="tag"> + +<tag-name><literal>off</literal></tag-name> +<tag-desc> +the use of a session cache is strictly prohibited: +nginx explicitly tells a client that sessions may not be reused. +</tag-desc> + +<tag-name><literal>none</literal></tag-name> +<tag-desc> +the use of a session cache is gently disallowed: +nginx tells a client that sessions may be reused, but does not +actually store session parameters in the cache. +</tag-desc> + +<tag-name><literal>builtin</literal></tag-name> +<tag-desc> +a cache built in OpenSSL; used by one worker process only. +The cache size is specified in sessions. +If size is not given, it is equal to 20480 sessions. +Use of the built-in cache can cause memory fragmentation. +</tag-desc> + +<tag-name><literal>shared</literal></tag-name> +<tag-desc> +a cache shared between all worker processes. +The cache size is specified in bytes; one megabyte can store +about 4000 sessions. +Each shared cache should have an arbitrary name. +A cache with the same name can be used in several +servers. +</tag-desc> + +</list> +</para> + +<para> +Both cache types can be used simultaneously, for example: +<example> +ssl_session_cache builtin:1000 shared:SSL:10m; +</example> +but using only shared cache without the built-in cache should +be more efficient. +</para> + +</directive> + + +<directive name="ssl_session_ticket_key"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Sets a <value>file</value> with the secret key used to encrypt +and decrypt TLS session tickets. +The directive is necessary if the same key has to be shared between +multiple servers. +By default, a randomly generated key is used. +</para> + +<para> +If several keys are specified, only the first key is +used to encrypt TLS session tickets. +This allows configuring key rotation, for example: +<example> +ssl_session_ticket_key current.key; +ssl_session_ticket_key previous.key; +</example> +</para> + +<para> +The <value>file</value> must contain 48 bytes of random data and can +be created using the following command: +<example> +openssl rand 48 > ticket.key +</example> +</para> + +</directive> + + +<directive name="ssl_session_tickets"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>stream</context> +<context>server</context> + +<para> +Enables or disables session resumption through +<link url="http://tools.ietf.org/html/rfc5077">TLS session tickets</link>. +</para> + +</directive> + + +<directive name="ssl_session_timeout"> +<syntax><value>time</value></syntax> +<default>5m</default> +<context>stream</context> +<context>server</context> + +<para> +Specifies a time during which a client may reuse the +session parameters stored in a cache. +</para> + +</directive> + +</section> + +</module>
--- a/xml/en/docs/stream/ngx_stream_upstream_module.xml +++ b/xml/en/docs/stream/ngx_stream_upstream_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_stream_upstream_module" link="/en/docs/stream/ngx_stream_upstream_module.html" lang="en" - rev="4"> + rev="5"> <section id="summary"> @@ -34,17 +34,23 @@ This module is available as part of our <para> <example> +resolver 10.0.0.1; + upstream <emphasis>backend</emphasis> { + zone upstream_backend 64k; + hash $remote_addr consistent; server backend1.example.com:12345 weight=5; server 127.0.0.1:12345 max_fails=3 fail_timeout=30s; - server unix:/tmp/backend3; + server unix:/tmp/backend2; + server backend3.example.com:12345 resolve; } server { listen 12346; proxy_pass <emphasis>backend</emphasis>; + health_check; } </example> </para> @@ -72,7 +78,8 @@ 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/backend3; + server unix:/tmp/backend2; + server backend3.example.com:12345 resolve; server backup1.example.com:12345 backup; } @@ -179,6 +186,34 @@ proxied server. Default value is zero, meaning there is no limit. </tag-desc> +<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 (1.7.10). +<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="slow_start"> <literal>slow_start</literal>=<value>time</value> </tag-name> @@ -204,6 +239,27 @@ are ignored, and such a server will neve </directive> +<directive name="zone"> +<syntax><value>name</value> <value>size</value></syntax> +<default/> +<context>upstream</context> +<appeared-in>1.7.10</appeared-in> + +<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. +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="hash"> <syntax><value>key</value> [<literal>consistent</literal>]</syntax> <default/> @@ -253,6 +309,229 @@ weighted round-robin balancing method. </directive> + +<directive name="least_time"> +<syntax><literal>connect</literal> | + <literal>first_byte</literal> | + <literal>last_byte</literal></syntax> +<default/> +<context>upstream</context> +<appeared-in>1.7.11</appeared-in> + +<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. +</para> + +</directive> + + +<directive name="health_check"> +<syntax>[<value>parameters</value>]</syntax> +<default/> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Enables periodic health checks of the servers in a +<link id="upstream">group</link>. +</para> + +<para> +The following optional parameters are supported: +<list type="tag"> + +<tag-name id="interval"> +<literal>interval</literal>=<value>time</value> +</tag-name> +<tag-desc> +sets the interval between two consecutive health checks, +by default, 5 seconds; +</tag-desc> + +<tag-name id="fails"> +<literal>fails</literal>=<value>number</value> +</tag-name> +<tag-desc> +sets the number of consecutive failed health checks of a particular server +after which this server will be considered unhealthy, +by default, 1; +</tag-desc> + +<tag-name id="passes"> +<literal>passes</literal>=<value>number</value> +</tag-name> +<tag-desc> +sets the number of consecutive passed health checks of a particular server +after which the server will be considered healthy, +by default, 1; +</tag-desc> + +<tag-name id="hc_match"> +<literal>match</literal>=<value>name</value> +</tag-name> +<tag-desc> +specifies the <literal>match</literal> block configuring the tests that a +successful connection should pass in order for a health check to pass; +by default, only the ability to connect to the server is checked. +</tag-desc> + +</list> +</para> + +<para> +For example, +<example> +server { + proxy_pass backend; + health_check; +} +</example> +will check the ability to connect to each +server in the <literal>backend</literal> group every five seconds. +When a connection to the server cannot be established, +the health check will fail, and the server will +be considered unhealthy. +Client connections are not passed to unhealthy servers. +</para> + +<para> +Health checks can also be configured to test data obtained from the server. +Tests are configured separately using the <link id="match"/> directive +and referenced in the <literal>match</literal> parameter. +</para> + +<para> +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 be +considered unhealthy. +</para> + +</directive> + + +<directive name="health_check_timeout"> +<syntax><value>timeout</value></syntax> +<default>5s</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Overrides the +<link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/> +value for health checks. +</para> + +</directive> + + +<directive name="match"> +<syntax block="yes"><value>name</value> </syntax> +<default/> +<context>stream</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Defines the named test set used to verify server responses to health checks. +</para> + +<para> +The following parameters can be configured: +<list type="tag"> + +<tag-name> +<literal>send</literal> <value>string</value>; +</tag-name> +<tag-desc> +sends a <value>string</value> to the server; +</tag-desc> + +<tag-name> +<literal>expect</literal> <literal>~</literal> <value>regexp</value>; +</tag-name> +<tag-desc> +a regular expression that the data obtained from the server should match. +The regular expression is specified with the preceding +“<literal>~*</literal>” modifier (for case-insensitive matching), or the +“<literal>~</literal>” modifier (for case-sensitive matching). +</tag-desc> + +</list> +</para> + +<para> +Health check is passed if: +<list type="bullet"> +<listitem> +the connection was successfully established; +</listitem> + +<listitem> +the <value>string</value> from the <literal>send</literal> parameter, +if specified, was sent; +</listitem> + +<listitem> +the data obtained from the server matched the regular expression +from the <literal>expect</literal> parameter, if specified; +</listitem> + +<listitem> +the time elapsed does not exceed the value specified +in the <link id="health_check_timeout"/> directive. +</listitem> + +</list> +</para> + +<para> +Example: +<example> +upstream backend { + zone upstream_backend 10m; + server 127.0.0.1:12345; +} + +match http { + send "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n"; + expect ~ "200 OK"; +} + +server { + listen 12346; + proxy_pass backend; + health_check match=http; +} +</example> +</para> + +<para> +<note> +Only the first +<link doc="ngx_stream_proxy_module.xml" id="proxy_upstream_buffer"/> +bytes of data obtained from the server are examined. +</note> +</para> + +</directive> + </section> </module>
--- a/xml/ru/GNUmakefile +++ b/xml/ru/GNUmakefile @@ -70,6 +70,7 @@ REFS = \ http/ngx_http_stub_status_module \ http/ngx_http_sub_module \ http/ngx_http_upstream_module \ + http/ngx_http_upstream_conf_module \ http/ngx_http_userid_module \ http/ngx_http_uwsgi_module \ http/ngx_http_xslt_module \
--- a/xml/ru/docs/http/ngx_http_status_module.xml +++ b/xml/ru/docs/http/ngx_http_status_module.xml @@ -9,7 +9,7 @@ <module name="Модуль ngx_http_status_module" link="/ru/docs/http/ngx_http_status_module.html" lang="ru" - rev="4"> + rev="5"> <section id="summary"> @@ -160,7 +160,7 @@ http://127.0.0.1/status/upstreams/backen <tag-name id="version"><literal>version</literal></tag-name> <tag-desc> Версия предоставляемого набора данных. -Текущей является версия 4. +Текущей является версия 5. </tag-desc> <tag-name><literal>nginx_version</literal></tag-name> @@ -173,6 +173,13 @@ http://127.0.0.1/status/upstreams/backen Адрес сервера, принявшего запрос получения информации о состоянии. </tag-desc> +<tag-name id="generation"><literal>generation</literal></tag-name> +<tag-desc> +Суммарное число +<link doc="../control.xml" id="reconfiguration">перезагрузок</link> +конфигурации. +</tag-desc> + <tag-name id="load_timestamp"><literal>load_timestamp</literal></tag-name> <tag-desc> Время последней перезагрузки конфигурации, в миллисекундах с начала эпохи. @@ -183,6 +190,19 @@ http://127.0.0.1/status/upstreams/backen Текущее время в миллисекундах с начала эпохи. </tag-desc> +<tag-name id="processes"><literal>processes</literal></tag-name> +<tag-desc> +<list type="tag"> + +<tag-name id="respawned"><literal>respawned</literal></tag-name> +<tag-desc> +Суммарное число перезапусков аварийно завершённых +дочерних процессов. +</tag-desc> + +</list> +</tag-desc> + <tag-name><literal>connections</literal></tag-name> <tag-desc> <list type="tag"> @@ -331,11 +351,13 @@ http://127.0.0.1/status/upstreams/backen Текущее число активных соединений. </tag-desc> +<!-- <tag-name><literal>keepalive</literal></tag-name> <tag-desc> Текущее число бездействующих <link doc="ngx_http_upstream_module.xml" id="keepalive"/>-соединений. </tag-desc> +--> <tag-name id="max_conns"><literal>max_conns</literal></tag-name> <tag-desc> @@ -451,6 +473,24 @@ http://127.0.0.1/status/upstreams/backen когда сервер в последний раз был выбран для обработки запроса (1.7.5). </tag-desc> +<tag-name id="header_time"><literal>header_time</literal></tag-name> +<tag-desc> +Среднее время получения +<link doc="ngx_http_upstream_module.xml" id="var_upstream_header_time">заголовка +ответа</link> от сервера (1.7.10). +Поле доступно при использовании метода балансировки +<link doc="ngx_http_upstream_module.xml" id="least_time"/>. +</tag-desc> + +<tag-name id="response_time"><literal>response_time</literal></tag-name> +<tag-desc> +Среднее время получения +<link doc="ngx_http_upstream_module.xml" id="var_upstream_response_time">всего +ответа</link> от сервера (1.7.10). +Поле доступно при использовании метода балансировки +<link doc="ngx_http_upstream_module.xml" id="least_time"/>. +</tag-desc> + </list> </tag-desc> @@ -551,6 +591,28 @@ http://127.0.0.1/status/upstreams/backen <list type="bullet"> <listitem> +Поле <literal>keepalive</literal> сервера группы +было удалено в <link id="version">версии</link> 5. +</listitem> + +<listitem> +Поле <link id="generation"/> +было добавлено в <link id="version">версии</link> 5. +</listitem> + +<listitem> +Поле <link id="respawned"/> в +<link id="processes"/> +было добавлено в <link id="version">версии</link> 5. +</listitem> + +<listitem> +Поля <link id="header_time"/> и <link id="response_time"/> в +<link id="upstreams"/> +были добавлены в <link id="version">версии</link> 5. +</listitem> + +<listitem> Поле <link id="selected"/> в <link id="upstreams"/> было добавлено в <link id="version">версии</link> 4.
copy from xml/ru/docs/http/ngx_http_upstream_module.xml copy to xml/ru/docs/http/ngx_http_upstream_conf_module.xml --- a/xml/ru/docs/http/ngx_http_upstream_module.xml +++ b/xml/ru/docs/http/ngx_http_upstream_conf_module.xml @@ -1,28 +1,27 @@ <?xml version="1.0"?> <!-- - Copyright (C) Igor Sysoev Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> -<module name="Модуль ngx_http_upstream_module" - link="/ru/docs/http/ngx_http_upstream_module.html" +<module name="Модуль ngx_http_upstream_conf_module" + link="/ru/docs/http/ngx_http_upstream_conf_module.html" lang="ru" - rev="35"> + rev="1"> <section id="summary"> <para> -Модуль <literal>ngx_http_upstream_module</literal> -позволяет описывать группы серверов, -которые могут использоваться в директивах -<link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>, -<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>, -<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_pass"/>, -<link doc="ngx_http_scgi_module.xml" id="scgi_pass"/> и -<link doc="ngx_http_memcached_module.xml" id="memcached_pass"/>. +Модуль <literal>ngx_http_upstream_conf_module</literal> +позволяет оперативно настраивать группы серверов +при помощи простого HTTP-интерфейса без необходимости перезапуска nginx. +Группа серверов +<link doc="ngx_http_upstream_module.xml" id="zone">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="zone">stream</link> +должна находиться в разделяемой памяти. </para> </section> @@ -32,47 +31,15 @@ <para> <example> -upstream <emphasis>backend</emphasis> { - server backend1.example.com weight=5; - server backend2.example.com:8080; - server unix:/tmp/backend3; +upstream backend { + zone upstream_backend 64k; - server backup1.example.com:8080 backup; - server backup2.example.com:8080 backup; + ... } server { - location / { - proxy_pass http://<emphasis>backend</emphasis>; - } -} -</example> -</para> - -<para> -Динамически настраиваемая группа, -доступна как часть -<commercial_version>коммерческой подписки</commercial_version>: -<example> -upstream <emphasis>dynamic</emphasis> { - zone upstream_dynamic 64k; - - server backend1.example.com weight=5; - server backend2.example.com:8080 fail_timeout=5s slow_start=30s; - server 192.0.2.1 max_fails=3; - - server backup1.example.com:8080 backup; - server backup2.example.com:8080 backup; -} - -server { - location / { - proxy_pass http://<emphasis>dynamic</emphasis>; - health_check; - } - location /upstream_conf { - upstream_conf; + <emphasis>upstream_conf</emphasis>; allow 127.0.0.1; deny all; } @@ -85,960 +52,6 @@ server { <section id="directives" name="Директивы"> -<directive name="upstream"> -<syntax block="yes"><value>название</value></syntax> -<default/> -<context>http</context> - -<para> -Описывает группу серверов. -Серверы могут слушать на разных портах. -Кроме того, можно одновременно использовать серверы, -слушающие на TCP- и UNIX-сокетах. -</para> - -<para> -Пример: -<example> -upstream backend { - server backend1.example.com weight=5; - server 127.0.0.1:8080 max_fails=3 fail_timeout=30s; - server unix:/tmp/backend3; - - server backup1.example.com backup; -} -</example> -</para> - -<para> -По умолчанию запросы распределяются по серверам циклически -(в режиме round-robin) с учётом весов серверов. -В вышеприведённом примере каждые 7 запросов будут распределены так: -5 запросов на <literal>backend1.example.com</literal> -и по одному запросу на второй и третий серверы. -Если при попытке работы с сервером происходит ошибка, то запрос -передаётся следующему серверу, и так далее до тех пор, пока не будут опробованы -все работающие серверы. -Если не удастся получить успешный ответ -ни от одного из серверов, то клиенту будет возвращён результат работы -с последним сервером. -</para> - -</directive> - - -<directive name="server"> -<syntax><value>адрес</value> [<value>параметры</value>]</syntax> -<default/> -<context>upstream</context> - -<para> -Задаёт <value>адрес</value> и другие <value>параметры</value> -сервера. -Адрес может быть указан в виде доменного имени или IP-адреса, -и необязательного порта, или в виде пути UNIX-сокета, который -указывается после префикса “<literal>unix:</literal>”. -Если порт не указан, используется порт 80. -Доменное имя, которому соответствует несколько IP-адресов, -задаёт сразу несколько серверов. -</para> - -<para> -Могут быть заданы следующие параметры: -<list type="tag"> - -<tag-name id="weight"> -<literal>weight</literal>=<value>число</value> -</tag-name> -<tag-desc> -задаёт вес сервера, по умолчанию 1. -</tag-desc> - -<tag-name id="max_fails"> -<literal>max_fails</literal>=<value>число</value> -</tag-name> -<tag-desc> -задаёт число неудачных попыток работы с сервером, которые должны произойти -в течение времени, заданного параметром <literal>fail_timeout</literal>, -чтобы сервер считался недоступным на период времени, также заданный -параметром <literal>fail_timeout</literal>. -По умолчанию число попыток устанавливается равным 1. -Нулевое значение отключает учёт попыток. -Что считается неудачной попыткой, определяется директивами -<link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>, -<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>, -<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_next_upstream"/>, -<link doc="ngx_http_scgi_module.xml" id="scgi_next_upstream"/> и -<link doc="ngx_http_memcached_module.xml" id="memcached_next_upstream"/>. -</tag-desc> - -<tag-name id="fail_timeout"> -<literal>fail_timeout</literal>=<value>время</value> -</tag-name> -<tag-desc> -задаёт -<list type="bullet"> - -<listitem> -время, в течение которого должно произойти заданное число неудачных -попыток работы с сервером для того, чтобы сервер считался недоступным; -</listitem> - -<listitem> -и время, в течение которого сервер будет считаться недоступным. -</listitem> - -</list> -По умолчанию параметр равен 10 секундам. -</tag-desc> - -<tag-name id="backup"> -<literal>backup</literal> -</tag-name> -<tag-desc> -помечает сервер как запасной сервер. -На него будут передаваться запросы в случае, если не работают основные серверы. -</tag-desc> - -<tag-name id="down"> -<literal>down</literal> -</tag-name> -<tag-desc> -помечает сервер как постоянно недоступный. -</tag-desc> - -</list> -</para> - -<para> -Кроме того, -следующие параметры доступны как часть -<commercial_version>коммерческой подписки</commercial_version>: -<list type="tag"> - -<tag-name id="max_conns"> -<literal>max_conns</literal>=<value>число</value> -</tag-name> -<tag-desc> -ограничивает максимальное <value>число</value> одновременных соединений -к проксируемому серверу (1.5.9). -Значение по умолчанию равно 0 и означает, что ограничения нет. -</tag-desc> - -<tag-name id="resolve"> -<literal>resolve</literal> -</tag-name> -<tag-desc> -отслеживает изменения IP-адресов, соответствующих доменному имени сервера, -и автоматически изменяет конфигурацию группы -без необходимости перезапуска nginx (1.5.12). -<para> -Для работы этого параметра -директива <link doc="ngx_http_core_module.xml" id="resolver"/> -должна быть задана в блоке -<link doc="ngx_http_core_module.xml" id="http"/>. -Пример: -<example> -http { - resolver 10.0.0.1; - - upstream u { - zone ...; - ... - server example.com resolve; - } -} -</example> -</para> -</tag-desc> - -<tag-name id="route"> -<literal>route</literal>=<value>строка</value> -</tag-name> -<tag-desc> -задаёт имя маршрута к серверу. -</tag-desc> - -<tag-name id="slow_start"> -<literal>slow_start</literal>=<value>время</value> -</tag-name> -<tag-desc> -задаёт <value>время</value>, в течение которого вес сервера -восстановится от нуля до своего номинального значения в ситуации, когда -неработоспособный (unhealthy) сервер вновь становится работоспособным -(<link id="health_check">healthy</link>) -или когда сервер становится доступным по прошествии времени, -в течение которого он считался <link id="fail_timeout">недоступным</link>. -Значение по умолчанию равно нулю и означает, что медленный старт выключен. -</tag-desc> - -</list> -</para> - -<para> -<note> -Если в группе только один сервер, параметры <literal>max_fails</literal>, -<literal>fail_timeout</literal> и <literal>slow_start</literal> -игнорируются и такой сервер никогда не будет считаться недоступным. -</note> -</para> - -</directive> - - -<directive name="zone"> -<syntax><value>имя</value> <value>размер</value></syntax> -<default/> -<context>upstream</context> - -<para> -Задаёт <value>имя</value> и <value>размер</value> зоны разделяемой памяти, -в которой хранятся конфигурация группы и её рабочее состояние, -разделяемые между рабочими процессами. -В таких группах для изменения состава группы -или настроек отдельных серверов -нет необходимости перезапускать nginx. -Конфигурация доступна через специальный location, -в котором указана директива <link id="upstream_conf"/>. -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="hash"> -<syntax><value>ключ</value> [<literal>consistent</literal>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.7.2</appeared-in> - -<para> -Задаёт метод балансировки нагрузки для группы, при котором -соответствие клиента серверу определяется при помощи -хэшированного значения <value>ключа</value>. -В качестве <value>ключа</value> может использоваться -текст, переменные и их комбинации. -Следует отметить, что любое добавление или удаление серверов в группе -может привести к перераспределению большинства ключей на другие серверы. -Метод совместим с библиотекой Perl -<link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached">Cache::Memcached</link>. -</para> - -<para> -Если задан параметр <literal>consistent</literal>, то вместо -вышеописанного метода будет использоваться метод консистентного хэширования -<link url="http://www.last.fm/user/RJ/journal/2007/04/10/392555/">ketama</link>. -Метод гарантирует, что при добавлении сервера в группу или его удалении -на другие серверы будет перераспределено минимальное число ключей. -Применение метода для кэширующих серверов обеспечивает -больший процент попаданий в кэш. -Метод совместим с библиотекой Perl -<link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached%3A%3AFast">Cache::Memcached::Fast</link> -при значении параметра <value>ketama_points</value> равным 160. -</para> - -</directive> - - -<directive name="ip_hash"> -<syntax/> -<default/> -<context>upstream</context> - -<para> -Задаёт для группы метод балансировки нагрузки, при котором запросы -распределяются по серверам на основе IP-адресов клиентов. -В качестве ключа для хэширования используются первые три -октета IPv4-адреса клиента или IPv6-адрес клиента целиком. -Метод гарантирует, что запросы одного и того же клиента -будут всегда передаваться на один и тот же сервер. -Если же этот сервер будет считаться недоступным, -то запросы этого клиента будут передаваться на другой сервер. -С большой долей вероятности это также будет один и тот же сервер. -<note> -IPv6-адреса поддерживаются начиная с версий 1.3.2 и 1.2.2. -</note> -</para> - -<para> -Если один из серверов нужно убрать на некоторое время, то для сохранения -текущего хэширования IP-адресов клиентов этот сервер нужно пометить -параметром <literal>down</literal>. -</para> - -<para> -Пример: -<example> -upstream backend { - ip_hash; - - server backend1.example.com; - server backend2.example.com; - server backend3.example.com <emphasis>down</emphasis>; - server backend4.example.com; -} -</example> -</para> - -<para> -<note> -До версий 1.3.1 и 1.2.2 для серверов, использующих метод балансировки нагрузки -<literal>ip_hash</literal>, нельзя было задать вес. -</note> -</para> - -</directive> - - -<directive name="keepalive"> -<syntax><value>соединения</value></syntax> -<default/> -<context>upstream</context> -<appeared-in>1.1.4</appeared-in> - -<para> -Задействует кэш соединений для группы серверов. -</para> - -<para> -Параметр <value>соединения</value> устанавливает максимальное число -неактивных постоянных соединений с серверами группы, которые будут -сохраняться в кэше каждого рабочего процесса. -При превышении этого числа наиболее давно не используемые соединения -закрываются. -<note> -Следует особо отметить, что директива <literal>keepalive</literal> -не ограничивает общее число соединений с серверами группы, которые -рабочие процессы nginx могут открыть. -Параметр <value>соединения</value> следует устанавливать достаточно -консервативно, чтобы серверы группы по-прежнему могли обрабатывать -новые входящие соединения. -</note> -</para> - -<para> -Пример конфигурации группы серверов memcached с постоянными соединениями: -<example> -upstream memcached_backend { - server 127.0.0.1:11211; - server 10.0.0.2:11211; - - keepalive 32; -} - -server { - ... - - location /memcached/ { - set $memcached_key $uri; - memcached_pass memcached_backend; - } - -} -</example> -</para> - -<para> -Для HTTP директиву -<link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/> -следует установить в “<literal>1.1</literal>”, -а поле заголовка <header>Connection</header> — очистить: -<example> -upstream http_backend { - server 127.0.0.1:8080; - - keepalive 16; -} - -server { - ... - - location /http/ { - proxy_pass http://http_backend; - proxy_http_version 1.1; - proxy_set_header Connection ""; - ... - } -} -</example> -</para> - -<para> -<note> -Хоть это и не рекомендуется, но также возможно использование постоянных -соединений с HTTP/1.0, путём передачи поля заголовка -<header>Connection: Keep-Alive</header> серверу группы. -</note> -</para> - -<para> -Для работы постоянных соединений с FastCGI-серверами потребуется -включить директиву -<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_keep_conn"/>: -<example> -upstream fastcgi_backend { - server 127.0.0.1:9000; - - keepalive 8; -} - -server { - ... - - location /fastcgi/ { - fastcgi_pass fastcgi_backend; - fastcgi_keep_conn on; - ... - } -} -</example> -</para> - -<para> -<note> -При использовании методов балансировки нагрузки, отличных -от стандартного round-robin, следует активировать их до -директивы <literal>keepalive</literal>. -</note> - -<note> -Протоколы SCGI и uwsgi не определяют семантику постоянных соединений. -</note> -</para> - -</directive> - - -<directive name="least_conn"> -<syntax/> -<default/> -<context>upstream</context> -<appeared-in>1.3.1</appeared-in> -<appeared-in>1.2.2</appeared-in> - -<para> -Задаёт для группы метод балансировки нагрузки, при котором запрос -передаётся серверу с наименьшим числом активных соединений, -с учётом весов серверов. -Если подходит сразу несколько серверов, они выбираются циклически -(в режиме round-robin) с учётом их весов. -</para> - -</directive> - - -<directive name="health_check"> -<syntax>[<value>параметры</value>]</syntax> -<default/> -<context>location</context> - -<para> -Активирует периодические проверки работоспособности серверов в -<link id="upstream">группе</link>, указанной в содержащем location. -</para> - -<para> -Могут быть заданы следующие необязательные параметры: -<list type="tag"> - -<tag-name id="interval"> -<literal>interval</literal>=<value>время</value> -</tag-name> -<tag-desc> -задаёт интервал между двумя последовательными проверками, -по умолчанию 5 секунд; -</tag-desc> - -<tag-name id="fails"> -<literal>fails</literal>=<value>число</value> -</tag-name> -<tag-desc> -задаёт число последовательных неуспешных проверок для определённого сервера, -после которых сервер будет считаться неработоспособным, -по умолчанию 1; -</tag-desc> - -<tag-name id="passes"> -<literal>passes</literal>=<value>число</value> -</tag-name> -<tag-desc> -задаёт число последовательных успешных проверок для определённого сервера, -после которых сервер будет считаться работоспособным, -по умолчанию 1; -</tag-desc> - -<tag-name id="uri"> -<literal>uri</literal>=<value>uri</value> -</tag-name> -<tag-desc> -задаёт URI, используемый в запросах, проверяющих работоспособность, -по умолчанию “<literal>/</literal>”; -</tag-desc> - -<tag-name id="hc_match"> -<literal>match</literal>=<value>имя</value> -</tag-name> -<tag-desc> -указывает на блок <literal>match</literal> с условиями, которым должен -удовлетворять ответ, чтобы результат проверки считался успешным; -по умолчанию код ответа должен быть 2xx или 3xx. -</tag-desc> - -</list> -</para> - -<para> -В примере -<example> -location / { - proxy_pass http://backend; - health_check; -} -</example> -каждому серверу группы <literal>backend</literal> -с интервалом в 5 секунд посылаются запросы “<literal>/</literal>”. -Если происходит ошибка или таймаут при работе с сервером, или -код ответа проксируемого сервера не равен -2xx или 3xx, проверка считается неуспешной и сервер -признаётся неработоспособным. -На неработоспособные серверы клиентские запросы передаваться не будут. -</para> - -<para> -Проверки работоспособности могут тестировать код ответа, -наличие или отсутствие определённых полей заголовка и их значений, -а также содержимое тела ответа. -Тесты настраиваются отдельно при помощи директивы <link id="match"/> -и указываются в параметре <literal>match</literal>. -Например: -<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> -В такой конфигурации успешный ответ на проверочный запрос -должен иметь код 200, тип содержимого “<literal>text/html</literal>” -и “<literal>Welcome to nginx!</literal>” в теле ответа. -</para> - -<para> -Группа должна находиться в <link id="zone">зоне разделяемой памяти</link>. -</para> - -<para> -Если для группы задано несколько проверок, -то при любой неуспешной проверке соответствующий сервер будет -считаться неработоспособным. -</para> - -<para> -<note> -Обратите внимание, что при использовании проверок -большинство переменных имеют пустые значения. -</note> -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="match"> -<syntax block="yes"><value>имя</value></syntax> -<default/> -<context>http</context> - -<para> -Задаёт именованный набор тестов для анализа ответов -на запросы проверки работоспособности. -</para> - -<para> -В ответе могут быть протестированы следующие объекты: -<list type="tag"> - -<tag-name><literal>status 200;</literal></tag-name> -<tag-desc>код ответа равен 200</tag-desc> - -<tag-name><literal>status ! 500;</literal></tag-name> -<tag-desc>код ответа не равен 500</tag-desc> - -<tag-name><literal>status 200 204;</literal></tag-name> -<tag-desc>код ответа равен 200 или 204</tag-desc> - -<tag-name><literal>status ! 301 302;</literal></tag-name> -<tag-desc>код ответа не равен ни 301, ни 302</tag-desc> - -<tag-name><literal>status 200-399;</literal></tag-name> -<tag-desc>код ответа находится в диапазоне от 200 до 399</tag-desc> - -<tag-name><literal>status ! 400-599;</literal></tag-name> -<tag-desc>код ответа находится вне диапазона от 400 до 599</tag-desc> - -<tag-name><literal>status 301-303 307;</literal></tag-name> -<tag-desc>код ответа равен 301, 302, 303 или 307</tag-desc> - -</list> - -<list type="tag"> - -<tag-name><literal>header Content-Type = text/html;</literal></tag-name> -<tag-desc> -заголовок содержит <header>Content-Type</header> -со значением <literal>text/html</literal> -</tag-desc> - -<tag-name><literal>header Content-Type != text/html;</literal></tag-name> -<tag-desc> -заголовок содержит <header>Content-Type</header> -со значением, отличным от <literal>text/html</literal> -</tag-desc> - -<tag-name><literal>header Connection ~ close;</literal></tag-name> -<tag-desc> -заголовок содержит <header>Connection</header> -со значением, совпадающим с регулярным выражением <literal>close</literal> -</tag-desc> - -<tag-name><literal>header Connection !~ close;</literal></tag-name> -<tag-desc> -заголовок содержит <header>Connection</header> -со значением, не совпадающим с регулярным выражением <literal>close</literal> -</tag-desc> - -<tag-name><literal>header Host;</literal></tag-name> -<tag-desc>заголовок содержит <header>Host</header></tag-desc> - -<tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name> -<tag-desc>заголовок не содержит <header>X-Accel-Redirect</header></tag-desc> - -</list> - -<list type="tag"> - -<tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name> -<tag-desc> -тело ответа совпадает с регулярным выражением -“<literal>Welcome to nginx!</literal>” -</tag-desc> - -<tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name> -<tag-desc> -тело ответа не совпадает с регулярным выражением -“<literal>Welcome to nginx!</literal>” -</tag-desc> - -</list> -</para> - -<para> -Если задано несколько тестов, -то ответ должен удовлетворять всем тестам. -<note> -Проверяются только первые 256 Кбайт тела ответа. -</note> -</para> - -<para> -Примеры: -<example> -# код ответа 200, тип содержимого "text/html" -# и тело ответа содержит "Welcome to nginx!" -match welcome { - status 200; - header Content-Type = text/html; - body ~ "Welcome to nginx!"; -} -</example> - -<example> -# код ответа не равен 301, 302, 303 и 307 и заголовок не содержит "Refresh:" -match not_redirect { - status ! 301-303 307; - header ! Refresh; -} -</example> - -<example> -# код ответа успешный и сервер не в сервисном режиме -match server_ok { - status 200-399; - body !~ "maintenance mode"; -} -</example> - -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="queue"> -<syntax> -<value>число</value> -[<literal>timeout</literal>=<value>время</value>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.5.12</appeared-in> - -<para> -Если при обработке запроса невозможно сразу выбрать сервер группы -и в группе есть серверы, у которых число соединений достигло -ограничения <link id="max_conns"/>, -запрос будет помещён в очередь. -Директива задаёт максимальное число запросов, которые могут одновременно -находиться в очереди. -Если очередь переполнена -или за время, задаваемое параметром <literal>timeout</literal>, -так и не удастся выбрать сервер для передачи ему запроса, -клиенту будет возвращена ошибка. -</para> - -<para> -По умолчанию параметр <literal>timeout</literal> равен 60 секундам. -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="sticky"> -<syntax> - <literal>cookie</literal> <value>имя</value> - [<literal>expires=</literal><value>время</value>] - [<literal>domain=</literal><value>домен</value>] - [<literal>path=</literal><value>путь</value>]</syntax> -<syntax> - <literal>route</literal> <value>переменная</value> ...</syntax> -<syntax> - <literal>learn</literal> - <literal>create=</literal><value>$переменная</value> - <literal>lookup=</literal><value>$переменная</value> - <literal>zone=</literal><value>имя</value>:<value>размер</value> - [<literal>timeout=</literal><value>время</value>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Включает режим привязки сеансов, в котором запросы клиента -будут передаваться на один и тот же сервер группы. -Доступны три метода: -<list type="tag"> -<tag-name id="sticky_cookie"><literal>cookie</literal></tag-name> -<tag-desc> - -<para> -При использовании метода <literal>cookie</literal> информация о -назначенном сервере передаётся в HTTP-куке: -<example> -upstream backend { - server backend1.example.com; - server backend2.example.com; - - sticky cookie srv_id expires=1h domain=.example.com path=/; -} -</example> -</para> - -<para> -Запрос от клиента, ещё не привязанного к определённому серверу, -передаётся на сервер, выбранный согласно настроенному методу балансировки. -Дальнейшие запросы от этого клиента передаются на тот же сервер. -Если назначенный сервер не может обработать запрос, выбирается новый -сервер как если бы клиент не имел привязки к серверу. -</para> - -<para> -Первый параметр задаёт имя куки, которую необходимо установить или проверить. -Дополнительные параметры могут быть следующими: -<list type="tag"> - -<tag-name><literal>expires</literal></tag-name> -<tag-desc> -Задаёт время, в течение которого браузеру необходимо хранить куку. -Специальное значение <literal>max</literal> устанавливает срок хранения куки до -31 декабря 2037 года 23:55:55 GMT. -Если параметр не указан, то время действия куки ограничивается сессией браузера. -</tag-desc> - -<tag-name><literal>domain</literal></tag-name> -<tag-desc> -Задаёт домен, для которого устанавливается кука. -</tag-desc> - -<tag-name><literal>path</literal></tag-name> -<tag-desc> -Задаёт путь, для которого устанавливается кука. -</tag-desc> - -</list> -Если пропущен тот или иной параметр, то соответствующего поля в куке не будет. -</para> -</tag-desc> - -<tag-name id="sticky_route"><literal>route</literal></tag-name> -<tag-desc> - -<para> -При использовании метода <literal>route</literal> проксируемый сервер назначает -клиенту маршрут по получении первого запроса. -Все последующие запросы от этого клиента будут содержать информацию о -маршруте в куке или URI. -Эта информация сравнивается с параметром “<literal>route</literal>” директивы -<link id="server"/> для идентификации сервера, на который -следует проксировать запрос. -Если назначенный сервер не может обработать запрос, выбирается новый сервер -согласно настроенному методу балансировки как если бы в запросе не было -информации о маршруте. -</para> - -<para> -Параметры метода <literal>route</literal> задают переменные, которые -могут содержать информацию о маршруте. -Первая непустая переменная используется для поиска соответствующего сервера. -</para> - -<para> -Пример: -<example> -map $cookie_jsessionid $route_cookie { - ~.+\.(?P<route>\w+)$ $route; -} - -map $request_uri $route_uri { - ~jsessionid=.+\.(?P<route>\w+)$ $route; -} - -upstream backend { - server backend1.example.com route=a; - server backend2.example.com route=b; - - sticky route $route_cookie $route_uri; -} -</example> -В этом примере маршрут берётся из куки “<literal>JSESSIONID</literal>”, -если она присутствует в запросе. -В противном случае используется маршрут из URI. -</para> - -</tag-desc> - -<tag-name id="sticky_learn"><literal>learn</literal></tag-name> -<tag-desc> -<para> -При использовании метода <literal>learn</literal> (1.7.1) nginx -анализирует ответы от вышестоящего сервера и запоминает -начатые им сессии, которые обычно передаются в HTTP-куке. -<example> -upstream backend { - server backend1.example.com:8080; - server backend2.example.com:8081; - - sticky learn - create=$upstream_cookie_sessionid - lookup=$cookie_sessionid - zone=client_sessions:1m; -} -</example> - -В примере выше сервер группы создаёт сессию путём установки -куки “<literal>SESSIONID</literal>” в своём ответе. -Последующие запросы с этой кукой будут передаваться на этот же сервер. -Если сервер не может обработать запрос, выбирается новый -сервер как если бы клиент не имел привязки к серверу. -</para> - -<para> -Параметры <literal>create</literal> и <literal>lookup</literal> -задают переменные, в которых соответственно указывается способ -создания новых и поиска существующих сессий. -Оба параметра могут быть указаны больше одного раза -(в этом случае используется первая непустая переменная). -</para> - -<para> -Сессии хранятся в зоне разделяемой памяти, <value>имя</value> и -<value>размер</value> которой задаются параметром <literal>zone</literal>. -Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч сессий -на 64-битной платформе. -Сессии, к которым не было обращений в течение времени, заданного параметром -<literal>timeout</literal>, удаляются из зоны. -По умолчанию <literal>timeout</literal> равен 10 минутам. -</para> - -</tag-desc> -</list> -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="sticky_cookie_insert"> -<syntax><value>имя</value> -[<literal>expires=</literal><value>время</value>] -[<literal>domain=</literal><value>домен</value>] -[<literal>path=</literal><value>путь</value>]</syntax> -<default/> -<context>upstream</context> - -<para> -Эта директива устарела начиная с версии 1.5.7. -Вместо неё следует использовать аналогичную директиву -<link id="sticky"/> с изменённым синтаксисом: -<note> -<literal>sticky cookie</literal> <value>имя</value> -[<literal>expires=</literal><value>время</value>] -[<literal>domain=</literal><value>домен</value>] -[<literal>path=</literal><value>путь</value>]; -</note> -</para> - -</directive> - - <directive name="upstream_conf"> <syntax/> <default/> @@ -1076,7 +89,7 @@ upstream backend { Команда настройки состоит из параметров, передаваемых в аргументах запроса, например: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic +http://127.0.0.1/upstream_conf?upstream=backend </example> </para> @@ -1086,6 +99,15 @@ http://127.0.0.1/upstream_conf?upstream= <list type="tag" compact="no"> <tag-name> +<literal>stream=</literal></tag-name> +<tag-desc> +Выбирает группу серверов +<link doc="../stream/ngx_stream_upstream_module.xml">stream</link>. +Если параметр не задан, будет выбрана группа серверов +<link doc="ngx_http_upstream_module.xml">http</link>. +</tag-desc> + +<tag-name> <literal>upstream=</literal><value>имя</value></tag-name> <tag-desc> Выбирает группу серверов для работы. @@ -1123,88 +145,112 @@ http://127.0.0.1/upstream_conf?upstream= <tag-name> <literal>server=</literal><value>адрес</value></tag-name> <tag-desc> -То же, что и параметр “<literal>адрес</literal>” -директивы <link id="server"/>. +То же, что и параметр “<literal>адрес</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="server">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link>. <para> При добавлении сервер можно задать в виде доменного имени. В этом случае любые изменения IP-адресов, соответствующих доменному имени сервера, отслеживаются и автоматически применяются к конфигурации группы без необходимости перезапуска nginx (1.7.2). -Для этого в блоке <link doc="ngx_http_core_module.xml" id="http"/> должна -быть задана директива <link doc="ngx_http_core_module.xml" id="resolver"/>. -См. также параметр -<link id="resolve"/> директивы <link id="server"/>. +Для этого в блоке +<link doc="ngx_http_core_module.xml" id="resolver">http</link> +или +<link doc="../stream/ngx_stream_core_module.xml" id="resolver">stream</link> +должна быть задана директива “<literal>resolver</literal>”. +См. также параметр “<literal>resolve</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="resolve">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="resolve">stream</link>. </para> </tag-desc> <tag-name> <literal>weight=</literal><value>число</value></tag-name> <tag-desc> -То же, что и параметр “<literal>weight</literal>” -директивы <link id="server"/>. +То же, что и параметр “<literal>weight</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="weight">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="weight">stream</link>. </tag-desc> <tag-name> <literal>max_conns=</literal><value>число</value></tag-name> <tag-desc> -То же, что и параметр “<literal>max_conns</literal>” -директивы <link id="server"/>. +То же, что и параметр “<literal>max_conns</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="max_conns">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="max_conns">stream</link>. </tag-desc> <tag-name> <literal>max_fails=</literal><value>число</value></tag-name> <tag-desc> -То же, что и параметр “<literal>max_fails</literal>” -директивы <link id="server"/>. +То же, что и параметр “<literal>max_fails</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="max_fails">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="max_fails">stream</link>. </tag-desc> <tag-name> <literal>fail_timeout=</literal><value>время</value></tag-name> <tag-desc> -То же, что и параметр “<literal>fail_timeout</literal>” -директивы <link id="server"/>. +То же, что и параметр “<literal>fail_timeout</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="fail_timeout">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="fail_timeout">stream</link>. </tag-desc> <tag-name> <literal>slow_start=</literal><value>время</value></tag-name> <tag-desc> -То же, что и параметр “<literal>slow_start</literal>” -директивы <link id="server"/>. +То же, что и параметр “<literal>slow_start</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="slow_start">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="slow_start">stream</link>. </tag-desc> <tag-name> <literal>down=</literal></tag-name> <tag-desc> -То же, что и параметр “<literal>down</literal>” -директивы <link id="server"/>. +То же, что и параметр “<literal>down</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="down">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link>. </tag-desc> <tag-name id="drain"><literal>drain=</literal></tag-name> - <tag-desc> -Переводит сервер группы в режим “draining” (1.7.5). +Переводит сервер группы серверов +<link doc="ngx_http_upstream_module.xml">http</link> +в режим “draining” (1.7.5). В этом режиме на сервер будут проксироваться только -<link id="sticky">привязанные</link> к нему запросы. +<link doc="ngx_http_upstream_module.xml" id="sticky">привязанные</link> +к нему запросы. </tag-desc> <tag-name> <literal>up=</literal></tag-name> <tag-desc> -Параметр, обратный по значению параметру “<literal>down</literal>” -директивы <link id="server"/>. +Параметр, обратный по значению параметру “<literal>down</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="down">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link>. </tag-desc> <tag-name> <literal>route=</literal><value>строка</value></tag-name> <tag-desc> -То же, что и параметр “<literal>route</literal>” -директивы <link id="server"/>. +То же, что и параметр “<literal>route</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="route">http</link>. </tag-desc> </list> -Первые два параметра выбирают объект. -Объектом может быть либо группа серверов, либо отдельный сервер. +Первые три параметра выбирают объект. +Объектом может быть либо группа серверов http или stream, +либо отдельный сервер. Если остальные параметры не указаны, то показывается конфигурация выбранной группы или сервера. </para> @@ -1213,176 +259,75 @@ http://127.0.0.1/upstream_conf?upstream= Например, команда для просмотра конфигурации всей группы выглядит следующим образом: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic +http://127.0.0.1/upstream_conf?upstream=backend </example> Для просмотра конфигурации отдельного сервера следует указать его идентификатор: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42 +http://127.0.0.1/upstream_conf?upstream=backend&id=42 </example> - </para> <para> Для добавления нового сервера в группу следует указать его адрес в параметре “<literal>server=</literal>”. Если остальные параметры не указаны, то при добавлении сервера -их значения будут установлены по умолчанию (см. директиву <link id="server"/>). +их значения будут установлены по умолчанию (см. директиву +“<literal>server</literal>” для +<link doc="ngx_http_upstream_module.xml" id="server">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link>). </para> <para> Например, команда для добавления нового основного сервера в группу выглядит следующим образом: <example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080 +http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080 </example> Добавление нового запасного сервера происходит следующим образом: <example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&backup=&server=127.0.0.1:8080 +http://127.0.0.1/upstream_conf?add=&upstream=backend&backup=&server=127.0.0.1:8080 </example> Добавление нового основного сервера с нестандартными значениями параметров и с пометкой его как постоянно недоступного (“<literal>down</literal>”) происходит следующим образом: <example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080&weight=2&down= +http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080&weight=2&down= </example> -</para> -<para> Для удаления сервера следует указать его идентификатор: <example> -http://127.0.0.1/upstream_conf?remove=&upstream=dynamic&id=42 +http://127.0.0.1/upstream_conf?remove=&upstream=backend&id=42 </example> -</para> -<para> Пометка существующего сервера как постоянно недоступного (“<literal>down</literal>”) происходит следующим образом: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&down= +http://127.0.0.1/upstream_conf?upstream=backend&id=42&down= </example> Изменение адреса существующего сервера происходит следующим образом: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&server=192.0.2.3:8123 +http://127.0.0.1/upstream_conf?upstream=backend&id=42&server=192.0.2.3:8123 </example> Изменение других параметров существующего сервера происходит следующим образом: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&max_fails=3&weight=4 +http://127.0.0.1/upstream_conf?upstream=backend&id=42&max_fails=3&weight=4 </example> -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> +Вышеприведённые примеры актуальны для группы серверов +<link doc="ngx_http_upstream_module.xml">http</link>. +Аналогичные примеры для группы серверов +<link doc="../stream/ngx_stream_upstream_module.xml">stream</link> +требуют указания параметра “<literal>stream=</literal>”. </para> </directive> </section> - -<section id="variables" name="Встроенные переменные"> - -<para> -Модуль <literal>ngx_http_upstream_module</literal> -поддерживает следующие встроенные переменные: -<list type="tag"> - -<tag-name id="var_upstream_addr"><var>$upstream_addr</var></tag-name> -<tag-desc> -хранит IP-адрес и порт или путь к UNIX-сокету сервера группы. -Если при обработке запроса были сделаны обращения к нескольким серверам, -то их адреса разделяются запятой, например, -“<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock</literal>”. -Если произошло внутреннее перенаправление от одной группы серверов на другую -с помощью -<header>X-Accel-Redirect</header> или -<link doc="ngx_http_core_module.xml" id="error_page"/>, -то адреса, соответствующие разным группам серверов, разделяются двоеточием, -например, -“<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80</literal>”. -</tag-desc> - -<tag-name id="var_upstream_cache_status"><var>$upstream_cache_status</var> -</tag-name> -<tag-desc> -хранит статус доступа к кэшу ответов (0.8.3). -Статус может быть одним из “<literal>MISS</literal>”, -“<literal>BYPASS</literal>”, “<literal>EXPIRED</literal>”, -“<literal>STALE</literal>”, “<literal>UPDATING</literal>”, -“<literal>REVALIDATED</literal>” или “<literal>HIT</literal>”. -</tag-desc> - -<tag-name id="var_upstream_cookie_"><var>$upstream_cookie_</var><value>имя</value> -</tag-name> -<tag-desc> -кука с указанным <value>именем</value>, переданная сервером группы -в поле <header>Set-Cookie</header> заголовка ответа (1.7.1). -Необходимо иметь в виду, что куки запоминаются только из ответа -последнего сервера. -</tag-desc> - -<tag-name id="var_upstream_header_time"><var>$upstream_header_time</var> -</tag-name> -<tag-desc> -хранит время, -затраченное на получение заголовка ответа от сервера группы (1.7.10); -время хранится в секундах с точностью до миллисекунд. -Времена нескольких ответов -разделяются запятыми и двоеточиями подобно адресам в переменной -<link id="var_upstream_addr">$upstream_addr</link>. -</tag-desc> - -<tag-name id="var_upstream_http_"><var>$upstream_http_</var><value>имя</value></tag-name> -<tag-desc> -хранят поля заголовка ответа сервера. -Например, поле заголовка ответа <header>Server</header> -доступно в переменной <var>$upstream_http_server</var>. -Правила преобразования имён полей заголовка ответа в имена переменных -такие же, как для переменных с префиксом -“<link doc="ngx_http_core_module.xml" id="var_http_">$http_</link>”. -Необходимо иметь в виду, что поля заголовка запоминаются только из ответа -последнего сервера. -</tag-desc> - -<tag-name id="var_upstream_response_length"><var>$upstream_response_length</var> -</tag-name> -<tag-desc> -хранит длину ответа, полученного от сервера группы (0.7.27); -длина хранится в байтах. -Длины нескольких ответов -разделяются запятыми и двоеточиями подобно адресам в переменной -<link id="var_upstream_addr">$upstream_addr</link>. -</tag-desc> - -<tag-name id="var_upstream_response_time"><var>$upstream_response_time</var> -</tag-name> -<tag-desc> -хранит время, затраченное на получение ответа от сервера группы; -время хранится в секундах с точностью до миллисекунд. -Времена нескольких ответов -разделяются запятыми и двоеточиями подобно адресам в переменной -<link id="var_upstream_addr">$upstream_addr</link>. -</tag-desc> - -<tag-name id="var_upstream_status"><var>$upstream_status</var></tag-name> -<tag-desc> -хранит статус ответа, полученного от сервера группы. -Статусы нескольких ответов -разделяются запятыми и двоеточиями подобно адресам в переменной -<link id="var_upstream_addr">$upstream_addr</link>. -</tag-desc> - -</list> -</para> - -</section> - </module>
--- a/xml/ru/docs/http/ngx_http_upstream_module.xml +++ b/xml/ru/docs/http/ngx_http_upstream_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_upstream_module" link="/ru/docs/http/ngx_http_upstream_module.html" lang="ru" - rev="35"> + rev="36"> <section id="summary"> @@ -54,12 +54,15 @@ server { доступна как часть <commercial_version>коммерческой подписки</commercial_version>: <example> +resolver 10.0.0.1; + upstream <emphasis>dynamic</emphasis> { zone upstream_dynamic 64k; server backend1.example.com weight=5; server backend2.example.com:8080 fail_timeout=5s slow_start=30s; server 192.0.2.1 max_fails=3; + server backend3.example.com resolve; server backup1.example.com:8080 backup; server backup2.example.com:8080 backup; @@ -70,12 +73,6 @@ server { proxy_pass http://<emphasis>dynamic</emphasis>; health_check; } - - location /upstream_conf { - upstream_conf; - allow 127.0.0.1; - deny all; - } } </example> </para> @@ -299,7 +296,8 @@ http { или настроек отдельных серверов нет необходимости перезапускать nginx. Конфигурация доступна через специальный location, -в котором указана директива <link id="upstream_conf"/>. +в котором указана директива +<link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. </para> <para> @@ -533,6 +531,38 @@ server { </directive> +<directive name="least_time"> +<syntax><literal>header</literal> | <literal>last_byte</literal></syntax> +<default/> +<context>upstream</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Задаёт для группы метод балансировки нагрузки, при котором запрос +передаётся серверу с наименьшими средним временем ответа и +числом активных соединений с учётом весов серверов. +Если подходит сразу несколько серверов, то они выбираются циклически +(в режиме round-robin) с учётом их весов. +</para> + +<para> +Если указан параметр <literal>header</literal>, +то учитывается время получения +<link id="var_upstream_header_time">заголовка ответа</link>. +Если указан параметр <literal>last_byte</literal>, то учитывается +время получения <link id="var_upstream_response_time">всего ответа</link>. +</para> + +<para> +<note> +Эта директива доступна как часть +<commercial_version>коммерческой подписки</commercial_version>. +</note> +</para> + +</directive> + + <directive name="health_check"> <syntax>[<value>параметры</value>]</syntax> <default/> @@ -842,6 +872,8 @@ match server_ok { <literal>cookie</literal> <value>имя</value> [<literal>expires=</literal><value>время</value>] [<literal>domain=</literal><value>домен</value>] + [<literal>httponly</literal>] + [<literal>secure</literal>] [<literal>path=</literal><value>путь</value>]</syntax> <syntax> <literal>route</literal> <value>переменная</value> ...</syntax> @@ -889,22 +921,32 @@ upstream backend { Дополнительные параметры могут быть следующими: <list type="tag"> -<tag-name><literal>expires</literal></tag-name> +<tag-name><literal>expires=</literal><value>время</value></tag-name> <tag-desc> -Задаёт время, в течение которого браузеру необходимо хранить куку. +Задаёт <value>время</value>, в течение которого браузеру необходимо хранить куку. Специальное значение <literal>max</literal> устанавливает срок хранения куки до 31 декабря 2037 года 23:55:55 GMT. Если параметр не указан, то время действия куки ограничивается сессией браузера. </tag-desc> -<tag-name><literal>domain</literal></tag-name> +<tag-name><literal>domain=</literal><value>домен</value></tag-name> <tag-desc> -Задаёт домен, для которого устанавливается кука. +Задаёт <value>домен</value>, для которого устанавливается кука. </tag-desc> -<tag-name><literal>path</literal></tag-name> +<tag-name><literal>httponly</literal></tag-name> +<tag-desc> +Добавляет атрибут <literal>HttpOnly</literal> к куке (1.7.11). +</tag-desc> + +<tag-name><literal>secure</literal></tag-name> <tag-desc> -Задаёт путь, для которого устанавливается кука. +Добавляет атрибут <literal>Secure</literal> к куке (1.7.11). +</tag-desc> + +<tag-name><literal>path=</literal><value>путь</value></tag-name> +<tag-desc> +Задаёт <value>путь</value>, для которого устанавливается кука. </tag-desc> </list> @@ -1038,253 +1080,6 @@ upstream backend { </directive> - -<directive name="upstream_conf"> -<syntax/> -<default/> -<context>location</context> - -<para> -Активирует HTTP-интерфейс для настройки групп серверов в содержащем location. -Доступ в location следует -<link doc="ngx_http_core_module.xml" id="satisfy">ограничить</link>. -</para> - -<para> -С помощью команд настройки можно: -<list type="bullet"> - -<listitem>просматривать конфигурацию группы;</listitem> - -<listitem> -просматривать или изменять конфигурацию, а также -удалять серверы; -</listitem> - -<listitem>добавлять новые серверы.</listitem> - -</list> -<note> -Поскольку адреса в группе не обязаны быть уникальными, -обращение к отдельным серверам в группе осуществляется по их идентификаторам. -Идентификаторы назначаются автоматически и показываются при добавлении сервера -или просмотре конфигурации группы. -</note> -</para> - -<para> -Команда настройки состоит из параметров, передаваемых в аргументах запроса, -например: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic -</example> -</para> - -<para> -Поддерживаются следующие параметры: - -<list type="tag" compact="no"> - -<tag-name> -<literal>upstream=</literal><value>имя</value></tag-name> -<tag-desc> -Выбирает группу серверов для работы. -Параметр является обязательным. -</tag-desc> - -<tag-name> -<literal>id=</literal><value>число</value></tag-name> -<tag-desc> -Выбирает сервер для просмотра, изменения или удаления. -</tag-desc> - -<tag-name> -<literal>remove=</literal></tag-name> -<tag-desc> -Удаляет сервер из группы. -</tag-desc> - -<tag-name> -<literal>add=</literal></tag-name> -<tag-desc> -Добавляет новый сервер в группу. -</tag-desc> - -<tag-name> -<literal>backup=</literal></tag-name> -<tag-desc> -Необходим для добавления запасного сервера. -<note> -До версии 1.7.2 параметр <literal>backup=</literal> требовался -также для просмотра, изменения или удаления существующих запасных серверов. -</note> -</tag-desc> - -<tag-name> -<literal>server=</literal><value>адрес</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>адрес</literal>” -директивы <link id="server"/>. -<para> -При добавлении сервер можно задать в виде доменного имени. -В этом случае любые изменения IP-адресов, соответствующих доменному имени -сервера, отслеживаются и автоматически применяются к конфигурации группы -без необходимости перезапуска nginx (1.7.2). -Для этого в блоке <link doc="ngx_http_core_module.xml" id="http"/> должна -быть задана директива <link doc="ngx_http_core_module.xml" id="resolver"/>. -См. также параметр -<link id="resolve"/> директивы <link id="server"/>. -</para> -</tag-desc> - -<tag-name> -<literal>weight=</literal><value>число</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>weight</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name> -<literal>max_conns=</literal><value>число</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>max_conns</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name> -<literal>max_fails=</literal><value>число</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>max_fails</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name> -<literal>fail_timeout=</literal><value>время</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>fail_timeout</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name> -<literal>slow_start=</literal><value>время</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>slow_start</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name> -<literal>down=</literal></tag-name> -<tag-desc> -То же, что и параметр “<literal>down</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name id="drain"><literal>drain=</literal></tag-name> - -<tag-desc> -Переводит сервер группы в режим “draining” (1.7.5). -В этом режиме на сервер будут проксироваться только -<link id="sticky">привязанные</link> к нему запросы. -</tag-desc> - -<tag-name> -<literal>up=</literal></tag-name> -<tag-desc> -Параметр, обратный по значению параметру “<literal>down</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name> -<literal>route=</literal><value>строка</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>route</literal>” -директивы <link id="server"/>. -</tag-desc> - -</list> - -Первые два параметра выбирают объект. -Объектом может быть либо группа серверов, либо отдельный сервер. -Если остальные параметры не указаны, то показывается конфигурация выбранной -группы или сервера. -</para> - -<para> -Например, команда для просмотра конфигурации всей группы -выглядит следующим образом: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic -</example> - -Для просмотра конфигурации отдельного сервера следует указать его идентификатор: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42 -</example> - -</para> - -<para> -Для добавления нового сервера в группу -следует указать его адрес в параметре “<literal>server=</literal>”. -Если остальные параметры не указаны, то при добавлении сервера -их значения будут установлены по умолчанию (см. директиву <link id="server"/>). -</para> - -<para> -Например, команда для добавления нового основного сервера в группу -выглядит следующим образом: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080 -</example> - -Добавление нового запасного сервера происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&backup=&server=127.0.0.1:8080 -</example> - -Добавление нового основного сервера с нестандартными -значениями параметров и с пометкой его как постоянно недоступного -(“<literal>down</literal>”) происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080&weight=2&down= -</example> -</para> - -<para> -Для удаления сервера следует указать его идентификатор: -<example> -http://127.0.0.1/upstream_conf?remove=&upstream=dynamic&id=42 -</example> -</para> - -<para> -Пометка существующего сервера как постоянно недоступного -(“<literal>down</literal>”) происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&down= -</example> - -Изменение адреса существующего сервера происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&server=192.0.2.3:8123 -</example> - -Изменение других параметров существующего сервера происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&max_fails=3&weight=4 -</example> - -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - </section>
--- a/xml/ru/docs/index.xml +++ b/xml/ru/docs/index.xml @@ -8,7 +8,7 @@ <article name="nginx: документация" link="/ru/docs/" lang="ru" - rev="17" + rev="18" toc="no"> @@ -409,6 +409,11 @@ ngx_http_upstream_module</link> </listitem> <listitem> +<link doc="http/ngx_http_upstream_conf_module.xml"> +ngx_http_upstream_conf_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_userid_module.xml"> ngx_http_userid_module</link> </listitem>
--- a/xml/ru/docs/ngx_core_module.xml +++ b/xml/ru/docs/ngx_core_module.xml @@ -10,7 +10,7 @@ <module name="Основная функциональность" link="/ru/docs/ngx_core_module.html" lang="ru" - rev="12"> + rev="13"> <section id="example" name="Пример конфигурации"> @@ -158,6 +158,7 @@ events { <default>logs/error.log error</default> <context>main</context> <context>http</context> +<context>stream</context> <context>server</context> <context>location</context> @@ -194,6 +195,12 @@ events { nginx с <literal>--with-debug</literal>, см. “<link doc="debugging_log.xml"/>”. </note> + +<note> +Директива может быть указана на +уровне <literal>stream</literal> +начиная с версии 1.7.11. +</note> </para> </directive>