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

annotate xml/en/docs/http/ngx_http_upstream_module.xml @ 1123:9a9aa8e9d12c

Rephrased the "zone" directive, translated into Russian.

author	Yaroslav Zhuravlev <yar@nginx.com>
date	Thu, 20 Mar 2014 15:41:50 +0400
parents	594093ef96b1
children	d790333947f4

rev	line source
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1 <?xml version="1.0"?>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	2
580 be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 566 diff changeset	3 <!--
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 566 diff changeset	4 Copyright (C) Igor Sysoev
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 566 diff changeset	5 Copyright (C) Nginx, Inc.
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 566 diff changeset	6 -->
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 566 diff changeset	7
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	9
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	10 <module name="Module ngx_http_upstream_module"
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	11 link="/en/docs/http/ngx_http_upstream_module.html"
589 764fbac1b8b4 Added document revision. Ruslan Ermilov <ru@nginx.com> parents: 580 diff changeset	12 lang="en"
1123 9a9aa8e9d12c Rephrased the "zone" directive, translated into Russian. Yaroslav Zhuravlev <yar@nginx.com> parents: 1122 diff changeset	13 rev="15">
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	14
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	15 <section id="summary">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	16
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	17 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	18 The <literal>ngx_http_upstream_module</literal> module
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	19 is used to define groups of servers that can be referenced
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	20 by the <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>,
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	21 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>, and
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	22 <link doc="ngx_http_memcached_module.xml" id="memcached_pass"/> directives.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	23 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	24
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	25 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	26
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	27
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	28 <section id="example" name="Example Configuration">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	29
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	30 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	31 <example>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	32 upstream <emphasis>backend</emphasis> {
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	33 server backend1.example.com weight=5;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	34 server backend2.example.com:8080;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	35 server unix:/tmp/backend3;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	36
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	37 server backup1.example.com:8080 backup;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	38 server backup2.example.com:8080 backup;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	39 }
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	40
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	41 server {
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	42 location / {
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	43 proxy_pass http://<emphasis>backend</emphasis>;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	44 }
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	45 }
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	46 </example>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	47 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	48
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	49 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	50 Dynamically configurable group,
1088 379cb572a7ec Paraphrased sentences that mention "commercial subscription". Ruslan Ermilov <ru@nginx.com> parents: 1075 diff changeset	51 available as part of our <commercial_version/>:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	52 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	53 upstream <emphasis>appservers</emphasis> {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	54 zone appservers 64k;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	55
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	56 server appserv1.example.com weight=5;
955 28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	57 server appserv2.example.com:8080 fail_timeout=5s slow_start=30s;
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	58 server 192.0.2.1 max_fails=3;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	59
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	60 server reserve1.example.com:8080 backup;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	61 server reserve2.example.com:8080 backup;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	62 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	63
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	64 server {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	65 location / {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	66 proxy_pass http://<emphasis>appservers</emphasis>;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	67 health_check;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	68 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	69
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	70 location /upstream_conf {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	71 upstream_conf;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	72 allow 127.0.0.1;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	73 deny all;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	74 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	75 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	76 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	77 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	78
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	79 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	80
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	81
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	82 <section id="directives" name="Directives">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	83
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	84 <directive name="upstream">
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	85 <syntax block="yes"><value>name</value></syntax>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	86 <default/>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	87 <context>http</context>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	88
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	89 <para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	90 Defines a group of servers.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	91 Servers can listen on different ports.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	92 In addition, servers listening on TCP and UNIX-domain sockets
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	93 can be mixed.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	94 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	95
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	96 <para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	97 Example:
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	98 <example>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	99 upstream backend {
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	100 server backend1.example.com weight=5;
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	101 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	102 server unix:/tmp/backend3;
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	103 }
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	104 </example>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	105 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	106
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	107 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	108 By default, requests are distributed between the servers using a
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	109 weighted round-robin balancing method.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	110 In the above example, each 7 requests will be distributed as follows:
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	111 5 requests go to <literal>backend1.example.com</literal>
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	112 and one request to each of the second and third servers.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	113 If an error occurs during communication with a server, the request will
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	114 be passed to the next server, and so on until all of the functioning
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	115 servers will be tried.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	116 If a successful response could not be obtained from any of the servers,
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	117 the client will receive the result of the communication with the last server.
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	118 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	119
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	120 </directive>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	121
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	122
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	123 <directive name="server">
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	124 <syntax><value>address</value> [<value>parameters</value>]</syntax>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	125 <default/>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	126 <context>upstream</context>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	127
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	128 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	129 Defines the <value>address</value> and other <value>parameters</value>
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	130 of a server.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	131 The address can be specified as a domain name or IP address,
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	132 with an optional port, or as a UNIX-domain socket path
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	133 specified after the “<literal>unix:</literal>” prefix.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	134 If a port is not specified, the port 80 is used.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	135 A domain name that resolves to several IP addresses defines
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	136 multiple servers at once.
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	137 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	138
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	139 <para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	140 The following parameters can be defined:
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	141 <list type="tag">
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	142
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	143 <tag-name><literal>weight</literal>=<value>number</value></tag-name>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	144 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	145 sets the weight of the server, by default, 1.
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	146 </tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	147
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	148 <tag-name><literal>max_fails</literal>=<value>number</value></tag-name>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	149 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	150 sets the number of unsuccessful attempts to communicate with the server
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	151 that should happen in the duration set by the <literal>fail_timeout</literal>
968 fa19bacf6e1e Unified upstream server up/down state terminology. Vladimir Homutov <vl@nginx.com> parents: 966 diff changeset	152 parameter to consider the server unavailable for a duration also set by the
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	153 <literal>fail_timeout</literal> parameter.
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	154 By default, the number of unsuccessful attempts is set to 1.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	155 The zero value disables the accounting of attempts.
942 ba3d6ade3513 Elaborate on upstream server failures. Ruslan Ermilov <ru@nginx.com> parents: 917 diff changeset	156 What is considered an unsuccessful attempt is defined by the
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	157 <link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>,
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	158 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>, and
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	159 <link doc="ngx_http_memcached_module.xml" id="memcached_next_upstream"/>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	160 directives.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	161 </tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	162
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	163 <tag-name><literal>fail_timeout</literal>=<value>time</value></tag-name>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	164 <tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	165 sets
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	166 <list type="bullet">
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	167
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	168 <listitem>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	169 the time during which the specified number of unsuccessful attempts to
968 fa19bacf6e1e Unified upstream server up/down state terminology. Vladimir Homutov <vl@nginx.com> parents: 966 diff changeset	170 communicate with the server should happen to consider the server unavailable;
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	171 </listitem>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	172
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	173 <listitem>
968 fa19bacf6e1e Unified upstream server up/down state terminology. Vladimir Homutov <vl@nginx.com> parents: 966 diff changeset	174 and the period of time the server will be considered unavailable.
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	175 </listitem>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	176
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	177 </list>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	178 By default, the parameter is set to 10 seconds.
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	179 </tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	180
955 28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	181 <tag-name><literal>slow_start</literal>=<value>time</value></tag-name>
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	182 <tag-desc>
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	183 sets the <value>time</value> during which the server will recover its weight
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	184 from zero to a nominal value, when unhealthy server becomes
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	185 <link id="health_check">healthy</link>,
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	186 or when the server becomes available after a period of time
968 fa19bacf6e1e Unified upstream server up/down state terminology. Vladimir Homutov <vl@nginx.com> parents: 966 diff changeset	187 it was considered unavailable.
955 28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	188 Default value is zero, i.e. slow start is disabled.
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	189 <note>
1088 379cb572a7ec Paraphrased sentences that mention "commercial subscription". Ruslan Ermilov <ru@nginx.com> parents: 1075 diff changeset	190 This functionality is available as part of our <commercial_version/>.
955 28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	191 </note>
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	192 </tag-desc>
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	193
1122 594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	194 <tag-name id="max_conns">
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	195 <literal>max_conns</literal>=<value>number</value>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	196 </tag-name>
1119 15f48e365f43 Documented the "max_conns" parameter of the "server" directive. Vladimir Homutov <vl@nginx.com> parents: 1088 diff changeset	197 <tag-desc>
15f48e365f43 Documented the "max_conns" parameter of the "server" directive. Vladimir Homutov <vl@nginx.com> parents: 1088 diff changeset	198 limits the maximum <value>number</value> of simultaneous connections to the
15f48e365f43 Documented the "max_conns" parameter of the "server" directive. Vladimir Homutov <vl@nginx.com> parents: 1088 diff changeset	199 proxied server (1.5.9).
15f48e365f43 Documented the "max_conns" parameter of the "server" directive. Vladimir Homutov <vl@nginx.com> parents: 1088 diff changeset	200 Default value is zero, meaning there is no limit.
15f48e365f43 Documented the "max_conns" parameter of the "server" directive. Vladimir Homutov <vl@nginx.com> parents: 1088 diff changeset	201 <note>
15f48e365f43 Documented the "max_conns" parameter of the "server" directive. Vladimir Homutov <vl@nginx.com> parents: 1088 diff changeset	202 This functionality is available as part of our <commercial_version/> only.
15f48e365f43 Documented the "max_conns" parameter of the "server" directive. Vladimir Homutov <vl@nginx.com> parents: 1088 diff changeset	203 </note>
15f48e365f43 Documented the "max_conns" parameter of the "server" directive. Vladimir Homutov <vl@nginx.com> parents: 1088 diff changeset	204 </tag-desc>
15f48e365f43 Documented the "max_conns" parameter of the "server" directive. Vladimir Homutov <vl@nginx.com> parents: 1088 diff changeset	205
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	206 <tag-name><literal>backup</literal></tag-name>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	207 <tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	208 marks the server as a backup server.
968 fa19bacf6e1e Unified upstream server up/down state terminology. Vladimir Homutov <vl@nginx.com> parents: 966 diff changeset	209 It will be passed requests when the primary servers are unavailable.
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	210 </tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	211
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	212 <tag-name><literal>down</literal></tag-name>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	213 <tag-desc>
968 fa19bacf6e1e Unified upstream server up/down state terminology. Vladimir Homutov <vl@nginx.com> parents: 966 diff changeset	214 marks the server as permanently unavailable; used along with
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	215 the <link id="ip_hash"/> directive.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	216 </tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	217
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	218 <tag-name><literal>route</literal>=<value>string</value></tag-name>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	219 <tag-desc>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	220 sets the server route name.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	221 <note>
1088 379cb572a7ec Paraphrased sentences that mention "commercial subscription". Ruslan Ermilov <ru@nginx.com> parents: 1075 diff changeset	222 This functionality is available as part of our <commercial_version/>.
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	223 </note>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	224 </tag-desc>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	225
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	226 </list>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	227 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	228
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	229 <para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	230 Example:
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	231 <example>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	232 upstream backend {
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	233 server backend1.example.com weight=5;
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	234 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	235 server unix:/tmp/backend3;
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	236
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	237 server backup1.example.com:8080 backup;
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	238 }
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	239 </example>
969 7c542520b8f7 Added note about behavior of a single server in an upstream. Vladimir Homutov <vl@nginx.com> parents: 968 diff changeset	240
7c542520b8f7 Added note about behavior of a single server in an upstream. Vladimir Homutov <vl@nginx.com> parents: 968 diff changeset	241 <note>
7c542520b8f7 Added note about behavior of a single server in an upstream. Vladimir Homutov <vl@nginx.com> parents: 968 diff changeset	242 If there is only a single server in a group, <literal>max_fails</literal>,
7c542520b8f7 Added note about behavior of a single server in an upstream. Vladimir Homutov <vl@nginx.com> parents: 968 diff changeset	243 <literal>fail_timeout</literal> and <literal>slow_start</literal> parameters
7c542520b8f7 Added note about behavior of a single server in an upstream. Vladimir Homutov <vl@nginx.com> parents: 968 diff changeset	244 are ignored, and such a server will never be considered unavailable.
7c542520b8f7 Added note about behavior of a single server in an upstream. Vladimir Homutov <vl@nginx.com> parents: 968 diff changeset	245 </note>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	246 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	247
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	248 </directive>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	249
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	250
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	251 <directive name="zone">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	252 <syntax><value>name</value> <value>size</value></syntax>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	253 <default/>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	254 <context>upstream</context>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	255
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	256 <para>
1123 9a9aa8e9d12c Rephrased the "zone" directive, translated into Russian. Yaroslav Zhuravlev <yar@nginx.com> parents: 1122 diff changeset	257 Defines the <value>name</value> and <value>size</value> of the shared
9a9aa8e9d12c Rephrased the "zone" directive, translated into Russian. Yaroslav Zhuravlev <yar@nginx.com> parents: 1122 diff changeset	258 memory zone that keeps the group’s configuration and run-time state that are
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	259 shared between worker processes.
1123 9a9aa8e9d12c Rephrased the "zone" directive, translated into Russian. Yaroslav Zhuravlev <yar@nginx.com> parents: 1122 diff changeset	260 Such groups allow changing the group membership
9a9aa8e9d12c Rephrased the "zone" directive, translated into Russian. Yaroslav Zhuravlev <yar@nginx.com> parents: 1122 diff changeset	261 or modifying the settings of a particular server
9a9aa8e9d12c Rephrased the "zone" directive, translated into Russian. Yaroslav Zhuravlev <yar@nginx.com> parents: 1122 diff changeset	262 without the need of restarting nginx.
9a9aa8e9d12c Rephrased the "zone" directive, translated into Russian. Yaroslav Zhuravlev <yar@nginx.com> parents: 1122 diff changeset	263 The configuration is accessible via a special location
9a9aa8e9d12c Rephrased the "zone" directive, translated into Russian. Yaroslav Zhuravlev <yar@nginx.com> parents: 1122 diff changeset	264 handled by <link id="upstream_conf"/>.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	265 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	266
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	267 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	268 <note>
1088 379cb572a7ec Paraphrased sentences that mention "commercial subscription". Ruslan Ermilov <ru@nginx.com> parents: 1075 diff changeset	269 This directive is available as part of our <commercial_version/>.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	270 </note>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	271 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	272
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	273 </directive>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	274
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	275
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	276 <directive name="ip_hash">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	277 <syntax/>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	278 <default/>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	279 <context>upstream</context>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	280
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	281 <para>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	282 Specifies that a group should use a load balancing method where requests
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	283 are distributed between servers based on client IP addresses.
542 a9e6a8613534 Documented IPv6 support in ip_hash. Ruslan Ermilov <ru@nginx.com> parents: 533 diff changeset	284 The first three octets of the client IPv4 address, or the entire IPv6 address,
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	285 are used as a hashing key.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	286 The method ensures that requests from the same client will always be
968 fa19bacf6e1e Unified upstream server up/down state terminology. Vladimir Homutov <vl@nginx.com> parents: 966 diff changeset	287 passed to the same server except when this server is unavailable.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	288 In the latter case client requests will be passed to another server.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	289 Most probably, it will always be the same server as well.
542 a9e6a8613534 Documented IPv6 support in ip_hash. Ruslan Ermilov <ru@nginx.com> parents: 533 diff changeset	290 <note>
566 f8148fc88224 Documented 1.2.2 changes. Ruslan Ermilov <ru@nginx.com> parents: 542 diff changeset	291 IPv6 addresses are supported starting from versions 1.3.2 and 1.2.2.
542 a9e6a8613534 Documented IPv6 support in ip_hash. Ruslan Ermilov <ru@nginx.com> parents: 533 diff changeset	292 </note>
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	293 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	294
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	295 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	296 If one of the servers needs to be temporarily removed, it should
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	297 be marked with the <literal>down</literal> parameter in
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	298 order to preserve the current hashing of client IP addresses.
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	299 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	300
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	301 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	302 Example:
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	303 <example>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	304 upstream backend {
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	305 ip_hash;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	306
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	307 server backend1.example.com;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	308 server backend2.example.com;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	309 server backend3.example.com <emphasis>down</emphasis>;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	310 server backend4.example.com;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	311 }
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	312 </example>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	313 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	314
526 4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	315 <para>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	316 <note>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	317 Until versions 1.3.1 and 1.2.2, it was not possible to specify a weight for
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	318 servers using the <literal>ip_hash</literal> load balancing method.
526 4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	319 </note>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	320 </para>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	321
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	322 </directive>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	323
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	324
316 1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	325 <directive name="keepalive">
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	326 <syntax><value>connections</value></syntax>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	327 <default/>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	328 <context>upstream</context>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	329 <appeared-in>1.1.4</appeared-in>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	330
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	331 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	332 Activates the cache for connections to upstream servers.
316 1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	333 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	334
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	335 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	336 The <value>connections</value> parameter sets the maximum number of
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	337 idle keepalive connections to upstream servers that are preserved in
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	338 the cache of each worker process.
654 841118e33f41 Refined the text about cache of connections to upstream servers. Ruslan Ermilov <ru@nginx.com> parents: 589 diff changeset	339 When this number is exceeded, the least recently used connections
841118e33f41 Refined the text about cache of connections to upstream servers. Ruslan Ermilov <ru@nginx.com> parents: 589 diff changeset	340 are closed.
316 1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	341 <note>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	342 It should be particularly noted that the <literal>keepalive</literal> directive
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	343 does not limit the total number of connections to upstream servers
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	344 that an nginx worker process can open.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	345 The <value>connections</value> parameter should be set to a number small enough
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	346 to let upstream servers process new incoming connections as well.
316 1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	347 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	348 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	349
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	350 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	351 Example configuration of memcached upstream with keepalive connections:
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	352 <example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	353 upstream memcached_backend {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	354 server 127.0.0.1:11211;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	355 server 10.0.0.2:11211;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	356
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	357 keepalive 32;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	358 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	359
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	360 server {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	361 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	362
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	363 location /memcached/ {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	364 set $memcached_key $uri;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	365 memcached_pass memcached_backend;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	366 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	367
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	368 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	369 </example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	370 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	371
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	372 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	373 For HTTP, the <link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	374 directive should be set to “<literal>1.1</literal>”
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	375 and the <header>Connection</header> header field should be cleared:
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	376 <example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	377 upstream http_backend {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	378 server 127.0.0.1:8080;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	379
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	380 keepalive 16;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	381 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	382
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	383 server {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	384 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	385
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	386 location /http/ {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	387 proxy_pass http://http_backend;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	388 proxy_http_version 1.1;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	389 proxy_set_header Connection "";
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	390 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	391 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	392 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	393 </example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	394 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	395
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	396 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	397 <note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	398 Alternatively, HTTP/1.0 persistent connections can be used by passing the
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	399 <header>Connection: Keep-Alive</header> header field to an upstream server,
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	400 though this method is not recommended.
316 1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	401 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	402 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	403
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	404 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	405 For FastCGI servers, it is required to set
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	406 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_keep_conn"/>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	407 for keepalive connections to work:
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	408 <example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	409 upstream fastcgi_backend {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	410 server 127.0.0.1:9000;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	411
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	412 keepalive 8;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	413 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	414
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	415 server {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	416 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	417
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	418 location /fastcgi/ {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	419 fastcgi_pass fastcgi_backend;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	420 fastcgi_keep_conn on;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	421 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	422 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	423 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	424 </example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	425 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	426
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	427 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	428 <note>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	429 When using load balancer methods other than the default
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	430 round-robin method, it is necessary to activate them before
316 1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	431 the <literal>keepalive</literal> directive.
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	432 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	433
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	434 <note>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	435 SCGI and uwsgi protocols do not have a notion of keepalive connections.
316 1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	436 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	437 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	438
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	439 </directive>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	440
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	441
526 4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	442 <directive name="least_conn">
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	443 <syntax/>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	444 <default/>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	445 <context>upstream</context>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	446 <appeared-in>1.3.1</appeared-in>
566 f8148fc88224 Documented 1.2.2 changes. Ruslan Ermilov <ru@nginx.com> parents: 542 diff changeset	447 <appeared-in>1.2.2</appeared-in>
526 4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	448
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	449 <para>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	450 Specifies that a group should use a load balancing method where a request
526 4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	451 is passed to the server with the least number of active connections,
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	452 taking into account weights of servers.
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	453 If there are several such servers, they are tried using a
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	454 weighted round-robin balancing method.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	455 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	456
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	457 </directive>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	458
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	459
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	460 <directive name="health_check">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	461 <syntax>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	462 [<literal>interval=</literal><value>time</value>]
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	463 <!--
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	464 [<literal>jitter=</literal><value>time</value>]
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	465 -->
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	466 [<literal>fails=</literal><value>number</value>]
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	467 [<literal>passes=</literal><value>number</value>]
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	468 [<literal>uri=</literal><value>uri</value>]
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	469 [<literal>match=</literal><value>name</value>]</syntax>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	470
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	471 <default/>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	472 <context>location</context>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	473
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	474 <para>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	475 Enables periodic health checks of the servers in a
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	476 <link id="upstream">group</link> referenced in the surrounding location.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	477 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	478
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	479 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	480 The following optional parameters are supported:
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	481 <list type="bullet">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	482
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	483 <listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	484 <literal>interval</literal>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	485 sets the interval between two consecutive health checks,
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	486 by default, 5 seconds;
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	487 </listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	488
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	489 <listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	490 <literal>fails</literal>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	491 sets the number of consecutive failed health checks of a particular server
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	492 after which this server will be considered unhealthy,
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	493 by default, 1;
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	494 </listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	495
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	496 <listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	497 <literal>passes</literal>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	498 sets the number of consecutive passed health checks of a particular server
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	499 after which the server will be considered healthy,
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	500 by default, 1;
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	501 </listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	502
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	503 <listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	504 <literal>uri</literal>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	505 defines the URI used in health check requests,
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	506 by default, “<literal>/</literal>”;
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	507 </listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	508
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	509 <listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	510 <literal>match</literal>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	511 specifies the <literal>match</literal> block configuring the tests that a
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	512 response should pass in order for a health check to pass;
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	513 by default, the response should have status code 2xx or 3xx.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	514 </listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	515
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	516 </list>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	517 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	518
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	519 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	520 For example,
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	521 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	522 location / {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	523 proxy_pass http://backend;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	524 health_check;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	525 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	526 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	527 will send “<literal>/</literal>” requests to each
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	528 server in the <literal>backend</literal> group every five seconds.
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	529 If any communication error or timeout occurs, or a
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	530 proxied server responds with the status code other than
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	531 2xx or 3xx, the health check will fail, and the server will
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	532 be considered unhealthy.
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	533 Client requests are not passed to unhealthy servers.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	534 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	535
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	536 <para>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	537 Health checks can be configured to test the status code of a response,
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	538 presence of certain header fields and their values,
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	539 and the body contents.
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	540 Tests are configured separately using the <link id="match"/> directive
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	541 and referenced in the <literal>match</literal> parameter.
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	542 For example:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	543 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	544 http {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	545 server {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	546 ...
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	547 location / {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	548 proxy_pass http://backend;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	549 health_check match=welcome;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	550 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	551 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	552
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	553 match welcome {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	554 status 200;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	555 header Content-Type = text/html;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	556 body ~ "Welcome to nginx!";
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	557 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	558 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	559 </example>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	560 This configuration tells that for a health check to pass, the response to a
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	561 health check request should succeed,
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	562 have status 200, content type “<literal>text/html</literal>”,
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	563 and contain “<literal>Welcome to nginx!</literal>” in the body.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	564 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	565
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	566 <para>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	567 The server group must reside in the <link id="zone">shared memory</link>.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	568 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	569
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	570 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	571 If several health checks are defined for the same group of servers,
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	572 a single failure of any check will make the corresponding server be
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	573 considered unhealthy.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	574 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	575
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	576 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	577 <note>
1088 379cb572a7ec Paraphrased sentences that mention "commercial subscription". Ruslan Ermilov <ru@nginx.com> parents: 1075 diff changeset	578 This directive is available as part of our <commercial_version/>.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	579 </note>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	580 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	581
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	582 </directive>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	583
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	584
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	585 <directive name="match">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	586 <syntax block="yes"><value>name</value></syntax>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	587 <default/>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	588 <context>http</context>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	589
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	590 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	591 Defines the named test set used to verify responses to health check requests.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	592 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	593
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	594 <para>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	595 The following items can be tested in a response:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	596 <list type="tag">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	597
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	598 <tag-name><literal>status 200;</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	599 <tag-desc>status is 200</tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	600
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	601 <tag-name><literal>status ! 500;</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	602 <tag-desc>status is not 500</tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	603
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	604 <tag-name><literal>status 200 204;</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	605 <tag-desc>status is 200 or 204</tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	606
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	607 <tag-name><literal>status ! 301 302;</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	608 <tag-desc>status is neither 301 nor 302</tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	609
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	610 <tag-name><literal>status 200-399;</literal></tag-name>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	611 <tag-desc>status is in the range from 200 to 399</tag-desc>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	612
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	613 <tag-name><literal>status ! 400-599;</literal></tag-name>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	614 <tag-desc>status is not in the range from 400 to 599</tag-desc>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	615
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	616 <tag-name><literal>status 301-303 307;</literal></tag-name>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	617 <tag-desc>status is either 301, 302, 303, or 307</tag-desc>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	618
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	619 </list>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	620
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	621 <list type="tag">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	622
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	623 <tag-name><literal>header Content-Type = text/html;</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	624 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	625 header contains <header>Content-Type</header>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	626 with value <literal>text/html</literal>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	627 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	628
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	629 <tag-name><literal>header Content-Type != text/html;</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	630 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	631 header contains <header>Content-Type</header>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	632 with value other than <literal>text/html</literal>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	633 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	634
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	635 <tag-name><literal>header Connection ~ close;</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	636 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	637 header contains <header>Connection</header>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	638 with value matching regular expression <literal>close</literal>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	639 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	640
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	641 <tag-name><literal>header Connection !~ close;</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	642 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	643 header contains <header>Connection</header>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	644 with value not matching regular expression <literal>close</literal>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	645 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	646
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	647 <tag-name><literal>header Host;</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	648 <tag-desc>header contains <header>Host</header></tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	649
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	650 <tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	651 <tag-desc>header lacks <header>X-Accel-Redirect</header></tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	652
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	653 </list>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	654
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	655 <list type="tag">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	656
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	657 <tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	658 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	659 body matches regular expression “<literal>Welcome to nginx!</literal>”
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	660 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	661
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	662 <tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	663 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	664 body does not match regular expression “<literal>Welcome to nginx!</literal>”
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	665 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	666
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	667 </list>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	668 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	669
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	670 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	671 If several tests are specified,
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	672 the response matches only if it matches all tests.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	673 <note>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	674 Only the first 256k of the response body are examined.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	675 </note>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	676 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	677
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	678 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	679 Examples:
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	680 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	681 # status is 200, content type is "text/html",
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	682 # and body contains "Welcome to nginx!"
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	683 match welcome {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	684 status 200;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	685 header Content-Type = text/html;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	686 body ~ "Welcome to nginx!";
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	687 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	688 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	689
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	690 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	691 # status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	692 match not_redirect {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	693 status ! 301-303 307;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	694 header ! Refresh;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	695 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	696 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	697
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	698 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	699 # status ok and not in maintenance mode
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	700 match server_ok {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	701 status 200-399;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	702 body !~ "maintenance mode";
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	703 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	704 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	705
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	706 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	707
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	708 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	709 <note>
1088 379cb572a7ec Paraphrased sentences that mention "commercial subscription". Ruslan Ermilov <ru@nginx.com> parents: 1075 diff changeset	710 This directive is available as part of our <commercial_version/>.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	711 </note>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	712 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	713
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	714 </directive>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	715
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	716
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	717 <directive name="sticky">
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	718 <syntax><literal>cookie</literal> <value>name</value>
1001 35ae9ded0465 Updated the "sticky" directive description. Vladimir Homutov <vl@nginx.com> parents: 988 diff changeset	719 [<literal>expires=</literal><value>time</value>]
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	720 [<literal>domain=</literal><value>domain</value>]
1001 35ae9ded0465 Updated the "sticky" directive description. Vladimir Homutov <vl@nginx.com> parents: 988 diff changeset	721 [<literal>path=</literal><value>path</value>]</syntax>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	722 <syntax><literal>route</literal> <value>variable</value> ...</syntax>
987 edd505634357 Documented the "sticky" directive. Vladimir Homutov <vl@nginx.com> parents: 981 diff changeset	723 <default/>
edd505634357 Documented the "sticky" directive. Vladimir Homutov <vl@nginx.com> parents: 981 diff changeset	724 <context>upstream</context>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	725 <appeared-in>1.5.7</appeared-in>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	726
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	727 <para>
962 f3754c623e6b Minor editing of the stiky_cookie_insert directive. Egor Nikitin <yegor.nikitin@gmail.com> parents: 960 diff changeset	728 Enables session affinity, which causes requests from the same client to be
960 48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	729 passed to the same server in a group of servers.
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	730 Two methods are available,
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	731 <literal>cookie</literal> and <literal>route</literal>.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	732 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	733
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	734 <para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	735 When the <literal>cookie</literal> method is used, information about the
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	736 designated server is passed in an HTTP cookie:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	737 <example>
960 48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	738 upstream backend {
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	739 server backend1.example.com;
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	740 server backend2.example.com;
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	741
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	742 sticky cookie srv_id expires=1h domain=.example.com path=/;
960 48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	743 }
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	744 </example>
960 48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	745 </para>
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	746
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	747 <para>
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	748 A request that comes from a client not yet bound to a particular server
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	749 is passed to the server selected by the configured balancing method.
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	750 Further requests from the same client are passed to the same server.
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	751 If the designated server cannot process a request, the new server is
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	752 selected as if the client has not been bound yet.
960 48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	753 </para>
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	754
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	755 <para>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	756 The first parameter sets the name of the cookie to be set or inspected.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	757 Additional parameters may be as follows:
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	758 <list type="tag">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	759
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	760 <tag-name><literal>expires</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	761 <tag-desc>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	762 Sets the time for which a browser should keep the cookie.
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	763 The special value <literal>max</literal> will cause the cookie to expire on
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	764 “<literal>31 Dec 2037 23:55:55 GMT</literal>”.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	765 This is the maximum time understood by old browsers.
960 48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	766 If the parameter is not specified, it will cause the cookie to expire at
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	767 the end of a browser session.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	768 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	769
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	770 <tag-name><literal>domain</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	771 <tag-desc>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	772 Defines the domain for which the cookie is set.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	773 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	774
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	775 <tag-name><literal>path</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	776 <tag-desc>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	777 Defines the path for which the cookie is set.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	778 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	779
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	780 </list>
981 fc35441b4856 Fixed grammar. Vladimir Homutov <vl@nginx.com> parents: 969 diff changeset	781 If any parameters are omitted, the corresponding cookie fields are not set.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	782 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	783
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	784 <para>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	785 When the <literal>route</literal> method is used, proxied server assigns
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	786 client a route on receipt of the first request.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	787 All subsequent requests from this client will carry routing information
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	788 in a cookie or URI.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	789 This information is compared with the “<literal>route</literal>” parameter
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	790 of the <link id="server"/> directive to identify the server to which the
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	791 request should be proxied.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	792 If the designated server cannot process a request, the new server is
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	793 selected by the configured balancing method as if there is no routing
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	794 information in the request.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	795 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	796
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	797 <para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	798 The parameters of the <literal>route</literal> method specify variables that
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	799 may contain routing information.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	800 The first non-empty variable is used to find the matching server.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	801 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	802
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	803 <para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	804 Example:
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	805 <example>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	806 map $cookie_jsessionid $route_cookie {
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	807 ~.+\.(?P<route>\w+)$ $route;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	808 }
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	809
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	810 map $request_uri $route_uri {
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	811 ~jsessionid=.+\.(?P<route>\w+)$ $route;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	812 }
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	813
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	814 upstream backend {
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	815 server backend1.example.com route=a;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	816 server backend2.example.com route=b;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	817
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	818 sticky route $route_cookie $route_uri;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	819 }
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	820 </example>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	821 Here, the route is taken from the “<literal>JSESSIONID</literal>” cookie
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	822 if present in a request.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	823 Otherwise, the route from the URI is used.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	824 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	825
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	826 <para>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	827 <note>
1088 379cb572a7ec Paraphrased sentences that mention "commercial subscription". Ruslan Ermilov <ru@nginx.com> parents: 1075 diff changeset	828 This directive is available as part of our <commercial_version/>.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	829 </note>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	830 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	831
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	832 </directive>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	833
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	834
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	835 <directive name="sticky_cookie_insert">
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	836 <syntax><value>name</value>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	837 [<literal>expires=</literal><value>time</value>]
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	838 [<literal>domain=</literal><value>domain</value>]
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	839 [<literal>path=</literal><value>path</value>]</syntax>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	840 <default/>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	841 <context>upstream</context>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	842
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	843 <para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	844 This directive is obsolete since version 1.5.7.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	845 An equivalent
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	846 <link id="sticky"/> directive with a new syntax should be used instead:
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	847 <note>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	848 <literal>sticky cookie</literal> <value>name</value>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	849 [<literal>expires=</literal><value>time</value>]
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	850 [<literal>domain=</literal><value>domain</value>]
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	851 [<literal>path=</literal><value>path</value>];
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	852 </note>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	853 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	854
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	855 </directive>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	856
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	857
1122 594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	858 <directive name="queue">
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	859 <syntax>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	860 <value>number</value>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	861 [<literal>timeout</literal>=<value>time</value>]</syntax>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	862 <default/>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	863 <context>upstream</context>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	864 <appeared-in>1.5.12</appeared-in>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	865
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	866 <para>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	867 If an upstream server cannot be selected immediately
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	868 while processing a request,
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	869 and there are the servers in the group that have reached the
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	870 <link id="max_conns"/> limit,
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	871 the request will be placed into the queue.
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	872 The directive specifies the maximum number of requests that can be in the queue
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	873 at the same time.
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	874 If the queue is filled up,
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	875 or the server to pass the request to cannot been selected within
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	876 the time period specified in the <literal>timeout</literal> parameter,
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	877 an error will be returned to the client.
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	878 </para>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	879
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	880 <para>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	881 The default value of the <literal>timeout</literal> parameter is 60 seconds.
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	882 </para>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	883
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	884 <para>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	885 <note>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	886 This directive is available as part of our <commercial_version/>.
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	887 </note>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	888 </para>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	889
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	890 </directive>
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	891
594093ef96b1 Upstream: documented the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1119 diff changeset	892
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	893 <directive name="upstream_conf">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	894 <syntax/>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	895 <default/>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	896 <context>location</context>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	897
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	898 <para>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	899 Turns on the HTTP interface of upstream configuration in the surrounding
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	900 location.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	901 Access to this location should be
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	902 <link doc="ngx_http_core_module.xml" id="satisfy">limited</link>.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	903 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	904
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	905 <para>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	906 Configuration commands can be used to:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	907 <list type="bullet">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	908
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	909 <listitem>view all primary or backup servers in a group;</listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	910
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	911 <listitem>view an individual server;</listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	912
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	913 <listitem>modify an individual server;</listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	914
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	915 <listitem>add a new server (see the note below);</listitem>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	916
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	917 <listitem>remove an individual server.</listitem>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	918
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	919 </list>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	920 <note>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	921 As noted in the <link id="server"/> directive, specifying a server
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	922 as a domain name may result in several servers being added to the group.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	923 Since addresses in a group are not required to be unique, individual
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	924 servers in a group can be uniquely referenced to only by their ID.
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	925 IDs are assigned automatically and shown on viewing of the group configuration.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	926 </note>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	927 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	928
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	929 <para>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	930 A configuration command consists of parameters passed as request arguments,
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	931 for example:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	932 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	933 http://127.0.0.1/upstream_conf?upstream=appservers
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	934 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	935 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	936
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	937 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	938 The following parameters are supported:
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	939
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	940 <list type="tag" compact="no">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	941
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	942 <tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	943 <literal>upstream=</literal><value>name</value></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	944 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	945 Selects a group.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	946 This parameter is mandatory.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	947 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	948
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	949 <tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	950 <literal>backup=</literal>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	951 </tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	952 <tag-desc>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	953 If not set, selects primary servers in the group.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	954 If set, selects backup servers in the group.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	955 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	956
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	957 <tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	958 <literal>id=</literal><value>number</value></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	959 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	960 Selects an individual primary or backup server in the group.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	961 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	962
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	963 <tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	964 <literal>remove=</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	965 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	966 Removes an individual primary or backup server from the group.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	967 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	968
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	969 <tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	970 <literal>add=</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	971 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	972 Adds a new primary or backup server to the group.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	973 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	974
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	975 <tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	976 <literal>server=</literal><value>address</value></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	977 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	978 Same as the “<literal>address</literal>” parameter
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	979 of the <link id="server"/> directive.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	980 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	981
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	982 <tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	983 <literal>weight=</literal><value>number</value></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	984 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	985 Same as the “<literal>weight</literal>” parameter
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	986 of the <link id="server"/> directive.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	987 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	988
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	989 <tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	990 <literal>max_fails=</literal><value>number</value></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	991 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	992 Same as the “<literal>max_fails</literal>” parameter
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	993 of the <link id="server"/> directive.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	994 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	995
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	996 <tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	997 <literal>fail_timeout=</literal><value>time</value></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	998 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	999 Same as the “<literal>fail_timeout</literal>” parameter
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1000 of the <link id="server"/> directive.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1001 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1002
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1003 <tag-name>
955 28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	1004 <literal>slow_start=</literal><value>time</value></tag-name>
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	1005 <tag-desc>
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	1006 Same as the “<literal>slow_start</literal>” parameter
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	1007 of the <link id="server"/> directive.
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	1008 </tag-desc>
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	1009
28d580f1eb63 Documented the "slow_start" parameter of the upstream "server" directive. Vladimir Homutov <vl@nginx.com> parents: 953 diff changeset	1010 <tag-name>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1011 <literal>down=</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1012 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1013 Same as the “<literal>down</literal>” parameter
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1014 of the <link id="server"/> directive.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1015 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1016
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1017 <tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1018 <literal>up=</literal></tag-name>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1019 <tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1020 The opposite of the “<literal>down</literal>” parameter
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1021 of the <link id="server"/> directive.
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1022 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1023
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1024 <tag-name>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1025 <literal>route=</literal><value>string</value></tag-name>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1026 <tag-desc>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1027 Same as the “<literal>route</literal>” parameter
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1028 of the <link id="server"/> directive.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1029 </tag-desc>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1030
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1031 </list>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1032
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1033 The first three parameters select a target the command applies to.
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1034 Without other parameters, the command shows configuration of the selected
488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1035 target.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1036 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1037
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1038 <para>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1039 For example, to view the primary servers in the group, send:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1040 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1041 http://127.0.0.1/upstream_conf?upstream=appservers
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1042 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1043
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1044 To view the backup servers in the group, send:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1045 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1046 http://127.0.0.1/upstream_conf?upstream=appservers&backup=
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1047 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1048
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1049 To view an individual primary server in the group, send:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1050 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1051 http://127.0.0.1/upstream_conf?upstream=appservers&id=42
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1052 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1053
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1054 To view an individual backup server in the group, send:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1055 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1056 http://127.0.0.1/upstream_conf?upstream=appservers&backup=&id=42
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1057 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1058 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1059
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1060 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1061 To add a new primary or backup server to the group,
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1062 specify its address in the “<literal>server=</literal>” parameter.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1063 Without other parameters specified, a server will be added with other
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1064 parameters set to their default values (see the <link id="server"/> directive).
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1065 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1066
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1067 <para>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1068 For example, to add a new primary server to the group, send:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1069 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1070 http://127.0.0.1/upstream_conf?add=&upstream=appservers&server=127.0.0.1:8080
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1071 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1072
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1073 To add a new backup server to the group, send:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1074 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1075 http://127.0.0.1/upstream_conf?add=&upstream=appservers&backup=&server=127.0.0.1:8080
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1076 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1077
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1078 To add a new primary server to the group,
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1079 set its parameters to non-default values
968 fa19bacf6e1e Unified upstream server up/down state terminology. Vladimir Homutov <vl@nginx.com> parents: 966 diff changeset	1080 and mark it as “<literal>down</literal>”, send:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1081 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1082 http://127.0.0.1/upstream_conf?add=&upstream=appservers&server=127.0.0.1:8080&weight=2&max_fails=3&fail_timeout=3s&down=
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1083 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1084 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1085
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1086 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1087 To remove an individual primary or backup server from the group,
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1088 select it with the <literal>id=</literal> parameter.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1089 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1090
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1091 <para>
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1092 For example, to remove an individual primary server from the group, send:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1093 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1094 http://127.0.0.1/upstream_conf?remove=&upstream=appservers&id=42
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1095 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1096
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1097 To remove an individual backup server from the group, send:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1098 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1099 http://127.0.0.1/upstream_conf?remove=&upstream=appservers&backup=&id=42
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1100 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1101 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1102
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1103 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1104 To modify an individual primary or backup server in the group,
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1105 select it with the <literal>id=</literal> parameter.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1106 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1107
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1108 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1109 For example, to modify an individual primary server in the group
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1110 by marking it as “<literal>down</literal>”, send:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1111 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1112 http://127.0.0.1/upstream_conf?upstream=appservers&id=42&down=
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1113 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1114
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1115 To modify the address of an individual backup server in the group, send:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1116 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1117 http://127.0.0.1/upstream_conf?upstream=appservers&backup=&id=42&server=192.0.2.3:8123
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1118 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1119
956 488a3f738db0 Text revision of commercial modules. Egor Nikitin <yegor.nikitin@gmail.com> parents: 955 diff changeset	1120 To modify other parameters of an individual primary server in the group, send:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1121 <example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1122 http://127.0.0.1/upstream_conf?upstream=appservers&id=42&max_fails=3&weight=4
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1123 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1124
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1125 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1126
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1127 <para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1128 <note>
1088 379cb572a7ec Paraphrased sentences that mention "commercial subscription". Ruslan Ermilov <ru@nginx.com> parents: 1075 diff changeset	1129 This directive is available as part of our <commercial_version/>.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1130 </note>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1131 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1132
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1133 </directive>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1134
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1135 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1136
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1137
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1138 <section id="variables" name="Embedded Variables">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1139
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1140 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1141 The <literal>ngx_http_upstream_module</literal> module
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1142 supports the following embedded variables:
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1143 <list type="tag">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1144
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1145 <tag-name><var>$upstream_addr</var></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1146 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1147 keeps the IP address and port of the server,
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1148 or the path to the UNIX-domain socket.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1149 If several servers were contacted during request processing,
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1150 their addresses are separated by commas, e.g.
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1151 “<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock</literal>”.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1152 If an internal redirect from one server group to another happens,
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1153 initiated by
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1154 <header>X-Accel-Redirect</header> or
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1155 <link doc="ngx_http_core_module.xml" id="error_page"/>,
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1156 then the server addresses from different groups are separated by colons, e.g.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1157 “<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>”.
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1158 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1159
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1160 <tag-name><var>$upstream_cache_status</var></tag-name>
f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1161 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1162 keeps the status of accessing a response cache (0.8.3).
1075 6c021feec587 Removed unjustified non-breakable spaces. Ruslan Ermilov <ru@nginx.com> parents: 1026 diff changeset	1163 The status can be either “<literal>MISS</literal>”,
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1164 “<literal>BYPASS</literal>”, “<literal>EXPIRED</literal>”,
1011 2ad2f30efdf2 Documented the "fastcgi_" and "proxy_cache_revalidate" directives. Vladimir Homutov <vl@nginx.com> parents: 1003 diff changeset	1165 “<literal>STALE</literal>”, “<literal>UPDATING</literal>”,
2ad2f30efdf2 Documented the "fastcgi_" and "proxy_cache_revalidate" directives. Vladimir Homutov <vl@nginx.com> parents: 1003 diff changeset	1166 “<literal>REVALIDATED</literal>” or “<literal>HIT</literal>”.
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1167 </tag-desc>
f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1168
f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1169 <tag-name><var>$upstream_response_length</var></tag-name>
f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1170 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1171 keeps the lengths of responses obtained from the upstream servers (0.7.27);
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1172 lengths are kept in bytes.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1173 Several response lengths are separated by commas and colons
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1174 like addresses in the <var>$upstream_addr</var> variable.
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1175 </tag-desc>
f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1176
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1177 <tag-name><var>$upstream_response_time</var></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1178 <tag-desc>
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1179 keeps times of responses obtained from upstream servers;
f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1180 times are kept in seconds with a milliseconds resolution.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1181 Several response times are separated by commas and colons
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1182 like addresses in the <var>$upstream_addr</var> variable.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1183 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1184
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1185 <tag-name><var>$upstream_status</var></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1186 <tag-desc>
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1187 keeps codes of responses obtained from upstream servers.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1188 Several response codes are separated by commas and colons
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1189 like addresses in the <var>$upstream_addr</var> variable.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1190 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1191
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1192 <tag-name><var>$upstream_http_...</var></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1193 <tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1194 keep server response header fields.
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1195 For example, the <header>Server</header> response header field
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1196 is available through the <var>$upstream_http_server</var> variable.
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1197 The rules of converting header field names to variable names are the same
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1198 as for the variables that start with the
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1199 “<link doc="ngx_http_core_module.xml" id="variables">$http_</link>” prefix.
f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1200 Only the last server’s response header fields are saved.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1201 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1202
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1203 </list>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1204 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1205
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1206 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1207
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1208 </module>

Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_upstream_module.xml @ 1123:9a9aa8e9d12c