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

annotate xml/en/docs/http/ngx_http_upstream_module.xml @ 2197:03f8a9c5e8ae

Updated link in the "random" directive.

author	Yaroslav Zhuravlev <yar@nginx.com>
date	Mon, 02 Jul 2018 18:53:12 +0300
parents	2c56f91c304a
children	0974dc0a6209

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"
2197 03f8a9c5e8ae Updated link in the "random" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2191 diff changeset	13 rev="72">
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"/>,
1181 b8f0362f61e5 Added links to scgi. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	21 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>,
1194 9264fdb6c833 Added links to uwsgi. Ruslan Ermilov <ru@nginx.com> parents: 1186 diff changeset	22 <link doc="ngx_http_uwsgi_module.xml" id="uwsgi_pass"/>,
2134 4cafd82e5007 Added info about gRPC to various modules. Yaroslav Zhuravlev <yar@nginx.com> parents: 2113 diff changeset	23 <link doc="ngx_http_scgi_module.xml" id="scgi_pass"/>,
4cafd82e5007 Added info about gRPC to various modules. Yaroslav Zhuravlev <yar@nginx.com> parents: 2113 diff changeset	24 <link doc="ngx_http_memcached_module.xml" id="memcached_pass"/>, and
4cafd82e5007 Added info about gRPC to various modules. Yaroslav Zhuravlev <yar@nginx.com> parents: 2113 diff changeset	25 <link doc="ngx_http_grpc_module.xml" id="grpc_pass"/> directives.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	26 </para>
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>
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
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	31 <section id="example" name="Example Configuration">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	32
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	33 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	34 <example>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	35 upstream <emphasis>backend</emphasis> {
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	36 server backend1.example.com weight=5;
1424 410e0683b6b4 Rolled back changes in the example of the upstream module. Yaroslav Zhuravlev <yar@nginx.com> parents: 1423 diff changeset	37 server backend2.example.com:8080;
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	38 server unix:/tmp/backend3;
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 server backup1.example.com:8080 backup;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	41 server backup2.example.com:8080 backup;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	42 }
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	43
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	44 server {
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	45 location / {
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	46 proxy_pass http://<emphasis>backend</emphasis>;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	47 }
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	48 }
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	49 </example>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	50 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	51
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	52 <para>
1945 88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module. Yaroslav Zhuravlev <yar@nginx.com> parents: 1925 diff changeset	53 Dynamically configurable group with
88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module. Yaroslav Zhuravlev <yar@nginx.com> parents: 1925 diff changeset	54 periodic <link doc="ngx_http_upstream_hc_module.xml">health checks</link> is
1128 1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	55 available as part of our
1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	56 <commercial_version>commercial subscription</commercial_version>:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	57 <example>
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	58 resolver 10.0.0.1;
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	59
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	60 upstream <emphasis>dynamic</emphasis> {
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	61 zone upstream_dynamic 64k;
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	62
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	63 server backend1.example.com weight=5;
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	64 server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	65 server 192.0.2.1 max_fails=3;
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	66 server backend3.example.com resolve;
1680 57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	67 server backend4.example.com service=http resolve;
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	68
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	69 server backup1.example.com:8080 backup;
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	70 server backup2.example.com:8080 backup;
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	71 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	72
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	73 server {
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	74 location / {
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	75 proxy_pass http://<emphasis>dynamic</emphasis>;
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	76 health_check;
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	77 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	78 }
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	79 </example>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	80 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	81
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	82 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	83
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	84
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	85 <section id="directives" name="Directives">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	86
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	87 <directive name="upstream">
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	88 <syntax block="yes"><value>name</value></syntax>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	89 <default/>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	90 <context>http</context>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	91
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	92 <para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	93 Defines a group of servers.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	94 Servers can listen on different ports.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	95 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	96 can be mixed.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	97 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	98
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	99 <para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	100 Example:
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	101 <example>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	102 upstream backend {
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	103 server backend1.example.com weight=5;
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	104 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	105 server unix:/tmp/backend3;
1126 2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	106
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	107 server backup1.example.com backup;
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	108 }
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	109 </example>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	110 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	111
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	112 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	113 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	114 weighted round-robin balancing method.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	115 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	116 5 requests go to <literal>backend1.example.com</literal>
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	117 and one request to each of the second and third servers.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	118 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	119 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	120 servers will be tried.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	121 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	122 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	123 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	124
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	125 </directive>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	126
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 <directive name="server">
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	129 <syntax><value>address</value> [<value>parameters</value>]</syntax>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	130 <default/>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	131 <context>upstream</context>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	132
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	133 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	134 Defines the <value>address</value> and other <value>parameters</value>
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	135 of a server.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	136 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	137 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	138 specified after the “<literal>unix:</literal>” prefix.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	139 If a port is not specified, the port 80 is used.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	140 A domain name that resolves to several IP addresses defines
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	141 multiple servers at once.
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	142 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	143
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	144 <para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	145 The following parameters can be defined:
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	146 <list type="tag">
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	147
1241 2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	148 <tag-name id="weight">
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	149 <literal>weight</literal>=<value>number</value>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	150 </tag-name>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	151 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	152 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	153 </tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	154
1800 9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	155 <tag-name id="max_conns">
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	156 <literal>max_conns</literal>=<value>number</value>
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	157 </tag-name>
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	158 <tag-desc>
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	159 limits the maximum <value>number</value> of simultaneous active
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	160 connections to the proxied server (1.11.5).
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	161 Default value is zero, meaning there is no limit.
1801 592f9fa804f6 Added info about shared memory to max_conns. Yaroslav Zhuravlev <yar@nginx.com> parents: 1800 diff changeset	162 If the server group does not reside in the <link id="zone">shared memory</link>,
592f9fa804f6 Added info about shared memory to max_conns. Yaroslav Zhuravlev <yar@nginx.com> parents: 1800 diff changeset	163 the limitation works per each worker process.
1800 9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	164 <note>
1801 592f9fa804f6 Added info about shared memory to max_conns. Yaroslav Zhuravlev <yar@nginx.com> parents: 1800 diff changeset	165 If <link id="keepalive">idle keepalive</link> connections,
592f9fa804f6 Added info about shared memory to max_conns. Yaroslav Zhuravlev <yar@nginx.com> parents: 1800 diff changeset	166 multiple <link doc="../ngx_core_module.xml" id="worker_processes">workers</link>,
592f9fa804f6 Added info about shared memory to max_conns. Yaroslav Zhuravlev <yar@nginx.com> parents: 1800 diff changeset	167 and the <link id="zone">shared memory</link> are enabled,
592f9fa804f6 Added info about shared memory to max_conns. Yaroslav Zhuravlev <yar@nginx.com> parents: 1800 diff changeset	168 the total number of active and idle connections to the proxied server
1800 9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	169 may exceed the <literal>max_conns</literal> value.
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	170 </note>
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	171 <note>
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	172 Since version 1.5.9 and prior to version 1.11.5,
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	173 this parameter was available as part of our
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	174 <commercial_version>commercial subscription</commercial_version>.
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	175 </note>
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	176 </tag-desc>
9d722e4153ab Documented the "max_conns" parameter as opensource. Yaroslav Zhuravlev <yar@nginx.com> parents: 1783 diff changeset	177
1241 2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	178 <tag-name id="max_fails">
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	179 <literal>max_fails</literal>=<value>number</value>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	180 </tag-name>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	181 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	182 sets the number of unsuccessful attempts to communicate with the server
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	183 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	184 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	185 <literal>fail_timeout</literal> parameter.
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	186 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	187 The zero value disables the accounting of attempts.
942 ba3d6ade3513 Elaborate on upstream server failures. Ruslan Ermilov <ru@nginx.com> parents: 917 diff changeset	188 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	189 <link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>,
1181 b8f0362f61e5 Added links to scgi. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	190 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>,
1194 9264fdb6c833 Added links to uwsgi. Ruslan Ermilov <ru@nginx.com> parents: 1186 diff changeset	191 <link doc="ngx_http_uwsgi_module.xml" id="uwsgi_next_upstream"/>,
2134 4cafd82e5007 Added info about gRPC to various modules. Yaroslav Zhuravlev <yar@nginx.com> parents: 2113 diff changeset	192 <link doc="ngx_http_scgi_module.xml" id="scgi_next_upstream"/>,
4cafd82e5007 Added info about gRPC to various modules. Yaroslav Zhuravlev <yar@nginx.com> parents: 2113 diff changeset	193 <link doc="ngx_http_memcached_module.xml" id="memcached_next_upstream"/>, and
4cafd82e5007 Added info about gRPC to various modules. Yaroslav Zhuravlev <yar@nginx.com> parents: 2113 diff changeset	194 <link doc="ngx_http_grpc_module.xml" id="grpc_next_upstream"/>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	195 directives.
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	196 </tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	197
1241 2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	198 <tag-name id="fail_timeout">
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	199 <literal>fail_timeout</literal>=<value>time</value>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	200 </tag-name>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	201 <tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	202 sets
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	203 <list type="bullet">
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	204
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	205 <listitem>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	206 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	207 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	208 </listitem>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	209
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	210 <listitem>
968 fa19bacf6e1e Unified upstream server up/down state terminology. Vladimir Homutov <vl@nginx.com> parents: 966 diff changeset	211 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	212 </listitem>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	213
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	214 </list>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	215 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	216 </tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	217
1241 2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	218 <tag-name id="backup">
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	219 <literal>backup</literal>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	220 </tag-name>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	221 <tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	222 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	223 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	224 </tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	225
1241 2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	226 <tag-name id="down">
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	227 <literal>down</literal>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	228 </tag-name>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	229 <tag-desc>
1410 f5dcc23b214f Deleted info about hash and ip_hash from the down parameter. Yaroslav Zhuravlev <yar@nginx.com> parents: 1393 diff changeset	230 marks the server as permanently unavailable.
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	231 </tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	232
1126 2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	233 </list>
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	234 </para>
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	235
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	236 <para>
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	237 Additionally,
1128 1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	238 the following parameters are available as part of our
1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	239 <commercial_version>commercial subscription</commercial_version>:
1126 2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	240 <list type="tag">
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	241
1124 d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	242 <tag-name id="resolve">
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	243 <literal>resolve</literal>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	244 </tag-name>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	245 <tag-desc>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	246 monitors changes of the IP addresses
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	247 that correspond to a domain name of the server,
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	248 and automatically modifies the upstream configuration
1127 948c853f5d22 Upstream: improved "server resolve". Ruslan Ermilov <ru@nginx.com> parents: 1126 diff changeset	249 without the need of restarting nginx (1.5.12).
1581 201bf8fa69e5 Added shared memory requirement to resolver in http and stream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1561 diff changeset	250 The server group must reside in the <link id="zone">shared memory</link>.
1124 d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	251 <para>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	252 In order for this parameter to work,
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	253 the <link doc="ngx_http_core_module.xml" id="resolver"/> directive
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	254 must be specified in the
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	255 <link doc="ngx_http_core_module.xml" id="http"/> block.
1127 948c853f5d22 Upstream: improved "server resolve". Ruslan Ermilov <ru@nginx.com> parents: 1126 diff changeset	256 Example:
1124 d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	257 <example>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	258 http {
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	259 resolver 10.0.0.1;
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	260
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	261 upstream u {
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	262 zone ...;
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	263 ...
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	264 server example.com resolve;
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	265 }
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	266 }
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	267 </example>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	268 </para>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	269 </tag-desc>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	270
1241 2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	271 <tag-name id="route">
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	272 <literal>route</literal>=<value>string</value>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	273 </tag-name>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	274 <tag-desc>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	275 sets the server route name.
1126 2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	276 </tag-desc>
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	277
1680 57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	278 <tag-name id="service">
1700 1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	279 <literal>service</literal>=<value>name</value>
1680 57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	280 </tag-name>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	281 <tag-desc>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	282 enables resolving of DNS
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	283 <link url="https://tools.ietf.org/html/rfc2782">SRV</link>
1700 1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	284 records and sets the service <value>name</value> (1.9.13).
1680 57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	285 In order for this parameter to work, it is necessary to specify
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	286 the <link id="resolve"/> parameter for the server
1700 1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	287 and specify a hostname without a port number.
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	288 <para>
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	289 If the service name does not contain a dot (“<literal>.</literal>”), then
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	290 the <link url="https://tools.ietf.org/html/rfc2782">RFC</link>-compliant name
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	291 is constructed
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	292 and the TCP protocol is added to the service prefix.
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	293 For example, to look up the
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	294 <literal>_http._tcp.backend.example.com</literal> SRV record,
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	295 it is necessary to specify the directive:
1680 57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	296 <example>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	297 server backend.example.com service=http resolve;
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	298 </example>
1700 1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	299 If the service name contains one or more dots, then the name is constructed
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	300 by joining the service prefix and the server name.
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	301 For example, to look up the <literal>_http._tcp.backend.example.com</literal>
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	302 and <literal>server1.backend.example.com</literal> SRV records,
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	303 it is necessary to specify the directives:
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	304 <example>
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	305 server backend.example.com service=_http._tcp resolve;
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	306 server example.com service=server1.backend resolve;
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	307 </example>
1680 57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	308 </para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	309
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	310 <para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	311 Highest-priority SRV records
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	312 (records with the same lowest-number priority value)
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	313 are resolved as primary servers,
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	314 the rest of SRV records are resolved as backup servers.
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	315 If the <link id="backup"/> parameter is specified for the server,
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	316 high-priority SRV records are resolved as backup servers,
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	317 the rest of SRV records are ignored.
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	318 </para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	319 </tag-desc>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	320
1241 2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	321 <tag-name id="slow_start">
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	322 <literal>slow_start</literal>=<value>time</value>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	323 </tag-name>
1126 2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	324 <tag-desc>
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	325 sets the <value>time</value> during which the server will recover its weight
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	326 from zero to a nominal value, when unhealthy server becomes
1945 88477c5d2751 Moved "health_check" and "match" to ngx_http_upstream_hc_module. Yaroslav Zhuravlev <yar@nginx.com> parents: 1925 diff changeset	327 <link doc="ngx_http_upstream_hc_module.xml" id="health_check">healthy</link>,
1126 2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	328 or when the server becomes available after a period of time
1241 2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	329 it was considered <link id="fail_timeout">unavailable</link>.
1126 2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	330 Default value is zero, i.e. slow start is disabled.
1817 0160e8784417 Documented behavior of server slow_start with ip_hash and hash. Yaroslav Zhuravlev <yar@nginx.com> parents: 1809 diff changeset	331 <note>
0160e8784417 Documented behavior of server slow_start with ip_hash and hash. Yaroslav Zhuravlev <yar@nginx.com> parents: 1809 diff changeset	332 The parameter cannot be used along with the
0160e8784417 Documented behavior of server slow_start with ip_hash and hash. Yaroslav Zhuravlev <yar@nginx.com> parents: 1809 diff changeset	333 <link id="hash"/> and <link id="ip_hash"/> load balancing methods.
0160e8784417 Documented behavior of server slow_start with ip_hash and hash. Yaroslav Zhuravlev <yar@nginx.com> parents: 1809 diff changeset	334 </note>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	335 </tag-desc>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	336
2082 fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	337 <tag-name id="drain">
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	338 <literal>drain</literal>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	339 </tag-name>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	340 <tag-desc>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	341 puts the server into the “draining” mode (1.13.6).
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	342 In this mode, only requests <link id="sticky">bound</link> to the server
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	343 will be proxied to it.
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	344 <note>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	345 Prior to version 1.13.6,
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	346 the parameter could be changed only with the
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	347 <link doc="ngx_http_api_module.xml">API</link> module.
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	348 </note>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	349 </tag-desc>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	350
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	351 </list>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	352 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	353
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	354 <para>
969 7c542520b8f7 Added note about behavior of a single server in an upstream. Vladimir Homutov <vl@nginx.com> parents: 968 diff changeset	355 <note>
7c542520b8f7 Added note about behavior of a single server in an upstream. Vladimir Homutov <vl@nginx.com> parents: 968 diff changeset	356 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	357 <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	358 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	359 </note>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	360 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	361
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	362 </directive>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	363
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	364
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	365 <directive name="zone">
1495 8d134b482cc3 Documented zone usage with many upstreams. Yaroslav Zhuravlev <yar@nginx.com> parents: 1481 diff changeset	366 <syntax><value>name</value> [<value>size</value>]</syntax>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	367 <default/>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	368 <context>upstream</context>
1461 4e5cab61e548 Documented status of the zone directive in ngx_http_upstream module. Vladimir Homutov <vl@nginx.com> parents: 1450 diff changeset	369 <appeared-in>1.9.0</appeared-in>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	370
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	371 <para>
1123 9a9aa8e9d12c Rephrased the "zone" directive, translated into Russian. Yaroslav Zhuravlev <yar@nginx.com> parents: 1122 diff changeset	372 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	373 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	374 shared between worker processes.
1495 8d134b482cc3 Documented zone usage with many upstreams. Yaroslav Zhuravlev <yar@nginx.com> parents: 1481 diff changeset	375 Several groups may share the same zone.
8d134b482cc3 Documented zone usage with many upstreams. Yaroslav Zhuravlev <yar@nginx.com> parents: 1481 diff changeset	376 In this case, it is enough to specify the <value>size</value> only once.
1461 4e5cab61e548 Documented status of the zone directive in ngx_http_upstream module. Vladimir Homutov <vl@nginx.com> parents: 1450 diff changeset	377 </para>
4e5cab61e548 Documented status of the zone directive in ngx_http_upstream module. Vladimir Homutov <vl@nginx.com> parents: 1450 diff changeset	378
4e5cab61e548 Documented status of the zone directive in ngx_http_upstream module. Vladimir Homutov <vl@nginx.com> parents: 1450 diff changeset	379 <para>
4e5cab61e548 Documented status of the zone directive in ngx_http_upstream module. Vladimir Homutov <vl@nginx.com> parents: 1450 diff changeset	380 Additionally,
4e5cab61e548 Documented status of the zone directive in ngx_http_upstream module. Vladimir Homutov <vl@nginx.com> parents: 1450 diff changeset	381 as part of our <commercial_version>commercial subscription</commercial_version>,
4e5cab61e548 Documented status of the zone directive in ngx_http_upstream module. Vladimir Homutov <vl@nginx.com> parents: 1450 diff changeset	382 such groups allow changing the group membership
1123 9a9aa8e9d12c Rephrased the "zone" directive, translated into Russian. Yaroslav Zhuravlev <yar@nginx.com> parents: 1122 diff changeset	383 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	384 without the need of restarting nginx.
2097 27c53e1cb4b6 Deprecated upstream_conf in the "zone" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2082 diff changeset	385 The configuration is accessible via the
27c53e1cb4b6 Deprecated upstream_conf in the "zone" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2082 diff changeset	386 <link doc="ngx_http_api_module.xml">API</link> module (1.13.3).
27c53e1cb4b6 Deprecated upstream_conf in the "zone" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2082 diff changeset	387 <note>
27c53e1cb4b6 Deprecated upstream_conf in the "zone" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2082 diff changeset	388 Prior to version 1.13.3,
27c53e1cb4b6 Deprecated upstream_conf in the "zone" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2082 diff changeset	389 the configuration was accessible only via a special location
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	390 handled by
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	391 <link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf"/>.
2097 27c53e1cb4b6 Deprecated upstream_conf in the "zone" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2082 diff changeset	392 </note>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	393 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	394
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	395 </directive>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	396
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	397
1636 44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	398 <directive name="state">
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	399 <syntax><value>file</value></syntax>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	400 <default/>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	401 <context>upstream</context>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	402 <appeared-in>1.9.7</appeared-in>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	403
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	404 <para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	405 Specifies a <value>file</value> that keeps the state
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	406 of the dynamically configurable group.
1809 2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	407 </para>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	408
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	409 <para>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	410 Examples:
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	411 <example>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	412 state /var/lib/nginx/state/servers.conf; # path for Linux
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	413 state /var/db/nginx/state/servers.conf; # path for FreeBSD
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	414 </example>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	415 </para>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	416
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	417 <para>
1636 44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	418 The state is currently limited to the list of servers with their parameters.
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	419 The file is read when parsing the configuration and is updated each time
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	420 the upstream configuration is
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	421 <link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf">changed</link>.
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	422 Changing the file content directly should be avoided.
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	423 The directive cannot be used
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	424 along with the <link id="server"/> directive.
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	425 </para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	426
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	427 <para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	428 <note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	429 Changes made during
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	430 <link doc="../control.xml" id="reconfiguration">configuration reload</link>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	431 or <link doc="../control.xml" id="upgrade">binary upgrade</link>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	432 can be lost.
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	433 </note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	434 </para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	435
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	436 <para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	437 <note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	438 This directive is available as part of our
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	439 <commercial_version>commercial subscription</commercial_version>.
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	440 </note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	441 </para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	442
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	443 </directive>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	444
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	445
1230 6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	446 <directive name="hash">
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	447 <syntax><value>key</value> [<literal>consistent</literal>]</syntax>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	448 <default/>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	449 <context>upstream</context>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	450 <appeared-in>1.7.2</appeared-in>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	451
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	452 <para>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	453 Specifies a load balancing method for a server group
1367 f1e14d87d833 Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1348 diff changeset	454 where the client-server mapping is based on the hashed <value>key</value> value.
1230 6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	455 The <value>key</value> can contain text, variables, and their combinations.
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	456 Note that adding or removing a server from the group
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	457 may result in remapping most of the keys to different servers.
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	458 The method is compatible with the
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	459 <link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached">Cache::Memcached</link>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	460 Perl library.
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	461 </para>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	462
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	463 <para>
1367 f1e14d87d833 Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1348 diff changeset	464 If the <literal>consistent</literal> parameter is specified
1230 6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	465 the <link url="http://www.last.fm/user/RJ/journal/2007/04/10/392555/">ketama</link>
1367 f1e14d87d833 Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1348 diff changeset	466 consistent hashing method will be used instead.
1230 6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	467 The method ensures that only a few keys
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	468 will be remapped to different servers
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	469 when a server is added to or removed from the group.
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	470 This helps to achieve a higher cache hit ratio for caching servers.
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	471 The method is compatible with the
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	472 <link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached%3A%3AFast">Cache::Memcached::Fast</link>
1236 def99e640654 Fixed grammar. Sergey Kandaurov <pluknet@nginx.com> parents: 1233 diff changeset	473 Perl library with the <value>ketama_points</value> parameter set to 160.
1230 6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	474 </para>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	475
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	476 </directive>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	477
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	478
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	479 <directive name="ip_hash">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	480 <syntax/>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	481 <default/>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	482 <context>upstream</context>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	483
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	484 <para>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	485 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	486 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	487 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	488 are used as a hashing key.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	489 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	490 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	491 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	492 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	493 <note>
566 f8148fc88224 Documented 1.2.2 changes. Ruslan Ermilov <ru@nginx.com> parents: 542 diff changeset	494 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	495 </note>
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	496 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	497
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	498 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	499 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	500 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	501 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	502 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	503
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	504 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	505 Example:
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	506 <example>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	507 upstream backend {
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	508 ip_hash;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	509
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	510 server backend1.example.com;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	511 server backend2.example.com;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	512 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	513 server backend4.example.com;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	514 }
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	515 </example>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	516 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	517
526 4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	518 <para>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	519 <note>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	520 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	521 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	522 </note>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	523 </para>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	524
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	525 </directive>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	526
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	527
316 1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	528 <directive name="keepalive">
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	529 <syntax><value>connections</value></syntax>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	530 <default/>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	531 <context>upstream</context>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	532 <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	533
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	534 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	535 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	536 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	537
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	538 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	539 The <value>connections</value> parameter sets the maximum number of
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	540 idle keepalive connections to upstream servers that are preserved in
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	541 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	542 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	543 are closed.
316 1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	544 <note>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	545 It should be particularly noted that the <literal>keepalive</literal> directive
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	546 does not limit the total number of connections to upstream servers
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	547 that an nginx worker process can open.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	548 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	549 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	550 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	551 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	552
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	553 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	554 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	555 <example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	556 upstream memcached_backend {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	557 server 127.0.0.1:11211;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	558 server 10.0.0.2:11211;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	559
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	560 keepalive 32;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	561 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	562
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	563 server {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	564 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	565
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	566 location /memcached/ {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	567 set $memcached_key $uri;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	568 memcached_pass memcached_backend;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	569 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	570
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	571 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	572 </example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	573 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	574
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	575 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	576 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	577 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	578 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	579 <example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	580 upstream http_backend {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	581 server 127.0.0.1:8080;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	582
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	583 keepalive 16;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	584 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	585
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	586 server {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	587 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	588
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	589 location /http/ {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	590 proxy_pass http://http_backend;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	591 proxy_http_version 1.1;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	592 proxy_set_header Connection "";
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	593 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	594 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	595 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	596 </example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	597 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	598
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	599 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	600 <note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	601 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	602 <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	603 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	604 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	605 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	606
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	607 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	608 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	609 <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	610 for keepalive connections to work:
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	611 <example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	612 upstream fastcgi_backend {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	613 server 127.0.0.1:9000;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	614
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	615 keepalive 8;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	616 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	617
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	618 server {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	619 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	620
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	621 location /fastcgi/ {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	622 fastcgi_pass fastcgi_backend;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	623 fastcgi_keep_conn on;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	624 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	625 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	626 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	627 </example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	628 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	629
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	630 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	631 <note>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	632 When using load balancer methods other than the default
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	633 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	634 the <literal>keepalive</literal> directive.
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	635 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	636
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	637 <note>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	638 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	639 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	640 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	641
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	642 </directive>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	643
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	644
1561 ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	645 <directive name="ntlm">
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	646 <syntax/>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	647 <default/>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	648 <context>upstream</context>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	649 <appeared-in>1.9.2</appeared-in>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	650
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	651 <para>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	652 Allows proxying requests with
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	653 <link url="https://en.wikipedia.org/wiki/Integrated_Windows_Authentication">NTLM
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	654 Authentication</link>.
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	655 The upstream connection is bound to the client connection
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	656 once the client sends a request with the <header>Authorization</header>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	657 header field value
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	658 starting with “<literal>Negotiate</literal>” or “<literal>NTLM</literal>”.
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	659 Further client requests will be proxied through the same upstream connection,
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	660 keeping the authentication context.
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	661 </para>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	662
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	663 <para>
1587 c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	664 In order for NTLM authentication to work,
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	665 it is necessary to enable keepalive connections to upstream servers.
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	666 The <link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	667 directive should be set to “<literal>1.1</literal>”
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	668 and the <header>Connection</header> header field should be cleared:
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	669 <example>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	670 upstream http_backend {
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	671 server 127.0.0.1:8080;
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	672
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	673 ntlm;
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	674 }
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	675
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	676 server {
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	677 ...
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	678
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	679 location /http/ {
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	680 proxy_pass http://http_backend;
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	681 proxy_http_version 1.1;
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	682 proxy_set_header Connection "";
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	683 ...
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	684 }
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	685 }
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	686 </example>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	687 </para>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	688
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	689 <para>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	690 <note>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	691 When using load balancer methods other than the default
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	692 round-robin method, it is necessary to activate them before
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	693 the <literal>ntlm</literal> directive.
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	694 </note>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	695 </para>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	696
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	697 <para>
1561 ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	698 <note>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	699 This directive is available as part of our
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	700 <commercial_version>commercial subscription</commercial_version>.
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	701 </note>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	702 </para>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	703
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	704 </directive>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	705
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	706
526 4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	707 <directive name="least_conn">
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	708 <syntax/>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	709 <default/>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	710 <context>upstream</context>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	711 <appeared-in>1.3.1</appeared-in>
566 f8148fc88224 Documented 1.2.2 changes. Ruslan Ermilov <ru@nginx.com> parents: 542 diff changeset	712 <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	713
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	714 <para>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	715 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	716 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	717 taking into account weights of servers.
1232 ab2ea38f3512 Upstream: least_conn description corresponds to the Russian text. Yaroslav Zhuravlev <yar@nginx.com> parents: 1230 diff changeset	718 If there are several such servers, they are tried in turn using a
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	719 weighted round-robin balancing method.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	720 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	721
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	722 </directive>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	723
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	724
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	725 <directive name="least_time">
1925 a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	726 <syntax>
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	727 <literal>header</literal> \|
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	728 <literal>last_byte</literal>
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	729 [<literal>inflight</literal>]</syntax>
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	730 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	731 <context>upstream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	732 <appeared-in>1.7.10</appeared-in>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	733
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	734 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	735 Specifies that a group should use a load balancing method where a request
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	736 is passed to the server with the least average response time and
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	737 least number of active connections, taking into account weights of servers.
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	738 If there are several such servers, they are tried in turn using a
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	739 weighted round-robin balancing method.
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	740 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	741
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	742 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	743 If the <literal>header</literal> parameter is specified,
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	744 time to receive the
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	745 <link id="var_upstream_header_time">response header</link> is used.
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	746 If the <literal>last_byte</literal> parameter is specified,
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	747 time to receive the <link id="var_upstream_response_time">full response</link>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	748 is used.
1925 a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	749 If the <literal>inflight</literal> parameter is specified (1.11.6),
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	750 incomplete requests are also taken into account.
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	751 <note>
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	752 Prior to version 1.11.6, incomplete requests were taken into account by default.
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	753 </note>
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	754 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	755
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	756 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	757 <note>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	758 This directive is available as part of our
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	759 <commercial_version>commercial subscription</commercial_version>.
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	760 </note>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	761 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	762
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	763 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	764
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	765
1125 9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	766 <directive name="queue">
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	767 <syntax>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	768 <value>number</value>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	769 [<literal>timeout</literal>=<value>time</value>]</syntax>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	770 <default/>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	771 <context>upstream</context>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	772 <appeared-in>1.5.12</appeared-in>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	773
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	774 <para>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	775 If an upstream server cannot be selected immediately
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	776 while processing a request,
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	777 the request will be placed into the queue.
2067 014323d0cc38 Highlighted the "number" value in the queue directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2062 diff changeset	778 The directive specifies the maximum <value>number</value> of requests
014323d0cc38 Highlighted the "number" value in the queue directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2062 diff changeset	779 that can be in the queue at the same time.
1125 9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	780 If the queue is filled up,
1543 08242a0abf11 Fixed grammar in the upstream queue directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1504 diff changeset	781 or the server to pass the request to cannot be selected within
1125 9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	782 the time period specified in the <literal>timeout</literal> parameter,
1625 0ba4b2e561bd Added 502 error to the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1587 diff changeset	783 the <http-status code="502" text="Bad Gateway"/>
0ba4b2e561bd Added 502 error to the "queue" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1587 diff changeset	784 error will be returned to the client.
1125 9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	785 </para>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	786
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	787 <para>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	788 The default value of the <literal>timeout</literal> parameter is 60 seconds.
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	789 </para>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	790
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	791 <para>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	792 <note>
1925 a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	793 When using load balancer methods other than the default
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	794 round-robin method, it is necessary to activate them before
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	795 the <literal>queue</literal> directive.
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	796 </note>
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	797
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	798 <note>
1128 1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	799 This directive is available as part of our
1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	800 <commercial_version>commercial subscription</commercial_version>.
1125 9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	801 </note>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	802 </para>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	803
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	804 </directive>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	805
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	806
2191 2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	807 <directive name="random">
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	808 <syntax>[<literal>two</literal> [<value>method</value>]]</syntax>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	809 <default/>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	810 <context>upstream</context>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	811 <appeared-in>1.15.1</appeared-in>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	812
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	813 <para>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	814 Specifies that a group should use a load balancing method where a request
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	815 is passed to a randomly selected server, taking into account weights
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	816 of servers.
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	817 </para>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	818
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	819 <para>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	820 The optional <literal>two</literal> parameter
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	821 instructs nginx to randomly select
2197 03f8a9c5e8ae Updated link in the "random" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2191 diff changeset	822 <link url="https://homes.cs.washington.edu/~karlin/papers/balls.pdf">two</link>
2191 2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	823 servers and then choose a server
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	824 using the specified <literal>method</literal>.
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	825 The default method is <literal>least_conn</literal>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	826 which passes a request to a server
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	827 with the least number of active connections.
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	828 </para>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	829
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	830 </directive>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	831
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	832
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	833 <directive name="sticky">
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	834 <syntax>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	835 <literal>cookie</literal> <value>name</value>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	836 [<literal>expires=</literal><value>time</value>]
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	837 [<literal>domain=</literal><value>domain</value>]
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	838 [<literal>httponly</literal>]
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	839 [<literal>secure</literal>]
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	840 [<literal>path=</literal><value>path</value>]</syntax>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	841 <syntax>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	842 <literal>route</literal> <value>$variable</value> ...</syntax>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	843 <syntax>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	844 <literal>learn</literal>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	845 <literal>create=</literal><value>$variable</value>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	846 <literal>lookup=</literal><value>$variable</value>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	847 <literal>zone=</literal><value>name</value>:<value>size</value>
2028 5c55b7054b58 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1945 diff changeset	848 [<literal>timeout=</literal><value>time</value>]
2139 f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	849 [<literal>header</literal>]
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	850 [<literal>sync</literal>]</syntax>
987 edd505634357 Documented the "sticky" directive. Vladimir Homutov <vl@nginx.com> parents: 981 diff changeset	851 <default/>
edd505634357 Documented the "sticky" directive. Vladimir Homutov <vl@nginx.com> parents: 981 diff changeset	852 <context>upstream</context>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	853 <appeared-in>1.5.7</appeared-in>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	854
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	855 <para>
962 f3754c623e6b Minor editing of the stiky_cookie_insert directive. Egor Nikitin <yegor.nikitin@gmail.com> parents: 960 diff changeset	856 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	857 passed to the same server in a group of servers.
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	858 Three methods are available:
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	859 <list type="tag">
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	860 <tag-name id="sticky_cookie"><literal>cookie</literal></tag-name>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	861 <tag-desc>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	862
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	863 <para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	864 When the <literal>cookie</literal> method is used, information about the
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	865 designated server is passed in an HTTP cookie generated by nginx:
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	866 <example>
960 48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	867 upstream backend {
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	868 server backend1.example.com;
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	869 server backend2.example.com;
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	870
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	871 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	872 }
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	873 </example>
960 48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	874 </para>
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	875
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	876 <para>
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	877 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	878 is passed to the server selected by the configured balancing method.
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	879 Further requests with this cookie will be passed to the designated server.
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	880 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	881 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	882 </para>
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	883
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	884 <para>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	885 The first parameter sets the name of the cookie to be set or inspected.
2041 29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	886 The cookie value is
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	887 a hexadecimal representation of the MD5 hash of the IP address and port,
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	888 or of the UNIX-domain socket path.
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	889 However, if the “<literal>route</literal>” parameter of the
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	890 <link id="server"/> directive is specified, the cookie value will be
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	891 the value of the “<literal>route</literal>” parameter:
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	892 <example>
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	893 upstream backend {
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	894 server backend1.example.com route=<emphasis>a</emphasis>;
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	895 server backend2.example.com route=<emphasis>b</emphasis>;
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	896
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	897 sticky cookie srv_id expires=1h domain=.example.com path=/;
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	898 }
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	899 </example>
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	900 In this case, the value of the “<literal>srv_id</literal>” cookie will be
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	901 either <value>a</value> or <value>b</value>.
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	902 </para>
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	903
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	904 <para>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	905 Additional parameters may be as follows:
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	906 <list type="tag">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	907
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	908 <tag-name><literal>expires=</literal><value>time</value></tag-name>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	909 <tag-desc>
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	910 Sets the <value>time</value> for which a browser should keep the cookie.
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	911 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	912 “<literal>31 Dec 2037 23:55:55 GMT</literal>”.
960 48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	913 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	914 the end of a browser session.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	915 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	916
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	917 <tag-name><literal>domain=</literal><value>domain</value></tag-name>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	918 <tag-desc>
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	919 Defines the <value>domain</value> for which the cookie is set.
1825 56b6244ddadb Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1818 diff changeset	920 Parameter value can contain variables (1.11.5).
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	921 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	922
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	923 <tag-name><literal>httponly</literal></tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	924 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	925 Adds the <literal>HttpOnly</literal> attribute to the cookie (1.7.11).
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	926 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	927
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	928 <tag-name><literal>secure</literal></tag-name>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	929 <tag-desc>
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	930 Adds the <literal>Secure</literal> attribute to the cookie (1.7.11).
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	931
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	932 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	933
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	934 <tag-name><literal>path=</literal><value>path</value></tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	935 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	936 Defines the <value>path</value> for which the cookie is set.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	937 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	938
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	939 </list>
981 fc35441b4856 Fixed grammar. Vladimir Homutov <vl@nginx.com> parents: 969 diff changeset	940 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	941 </para>
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	942 </tag-desc>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	943
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	944 <tag-name id="sticky_route"><literal>route</literal></tag-name>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	945 <tag-desc>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	946
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	947 <para>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	948 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	949 client a route on receipt of the first request.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	950 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	951 in a cookie or URI.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	952 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	953 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	954 request should be proxied.
1854 dca985318cfe Documented default value for server route in sticky route. Yaroslav Zhuravlev <yar@nginx.com> parents: 1825 diff changeset	955 If the “<literal>route</literal>” parameter is not specified, the route name
dca985318cfe Documented default value for server route in sticky route. Yaroslav Zhuravlev <yar@nginx.com> parents: 1825 diff changeset	956 will be a hexadecimal representation of the MD5 hash of the IP address and port,
dca985318cfe Documented default value for server route in sticky route. Yaroslav Zhuravlev <yar@nginx.com> parents: 1825 diff changeset	957 or of the UNIX-domain socket path.
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	958 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	959 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	960 information in the request.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	961 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	962
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	963 <para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	964 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	965 may contain routing information.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	966 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	967 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	968
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	969 <para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	970 Example:
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	971 <example>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	972 map $cookie_jsessionid $route_cookie {
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	973 ~.+\.(?P<route>\w+)$ $route;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	974 }
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	975
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	976 map $request_uri $route_uri {
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	977 ~jsessionid=.+\.(?P<route>\w+)$ $route;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	978 }
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	979
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	980 upstream backend {
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	981 server backend1.example.com route=a;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	982 server backend2.example.com route=b;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	983
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	984 sticky route $route_cookie $route_uri;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	985 }
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	986 </example>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	987 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	988 if present in a request.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	989 Otherwise, the route from the URI is used.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	990 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	991
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	992 </tag-desc>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	993
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	994 <tag-name id="sticky_learn"><literal>learn</literal></tag-name>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	995 <tag-desc>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	996 <para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	997 When the <literal>learn</literal> method (1.7.1) is used, nginx
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	998 analyzes upstream server responses and learns server-initiated sessions
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	999 usually passed in an HTTP cookie.
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1000 <example>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1001 upstream backend {
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1002 server backend1.example.com:8080;
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1003 server backend2.example.com:8081;
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1004
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1005 sticky learn
1544 627a9309011c Renamed cookie in the example of the sticky directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1543 diff changeset	1006 create=$upstream_cookie_examplecookie
627a9309011c Renamed cookie in the example of the sticky directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1543 diff changeset	1007 lookup=$cookie_examplecookie
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1008 zone=client_sessions:1m;
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1009 }
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1010 </example>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1011
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1012 In the example, the upstream server creates a session by setting the
1544 627a9309011c Renamed cookie in the example of the sticky directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1543 diff changeset	1013 cookie “<literal>EXAMPLECOOKIE</literal>” in the response.
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1014 Further requests with this cookie will be passed to the same server.
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1015 If the server cannot process the request, the new server is
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1016 selected as if the client has not been bound yet.
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1017 </para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1018
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1019 <para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1020 The parameters <literal>create</literal> and <literal>lookup</literal>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1021 specify variables that indicate how new sessions are created and existing
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1022 sessions are searched, respectively.
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1023 Both parameters may be specified more than once, in which case the first
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1024 non-empty variable is used.
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1025 </para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1026
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1027 <para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1028 Sessions are stored in a shared memory zone, whose <value>name</value> and
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1029 <value>size</value> are configured by the <literal>zone</literal> parameter.
2139 f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1030 One megabyte zone can store about 4000 sessions on the 64-bit platform.
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1031 The sessions that are not accessed during the time specified by the
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1032 <literal>timeout</literal> parameter get removed from the zone.
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1033 By default, <literal>timeout</literal> is set to 10 minutes.
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1034 </para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1035
2028 5c55b7054b58 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1945 diff changeset	1036 <para id="sticky_learn_header">
5c55b7054b58 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1945 diff changeset	1037 The <literal>header</literal> parameter (1.13.1) allows creating a session
5c55b7054b58 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1945 diff changeset	1038 right after receiving response headers from the upstream server.
5c55b7054b58 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1945 diff changeset	1039 </para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1945 diff changeset	1040
2139 f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1041 <para id="sticky_learn_sync">
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1042 The <literal>sync</literal> parameter (1.13.8) enables
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1043 <link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">synchronization</link>
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1044 of the shared memory zone.
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1045 </para>
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1046
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1047 </tag-desc>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1048 </list>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1049 </para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1050
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1051 <para>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1052 <note>
1128 1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	1053 This directive is available as part of our
1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	1054 <commercial_version>commercial subscription</commercial_version>.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1055 </note>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1056 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1057
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1058 </directive>
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
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1061 <directive name="sticky_cookie_insert">
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1062 <syntax><value>name</value>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1063 [<literal>expires=</literal><value>time</value>]
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1064 [<literal>domain=</literal><value>domain</value>]
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1065 [<literal>path=</literal><value>path</value>]</syntax>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1066 <default/>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1067 <context>upstream</context>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1068
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1069 <para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1070 This directive is obsolete since version 1.5.7.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1071 An equivalent
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1072 <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	1073 <note>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1074 <literal>sticky cookie</literal> <value>name</value>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1075 [<literal>expires=</literal><value>time</value>]
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1076 [<literal>domain=</literal><value>domain</value>]
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1077 [<literal>path=</literal><value>path</value>];
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1078 </note>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1079 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1080
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1081 </directive>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1082
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1083 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1084
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1085
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1086 <section id="variables" name="Embedded Variables">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1087
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1088 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1089 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	1090 supports the following embedded variables:
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1091 <list type="tag">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1092
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1093 <tag-name id="var_upstream_addr"><var>$upstream_addr</var></tag-name>
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1094 <tag-desc>
1391 0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1095 keeps the IP address and port,
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1096 or the path to the UNIX-domain socket of the upstream server.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1097 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	1098 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	1099 “<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	1100 If an internal redirect from one server group to another happens,
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1101 initiated by
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1102 <header>X-Accel-Redirect</header> or
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1103 <link doc="ngx_http_core_module.xml" id="error_page"/>,
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1104 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	1105 “<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>”.
2058 eb58ee50561d Documented upstream name in $upstream_addr. Yaroslav Zhuravlev <yar@nginx.com> parents: 2041 diff changeset	1106 If a server cannot be selected,
eb58ee50561d Documented upstream name in $upstream_addr. Yaroslav Zhuravlev <yar@nginx.com> parents: 2041 diff changeset	1107 the variable keeps the name of the server group.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1108 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1109
1783 031566771bbd Documented $upstream_bytes_received for http upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1722 diff changeset	1110 <tag-name id="var_upstream_bytes_received"><var>$upstream_bytes_received</var></tag-name>
031566771bbd Documented $upstream_bytes_received for http upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1722 diff changeset	1111 <tag-desc>
031566771bbd Documented $upstream_bytes_received for http upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1722 diff changeset	1112 number of bytes received from an upstream server (1.11.4).
031566771bbd Documented $upstream_bytes_received for http upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1722 diff changeset	1113 Values from several connections
031566771bbd Documented $upstream_bytes_received for http upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1722 diff changeset	1114 are separated by commas and colons like addresses in the
031566771bbd Documented $upstream_bytes_received for http upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1722 diff changeset	1115 <link id="var_upstream_addr">$upstream_addr</link> variable.
031566771bbd Documented $upstream_bytes_received for http upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1722 diff changeset	1116 </tag-desc>
031566771bbd Documented $upstream_bytes_received for http upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1722 diff changeset	1117
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1118 <tag-name id="var_upstream_cache_status"><var>$upstream_cache_status</var>
07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1119 </tag-name>
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1120 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1121 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	1122 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	1123 “<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	1124 “<literal>STALE</literal>”, “<literal>UPDATING</literal>”,
1391 0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1125 “<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	1126 </tag-desc>
f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1127
1481 f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1128 <tag-name id="var_upstream_connect_time"><var>$upstream_connect_time</var>
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1129 </tag-name>
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1130 <tag-desc>
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1131 keeps time spent on establishing a connection with the upstream server (1.9.1);
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1132 the time is kept in seconds with millisecond resolution.
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1133 In case of SSL, includes time spent on handshake.
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1134 Times of several connections
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1135 are separated by commas and colons like addresses in the
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1136 <link id="var_upstream_addr">$upstream_addr</link> variable.
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1137 </tag-desc>
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1138
1186 8125bec5c7a1 Upstream: documented the $upstream_cookie_* variables. Ruslan Ermilov <ru@nginx.com> parents: 1181 diff changeset	1139 <tag-name id="var_upstream_cookie_"><var>$upstream_cookie_</var><value>name</value>
8125bec5c7a1 Upstream: documented the $upstream_cookie_* variables. Ruslan Ermilov <ru@nginx.com> parents: 1181 diff changeset	1140 </tag-name>
8125bec5c7a1 Upstream: documented the $upstream_cookie_* variables. Ruslan Ermilov <ru@nginx.com> parents: 1181 diff changeset	1141 <tag-desc>
8125bec5c7a1 Upstream: documented the $upstream_cookie_* variables. Ruslan Ermilov <ru@nginx.com> parents: 1181 diff changeset	1142 cookie with the specified <value>name</value> sent by the upstream server
8125bec5c7a1 Upstream: documented the $upstream_cookie_* variables. Ruslan Ermilov <ru@nginx.com> parents: 1181 diff changeset	1143 in the <header>Set-Cookie</header> response header field (1.7.1).
1391 0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1144 Only the cookies from the response of the last server are saved.
1186 8125bec5c7a1 Upstream: documented the $upstream_cookie_* variables. Ruslan Ermilov <ru@nginx.com> parents: 1181 diff changeset	1145 </tag-desc>
8125bec5c7a1 Upstream: documented the $upstream_cookie_* variables. Ruslan Ermilov <ru@nginx.com> parents: 1181 diff changeset	1146
1393 15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1147 <tag-name id="var_upstream_header_time"><var>$upstream_header_time</var>
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1148 </tag-name>
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1149 <tag-desc>
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1150 keeps time
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1151 spent on receiving the response header from the upstream server (1.7.10);
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1152 the time is kept in seconds with millisecond resolution.
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1153 Times of several responses
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1154 are separated by commas and colons like addresses in the
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1155 <link id="var_upstream_addr">$upstream_addr</link> variable.
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1156 </tag-desc>
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1157
1392 82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1158 <tag-name id="var_upstream_http_"><var>$upstream_http_</var><value>name</value></tag-name>
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1159 <tag-desc>
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1160 keep server response header fields.
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1161 For example, the <header>Server</header> response header field
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1162 is available through the <var>$upstream_http_server</var> variable.
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1163 The rules of converting header field names to variable names are the same
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1164 as for the variables that start with the
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1165 “<link doc="ngx_http_core_module.xml" id="var_http_">$http_</link>” prefix.
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1166 Only the header fields from the response of the last server are saved.
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1167 </tag-desc>
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1168
2139 f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1169 <tag-name id="var_upstream_queue_time"><var>$upstream_queue_time</var></tag-name>
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1170 <tag-desc>
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1171 keeps time the request spent in the upstream <link id="queue">queue</link>
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1172 (1.13.9);
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1173 the time is kept in seconds with millisecond resolution.
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1174 Times of several responses
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1175 are separated by commas and colons like addresses in the
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1176 <link id="var_upstream_addr">$upstream_addr</link> variable.
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1177 </tag-desc>
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1178
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1179 <tag-name id="var_upstream_response_length"><var>$upstream_response_length</var>
07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1180 </tag-name>
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1181 <tag-desc>
1391 0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1182 keeps the length of the response obtained from the upstream server (0.7.27);
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1183 the length is kept in bytes.
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1184 Lengths of several responses
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1185 are separated by commas and colons like addresses in the
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1186 <link id="var_upstream_addr">$upstream_addr</link> variable.
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1187 </tag-desc>
f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1188
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1189 <tag-name id="var_upstream_response_time"><var>$upstream_response_time</var>
07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1190 </tag-name>
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1191 <tag-desc>
1391 0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1192 keeps time spent on receiving the response from the upstream server;
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1193 the time is kept in seconds with millisecond resolution.
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1194 Times of several responses
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1195 are separated by commas and colons like addresses in the
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1196 <link id="var_upstream_addr">$upstream_addr</link> variable.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1197 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1198
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1199 <tag-name id="var_upstream_status"><var>$upstream_status</var></tag-name>
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1200 <tag-desc>
1391 0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1201 keeps status code of the response obtained from the upstream server.
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1202 Status codes of several responses
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1203 are separated by commas and colons like addresses in the
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1204 <link id="var_upstream_addr">$upstream_addr</link> variable.
2062 7275c134ec67 Documented "no live upstreams" case for $upstream_status. Yaroslav Zhuravlev <yar@nginx.com> parents: 2058 diff changeset	1205 If a server cannot be selected,
7275c134ec67 Documented "no live upstreams" case for $upstream_status. Yaroslav Zhuravlev <yar@nginx.com> parents: 2058 diff changeset	1206 the variable keeps the <http-status code="502" text="Bad Gateway"/> status code.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1207 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1208
2113 180269c4a220 Documented the "upstream_trailer_" variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 2097 diff changeset	1209 <tag-name id="var_upstream_trailer_"><var>$upstream_trailer_</var><value>name</value></tag-name>
180269c4a220 Documented the "upstream_trailer_" variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 2097 diff changeset	1210 <tag-desc>
180269c4a220 Documented the "upstream_trailer_" variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 2097 diff changeset	1211 keeps fields from the end of the response
180269c4a220 Documented the "upstream_trailer_" variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 2097 diff changeset	1212 obtained from the upstream server (1.13.10).
180269c4a220 Documented the "upstream_trailer_" variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 2097 diff changeset	1213 </tag-desc>
180269c4a220 Documented the "upstream_trailer_" variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 2097 diff changeset	1214
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1215 </list>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1216 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1217
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1218 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1219
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1220 </module>

Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_upstream_module.xml @ 2197:03f8a9c5e8ae