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

annotate xml/en/docs/http/ngx_http_upstream_module.xml @ 3029:27008cb3fb27

Updated docs for the upcoming NGINX Plus release.

author	Yaroslav Zhuravlev <yar@nginx.com>
date	Tue, 19 Dec 2023 12:58:01 +0000
parents	a2708cf6ebdb
children	9eadb98ec770

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"
2809 e642fe346261 Added note about requests distribution to sticky cookie. Yaroslav Zhuravlev <yar@nginx.com> parents: 2706 diff changeset	13 rev="88">
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.
2434 a1f61586779b Listed not supported load balancing methods in upstream backup. Yaroslav Zhuravlev <yar@nginx.com> parents: 2418 diff changeset	224 <note>
a1f61586779b Listed not supported load balancing methods in upstream backup. Yaroslav Zhuravlev <yar@nginx.com> parents: 2418 diff changeset	225 The parameter cannot be used along with the
a1f61586779b Listed not supported load balancing methods in upstream backup. Yaroslav Zhuravlev <yar@nginx.com> parents: 2418 diff changeset	226 <link id="hash"/>, <link id="ip_hash"/>, and <link id="random"/>
a1f61586779b Listed not supported load balancing methods in upstream backup. Yaroslav Zhuravlev <yar@nginx.com> parents: 2418 diff changeset	227 load balancing methods.
a1f61586779b Listed not supported load balancing methods in upstream backup. Yaroslav Zhuravlev <yar@nginx.com> parents: 2418 diff changeset	228 </note>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	229 </tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	230
1241 2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	231 <tag-name id="down">
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	232 <literal>down</literal>
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	233 </tag-name>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	234 <tag-desc>
1410 f5dcc23b214f Deleted info about hash and ip_hash from the down parameter. Yaroslav Zhuravlev <yar@nginx.com> parents: 1393 diff changeset	235 marks the server as permanently unavailable.
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	236 </tag-desc>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	237
1126 2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	238 </list>
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	239 </para>
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	240
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	241 <para>
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	242 Additionally,
1128 1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	243 the following parameters are available as part of our
1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	244 <commercial_version>commercial subscription</commercial_version>:
1126 2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	245 <list type="tag">
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	246
1124 d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	247 <tag-name id="resolve">
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	248 <literal>resolve</literal>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	249 </tag-name>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	250 <tag-desc>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	251 monitors changes of the IP addresses
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	252 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	253 and automatically modifies the upstream configuration
1127 948c853f5d22 Upstream: improved "server resolve". Ruslan Ermilov <ru@nginx.com> parents: 1126 diff changeset	254 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	255 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	256 <para>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	257 In order for this parameter to work,
2470 504536999408 Added upstream resolver info to upstream server resolve parameter. Yaroslav Zhuravlev <yar@nginx.com> parents: 2469 diff changeset	258 the <literal>resolver</literal> directive
1124 d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	259 must be specified in the
2470 504536999408 Added upstream resolver info to upstream server resolve parameter. Yaroslav Zhuravlev <yar@nginx.com> parents: 2469 diff changeset	260 <link doc="ngx_http_core_module.xml" id="resolver">http</link> block
504536999408 Added upstream resolver info to upstream server resolve parameter. Yaroslav Zhuravlev <yar@nginx.com> parents: 2469 diff changeset	261 or in the corresponding <link id="resolver">upstream</link> block.
1124 d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	262 </para>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	263 </tag-desc>
d790333947f4 Upstream: the "resolve" parameter of the "server" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1123 diff changeset	264
1241 2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	265 <tag-name id="route">
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	266 <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	267 </tag-name>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	268 <tag-desc>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	269 sets the server route name.
1126 2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	270 </tag-desc>
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	271
1680 57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	272 <tag-name id="service">
1700 1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	273 <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	274 </tag-name>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	275 <tag-desc>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	276 enables resolving of DNS
2831 4add6ae1296f Updated links to datatracker.ietf.org. Sergey Kandaurov <pluknet@nginx.com> parents: 2809 diff changeset	277 <link url="https://datatracker.ietf.org/doc/html/rfc2782">SRV</link>
1700 1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	278 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	279 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	280 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	281 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	282 <para>
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	283 If the service name does not contain a dot (“<literal>.</literal>”), then
2831 4add6ae1296f Updated links to datatracker.ietf.org. Sergey Kandaurov <pluknet@nginx.com> parents: 2809 diff changeset	284 the <link url="https://datatracker.ietf.org/doc/html/rfc2782">RFC</link>-compliant name
1700 1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	285 is constructed
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	286 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	287 For example, to look up the
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	288 <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	289 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	290 <example>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	291 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	292 </example>
1700 1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	293 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	294 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	295 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	296 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	297 it is necessary to specify the directives:
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	298 <example>
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	299 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	300 server example.com service=server1.backend resolve;
1dbef8ab47c7 Updated description of service parameter in upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1680 diff changeset	301 </example>
1680 57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	302 </para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	303
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	304 <para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	305 Highest-priority SRV records
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	306 (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	307 are resolved as primary servers,
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	308 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	309 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	310 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	311 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	312 </para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	313 </tag-desc>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1636 diff changeset	314
1241 2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	315 <tag-name id="slow_start">
2246339a6a93 Upstream: added IDs for "server" and "health_check" params. Yaroslav Zhuravlev <yar@nginx.com> parents: 1236 diff changeset	316 <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	317 </tag-name>
1126 2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	318 <tag-desc>
2e28d1c4a0a2 Upstream: revised layout of the "server" directive. Ruslan Ermilov <ru@nginx.com> parents: 1125 diff changeset	319 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	320 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	321 <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	322 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	323 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	324 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	325 <note>
0160e8784417 Documented behavior of server slow_start with ip_hash and hash. Yaroslav Zhuravlev <yar@nginx.com> parents: 1809 diff changeset	326 The parameter cannot be used along with the
2418 7e1af2148946 Updated note in slow_start with random load balancing method. Yaroslav Zhuravlev <yar@nginx.com> parents: 2307 diff changeset	327 <link id="hash"/>, <link id="ip_hash"/>, and <link id="random"/>
7e1af2148946 Updated note in slow_start with random load balancing method. Yaroslav Zhuravlev <yar@nginx.com> parents: 2307 diff changeset	328 load balancing methods.
1817 0160e8784417 Documented behavior of server slow_start with ip_hash and hash. Yaroslav Zhuravlev <yar@nginx.com> parents: 1809 diff changeset	329 </note>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	330 </tag-desc>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	331
2082 fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	332 <tag-name id="drain">
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	333 <literal>drain</literal>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	334 </tag-name>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	335 <tag-desc>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	336 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	337 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	338 will be proxied to it.
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	339 <note>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	340 Prior to version 1.13.6,
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	341 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	342 <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	343 </note>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	344 </tag-desc>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2067 diff changeset	345
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	346 </list>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	347 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	348
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	349 <para>
969 7c542520b8f7 Added note about behavior of a single server in an upstream. Vladimir Homutov <vl@nginx.com> parents: 968 diff changeset	350 <note>
7c542520b8f7 Added note about behavior of a single server in an upstream. Vladimir Homutov <vl@nginx.com> parents: 968 diff changeset	351 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	352 <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	353 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	354 </note>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	355 </para>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	356
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	357 </directive>
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	358
fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	359
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	360 <directive name="zone">
1495 8d134b482cc3 Documented zone usage with many upstreams. Yaroslav Zhuravlev <yar@nginx.com> parents: 1481 diff changeset	361 <syntax><value>name</value> [<value>size</value>]</syntax>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	362 <default/>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	363 <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	364 <appeared-in>1.9.0</appeared-in>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	365
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	366 <para>
1123 9a9aa8e9d12c Rephrased the "zone" directive, translated into Russian. Yaroslav Zhuravlev <yar@nginx.com> parents: 1122 diff changeset	367 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	368 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	369 shared between worker processes.
1495 8d134b482cc3 Documented zone usage with many upstreams. Yaroslav Zhuravlev <yar@nginx.com> parents: 1481 diff changeset	370 Several groups may share the same zone.
8d134b482cc3 Documented zone usage with many upstreams. Yaroslav Zhuravlev <yar@nginx.com> parents: 1481 diff changeset	371 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	372 </para>
4e5cab61e548 Documented status of the zone directive in ngx_http_upstream module. Vladimir Homutov <vl@nginx.com> parents: 1450 diff changeset	373
4e5cab61e548 Documented status of the zone directive in ngx_http_upstream module. Vladimir Homutov <vl@nginx.com> parents: 1450 diff changeset	374 <para>
4e5cab61e548 Documented status of the zone directive in ngx_http_upstream module. Vladimir Homutov <vl@nginx.com> parents: 1450 diff changeset	375 Additionally,
4e5cab61e548 Documented status of the zone directive in ngx_http_upstream module. Vladimir Homutov <vl@nginx.com> parents: 1450 diff changeset	376 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	377 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	378 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	379 without the need of restarting nginx.
2097 27c53e1cb4b6 Deprecated upstream_conf in the "zone" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2082 diff changeset	380 The configuration is accessible via the
27c53e1cb4b6 Deprecated upstream_conf in the "zone" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2082 diff changeset	381 <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	382 <note>
27c53e1cb4b6 Deprecated upstream_conf in the "zone" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2082 diff changeset	383 Prior to version 1.13.3,
27c53e1cb4b6 Deprecated upstream_conf in the "zone" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2082 diff changeset	384 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	385 handled by
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	386 <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	387 </note>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	388 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	389
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	390 </directive>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	391
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	392
1636 44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	393 <directive name="state">
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	394 <syntax><value>file</value></syntax>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	395 <default/>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	396 <context>upstream</context>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	397 <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	398
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	399 <para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	400 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	401 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	402 </para>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	403
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	404 <para>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	405 Examples:
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	406 <example>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	407 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	408 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	409 </example>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	410 </para>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	411
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1801 diff changeset	412 <para>
1636 44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	413 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	414 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	415 the upstream configuration is
2222 0974dc0a6209 Changed link from upstream_conf to api in "state". Yaroslav Zhuravlev <yar@nginx.com> parents: 2197 diff changeset	416 <link doc="ngx_http_api_module.xml" id="http_upstreams_http_upstream_name_servers_">changed</link>.
1636 44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	417 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	418 The directive cannot be used
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	419 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	420 </para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	421
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	422 <para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	423 <note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	424 Changes made during
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	425 <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	426 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	427 can be lost.
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 </para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	430
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	431 <para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	432 <note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	433 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	434 <commercial_version>commercial subscription</commercial_version>.
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	435 </note>
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
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	438 </directive>
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	439
44c4323144c5 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1625 diff changeset	440
1230 6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	441 <directive name="hash">
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	442 <syntax><value>key</value> [<literal>consistent</literal>]</syntax>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	443 <default/>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	444 <context>upstream</context>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	445 <appeared-in>1.7.2</appeared-in>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	446
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	447 <para>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	448 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	449 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	450 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	451 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	452 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	453 The method is compatible with the
2275 d93c8c32df75 Updated links to CPAN search interface. Sergey Kandaurov <pluknet@nginx.com> parents: 2274 diff changeset	454 <link url="https://metacpan.org/pod/Cache::Memcached">Cache::Memcached</link>
1230 6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	455 Perl library.
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	456 </para>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	457
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	458 <para>
2282 35fd70c12f98 Resynchronized the http and stream upstream module versions. Sergey Kandaurov <pluknet@nginx.com> parents: 2275 diff changeset	459 If the <literal>consistent</literal> parameter is specified,
2274 e28e3d0f0d20 Updated link in the "hash" directive. Sergey Kandaurov <pluknet@nginx.com> parents: 2230 diff changeset	460 the <link url="https://www.metabrew.com/article/libketama-consistent-hashing-algo-memcached-clients">ketama</link>
1367 f1e14d87d833 Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1348 diff changeset	461 consistent hashing method will be used instead.
1230 6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	462 The method ensures that only a few keys
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	463 will be remapped to different servers
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	464 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	465 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	466 The method is compatible with the
2275 d93c8c32df75 Updated links to CPAN search interface. Sergey Kandaurov <pluknet@nginx.com> parents: 2274 diff changeset	467 <link url="https://metacpan.org/pod/Cache::Memcached::Fast">Cache::Memcached::Fast</link>
1236 def99e640654 Fixed grammar. Sergey Kandaurov <pluknet@nginx.com> parents: 1233 diff changeset	468 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	469 </para>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	470
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	471 </directive>
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	472
6cc809881694 Upstream: added the "hash" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1194 diff changeset	473
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	474 <directive name="ip_hash">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	475 <syntax/>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	476 <default/>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	477 <context>upstream</context>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	478
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	479 <para>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	480 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	481 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	482 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	483 are used as a hashing key.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	484 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	485 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	486 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	487 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	488 <note>
566 f8148fc88224 Documented 1.2.2 changes. Ruslan Ermilov <ru@nginx.com> parents: 542 diff changeset	489 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	490 </note>
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	491 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	492
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	493 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	494 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	495 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	496 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	497 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	498
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	499 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	500 Example:
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	501 <example>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	502 upstream backend {
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	503 ip_hash;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	504
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	505 server backend1.example.com;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	506 server backend2.example.com;
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	507 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	508 server backend4.example.com;
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 </example>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	511 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	512
526 4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	513 <para>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	514 <note>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	515 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	516 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	517 </note>
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
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	520 </directive>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	521
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	522
316 1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	523 <directive name="keepalive">
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	524 <syntax><value>connections</value></syntax>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	525 <default/>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	526 <context>upstream</context>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	527 <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	528
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	529 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	530 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	531 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	532
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	533 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	534 The <value>connections</value> parameter sets the maximum number of
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	535 idle keepalive connections to upstream servers that are preserved in
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	536 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	537 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	538 are closed.
316 1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	539 <note>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	540 It should be particularly noted that the <literal>keepalive</literal> directive
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	541 does not limit the total number of connections to upstream servers
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	542 that an nginx worker process can open.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	543 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	544 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	545 </note>
2610 fdfe54a01ea1 Relocated note in keepalive directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2470 diff changeset	546
fdfe54a01ea1 Relocated note in keepalive directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2470 diff changeset	547 <note>
fdfe54a01ea1 Relocated note in keepalive directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2470 diff changeset	548 When using load balancing methods other than the default
fdfe54a01ea1 Relocated note in keepalive directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2470 diff changeset	549 round-robin method, it is necessary to activate them before
fdfe54a01ea1 Relocated note in keepalive directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2470 diff changeset	550 the <literal>keepalive</literal> directive.
fdfe54a01ea1 Relocated note in keepalive directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2470 diff changeset	551 </note>
316 1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	552 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	553
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	554 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	555 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	556 <example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	557 upstream memcached_backend {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	558 server 127.0.0.1:11211;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	559 server 10.0.0.2:11211;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	560
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	561 keepalive 32;
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
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	564 server {
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
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	567 location /memcached/ {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	568 set $memcached_key $uri;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	569 memcached_pass memcached_backend;
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 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	573 </example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	574 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	575
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	576 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	577 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	578 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	579 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	580 <example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	581 upstream http_backend {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	582 server 127.0.0.1:8080;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	583
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	584 keepalive 16;
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
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	587 server {
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
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	590 location /http/ {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	591 proxy_pass http://http_backend;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	592 proxy_http_version 1.1;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	593 proxy_set_header Connection "";
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 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	597 </example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	598 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	599
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	600 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	601 <note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	602 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	603 <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	604 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	605 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	606 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	607
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	608 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	609 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	610 <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	611 for keepalive connections to work:
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	612 <example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	613 upstream fastcgi_backend {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	614 server 127.0.0.1:9000;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	615
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	616 keepalive 8;
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
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	619 server {
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
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	622 location /fastcgi/ {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	623 fastcgi_pass fastcgi_backend;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	624 fastcgi_keep_conn on;
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 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	628 </example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	629 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	630
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	631 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	632 <note>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	633 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	634 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	635 </para>
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 </directive>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	638
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version", Ruslan Ermilov <ru@nginx.com> parents: 293 diff changeset	639
2223 a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	640 <directive name="keepalive_requests">
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	641 <syntax><value>number</value></syntax>
2706 4f44386a16b1 Changed default value of keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2705 diff changeset	642 <default>1000</default>
2223 a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	643 <context>upstream</context>
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	644 <appeared-in>1.15.3</appeared-in>
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	645
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	646 <para>
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	647 Sets the maximum number of requests that can be
2225 e2c3d17d0f58 Unified wording of upstream keepalive directives. Yaroslav Zhuravlev <yar@nginx.com> parents: 2223 diff changeset	648 served through one keepalive connection.
2223 a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	649 After the maximum number of requests is made, the connection is closed.
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	650 </para>
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	651
2450 a26a42699207 Added note about max number of keepalive requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2434 diff changeset	652 <para>
a26a42699207 Added note about max number of keepalive requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2434 diff changeset	653 Closing connections periodically is necessary to free
a26a42699207 Added note about max number of keepalive requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2434 diff changeset	654 per-connection memory allocations.
a26a42699207 Added note about max number of keepalive requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2434 diff changeset	655 Therefore, using too high maximum number of requests
a26a42699207 Added note about max number of keepalive requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2434 diff changeset	656 could result in excessive memory usage and not recommended.
a26a42699207 Added note about max number of keepalive requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2434 diff changeset	657 </para>
a26a42699207 Added note about max number of keepalive requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2434 diff changeset	658
2706 4f44386a16b1 Changed default value of keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2705 diff changeset	659 <para>
4f44386a16b1 Changed default value of keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2705 diff changeset	660 <note>
4f44386a16b1 Changed default value of keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2705 diff changeset	661 Prior to version 1.19.10, the default value was 100.
4f44386a16b1 Changed default value of keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2705 diff changeset	662 </note>
4f44386a16b1 Changed default value of keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2705 diff changeset	663 </para>
4f44386a16b1 Changed default value of keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2705 diff changeset	664
2223 a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	665 </directive>
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	666
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	667
2705 06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	668 <directive name="keepalive_time">
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	669 <syntax><value>time</value></syntax>
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	670 <default>1h</default>
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	671 <context>upstream</context>
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	672 <appeared-in>1.19.10</appeared-in>
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	673
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	674 <para>
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	675 Limits the maximum time during which
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	676 requests can be processed through one keepalive connection.
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	677 After this time is reached, the connection is closed
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	678 following the subsequent request processing.
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	679 </para>
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	680
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	681 </directive>
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	682
06805824d0f0 Documented the keepalive_time directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2632 diff changeset	683
2223 a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	684 <directive name="keepalive_timeout">
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	685 <syntax><value>timeout</value></syntax>
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	686 <default>60s</default>
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	687 <context>upstream</context>
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	688 <appeared-in>1.15.3</appeared-in>
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	689
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	690 <para>
2225 e2c3d17d0f58 Unified wording of upstream keepalive directives. Yaroslav Zhuravlev <yar@nginx.com> parents: 2223 diff changeset	691 Sets a timeout during which an idle keepalive
2223 a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	692 connection to an upstream server will stay open.
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	693 </para>
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	694
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	695 </directive>
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	696
a692df6ef304 Added upstream keepalive_timeout and keepalive_requests. Yaroslav Zhuravlev <yar@nginx.com> parents: 2222 diff changeset	697
1561 ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	698 <directive name="ntlm">
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	699 <syntax/>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	700 <default/>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	701 <context>upstream</context>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	702 <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	703
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	704 <para>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	705 Allows proxying requests with
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	706 <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	707 Authentication</link>.
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	708 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	709 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	710 header field value
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	711 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	712 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	713 keeping the authentication context.
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	714 </para>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	715
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	716 <para>
1587 c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	717 In order for NTLM authentication to work,
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	718 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	719 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	720 directive should be set to “<literal>1.1</literal>”
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	721 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	722 <example>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	723 upstream http_backend {
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	724 server 127.0.0.1:8080;
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	725
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	726 ntlm;
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	727 }
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	728
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	729 server {
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	730 ...
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	731
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	732 location /http/ {
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	733 proxy_pass http://http_backend;
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	734 proxy_http_version 1.1;
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	735 proxy_set_header Connection "";
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	736 ...
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	737 }
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	738 }
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	739 </example>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	740 </para>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	741
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	742 <para>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	743 <note>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	744 When using load balancer methods other than the default
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	745 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	746 the <literal>ntlm</literal> directive.
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	747 </note>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	748 </para>
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	749
c2a0a18e65ba Added keepalive info for ntlm. Yaroslav Zhuravlev <yar@nginx.com> parents: 1581 diff changeset	750 <para>
1561 ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	751 <note>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	752 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	753 <commercial_version>commercial subscription</commercial_version>.
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	754 </note>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	755 </para>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	756
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	757 </directive>
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	758
ed420c318557 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1544 diff changeset	759
526 4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	760 <directive name="least_conn">
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	761 <syntax/>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	762 <default/>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	763 <context>upstream</context>
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	764 <appeared-in>1.3.1</appeared-in>
566 f8148fc88224 Documented 1.2.2 changes. Ruslan Ermilov <ru@nginx.com> parents: 542 diff changeset	765 <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	766
4f907cde0382 1.3.1 changes: ip_hash+weight, least_conn. Ruslan Ermilov <ru@nginx.com> parents: 316 diff changeset	767 <para>
533 fb630c3c5039 Revamped the upstream documentation somewhat. Ruslan Ermilov <ru@nginx.com> parents: 526 diff changeset	768 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	769 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	770 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	771 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	772 weighted round-robin balancing method.
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	773 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	774
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	775 </directive>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	776
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	777
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	778 <directive name="least_time">
1925 a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	779 <syntax>
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	780 <literal>header</literal> \|
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	781 <literal>last_byte</literal>
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	782 [<literal>inflight</literal>]</syntax>
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	783 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	784 <context>upstream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	785 <appeared-in>1.7.10</appeared-in>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	786
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	787 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	788 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	789 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	790 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	791 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	792 weighted round-robin balancing method.
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	793 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	794
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	795 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	796 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	797 time to receive the
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	798 <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	799 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	800 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	801 is used.
1925 a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	802 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	803 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	804 <note>
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	805 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	806 </note>
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	807 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	808
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	809 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	810 <note>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	811 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	812 <commercial_version>commercial subscription</commercial_version>.
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	813 </note>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	814 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	815
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	816 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	817
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	818
1125 9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	819 <directive name="queue">
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	820 <syntax>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	821 <value>number</value>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	822 [<literal>timeout</literal>=<value>time</value>]</syntax>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	823 <default/>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	824 <context>upstream</context>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	825 <appeared-in>1.5.12</appeared-in>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	826
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	827 <para>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	828 If an upstream server cannot be selected immediately
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	829 while processing a request,
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	830 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	831 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	832 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	833 If the queue is filled up,
1543 08242a0abf11 Fixed grammar in the upstream queue directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1504 diff changeset	834 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	835 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	836 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	837 error will be returned to the client.
1125 9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	838 </para>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	839
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	840 <para>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	841 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	842 </para>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	843
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	844 <para>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	845 <note>
1925 a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	846 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	847 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	848 the <literal>queue</literal> directive.
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	849 </note>
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	850
a58b35cc0823 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1891 diff changeset	851 <note>
1128 1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	852 This directive is available as part of our
1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	853 <commercial_version>commercial subscription</commercial_version>.
1125 9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	854 </note>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	855 </para>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	856
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	857 </directive>
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	858
9a95b9026a16 Upstream: reallocated the "queue" directive. Ruslan Ermilov <ru@nginx.com> parents: 1124 diff changeset	859
2191 2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	860 <directive name="random">
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	861 <syntax>[<literal>two</literal> [<value>method</value>]]</syntax>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	862 <default/>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	863 <context>upstream</context>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	864 <appeared-in>1.15.1</appeared-in>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	865
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	866 <para>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	867 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	868 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	869 of servers.
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	870 </para>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	871
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	872 <para>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	873 The optional <literal>two</literal> parameter
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	874 instructs nginx to randomly select
2197 03f8a9c5e8ae Updated link in the "random" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 2191 diff changeset	875 <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	876 servers and then choose a server
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	877 using the specified <literal>method</literal>.
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	878 The default method is <literal>least_conn</literal>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	879 which passes a request to a server
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	880 with the least number of active connections.
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	881 </para>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	882
2230 283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	883 <para id="random_least_time">
283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	884 The <literal>least_time</literal> method passes a request to a server
283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	885 with the least average response time and least number of active connections.
283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	886 If <literal>least_time=header</literal> is specified, the time to receive the
283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	887 <link id="var_upstream_header_time">response header</link> is used.
283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	888 If <literal>least_time=last_byte</literal> is specified, the time to receive the
283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	889 <link id="var_upstream_response_time">full response</link> is used.
283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	890 <note>
283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	891 The <literal>least_time</literal> method is available as a part of our
283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	892 <commercial_version>commercial subscription</commercial_version>.
283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	893 </note>
283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	894 </para>
283b1e67eaa6 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2225 diff changeset	895
2191 2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	896 </directive>
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	897
2c56f91c304a Documented the "random" directive. Vladimir Homutov <vl@nginx.com> parents: 2139 diff changeset	898
2469 98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	899 <directive name="resolver">
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	900 <syntax>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	901 <value>address</value> ...
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	902 [<literal>valid</literal>=<value>time</value>]
2914 3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	903 [<literal>ipv4</literal>=<literal>on</literal>\|<literal>off</literal>]
2469 98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	904 [<literal>ipv6</literal>=<literal>on</literal>\|<literal>off</literal>]
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	905 [<literal>status_zone</literal>=<value>zone</value>]</syntax>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	906 <default/>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	907 <context>upstream</context>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	908 <appeared-in>1.17.5</appeared-in>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	909
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	910 <para>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	911 Configures name servers used to resolve names of upstream servers
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	912 into addresses, for example:
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	913 <example>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	914 resolver 127.0.0.1 [::1]:5353;
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	915 </example>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	916 The address can be specified as a domain name or IP address,
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	917 with an optional port.
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	918 If port is not specified, the port 53 is used.
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	919 Name servers are queried in a round-robin fashion.
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	920 </para>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	921
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	922 <para id="resolver_ipv6">
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	923 By default, nginx will look up both IPv4 and IPv6 addresses while resolving.
2914 3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	924 If looking up of IPv4 or IPv6 addresses is not desired,
3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	925 the <literal>ipv4=off</literal> (1.23.1) or
2469 98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	926 the <literal>ipv6=off</literal> parameter can be specified.
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	927 </para>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	928
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	929 <para id="resolver_valid">
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	930 By default, nginx caches answers using the TTL value of a response.
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	931 An optional <literal>valid</literal> parameter allows overriding it:
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	932 <example>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	933 resolver 127.0.0.1 [::1]:5353 valid=30s;
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	934 </example>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	935 <note>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	936 To prevent DNS spoofing, it is recommended
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	937 configuring DNS servers in a properly secured trusted local network.
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	938 </note>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	939 </para>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	940
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	941 <para id="resolver_status_zone">
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	942 The optional <literal>status_zone</literal> parameter
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	943 enables
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	944 <link doc="ngx_http_api_module.xml" id="resolvers_">collection</link>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	945 of DNS server statistics of requests and responses
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	946 in the specified <value>zone</value>.
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	947 </para>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	948
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	949 <para>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	950 <note>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	951 This directive is available as part of our
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	952 <commercial_version>commercial subscription</commercial_version>.
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	953 </note>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	954 </para>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	955
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	956 </directive>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	957
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	958
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	959 <directive name="resolver_timeout">
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	960 <syntax><value>time</value></syntax>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	961 <default>30s</default>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	962 <context>upstream</context>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	963 <appeared-in>1.17.5</appeared-in>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	964
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	965 <para>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	966 Sets a timeout for name resolution, for example:
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	967 <example>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	968 resolver_timeout 5s;
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	969 </example>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	970 </para>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	971
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	972 <para>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	973 <note>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	974 This directive is available as part of our
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	975 <commercial_version>commercial subscription</commercial_version>.
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	976 </note>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	977 </para>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	978
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	979 </directive>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	980
98fd810c13e0 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2450 diff changeset	981
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	982 <directive name="sticky">
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	983 <syntax>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	984 <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	985 [<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	986 [<literal>domain=</literal><value>domain</value>]
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	987 [<literal>httponly</literal>]
2914 3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	988 [<literal>samesite=</literal><literal>strict</literal>\|<literal>lax</literal>\|<literal>none</literal>\|<value>$variable</value>]
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	989 [<literal>secure</literal>]
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	990 [<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	991 <syntax>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	992 <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	993 <syntax>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	994 <literal>learn</literal>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	995 <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	996 <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	997 <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	998 [<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	999 [<literal>header</literal>]
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1000 [<literal>sync</literal>]</syntax>
987 edd505634357 Documented the "sticky" directive. Vladimir Homutov <vl@nginx.com> parents: 981 diff changeset	1001 <default/>
edd505634357 Documented the "sticky" directive. Vladimir Homutov <vl@nginx.com> parents: 981 diff changeset	1002 <context>upstream</context>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1003 <appeared-in>1.5.7</appeared-in>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1004
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1005 <para>
962 f3754c623e6b Minor editing of the stiky_cookie_insert directive. Egor Nikitin <yegor.nikitin@gmail.com> parents: 960 diff changeset	1006 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	1007 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	1008 Three methods are available:
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1009 <list type="tag">
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1010 <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	1011 <tag-desc>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1012
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1013 <para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1014 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	1015 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	1016 <example>
960 48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	1017 upstream backend {
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	1018 server backend1.example.com;
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	1019 server backend2.example.com;
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	1020
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1021 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	1022 }
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1023 </example>
960 48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	1024 </para>
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	1025
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	1026 <para>
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	1027 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	1028 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	1029 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	1030 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	1031 selected as if the client has not been bound yet.
2809 e642fe346261 Added note about requests distribution to sticky cookie. Yaroslav Zhuravlev <yar@nginx.com> parents: 2706 diff changeset	1032
e642fe346261 Added note about requests distribution to sticky cookie. Yaroslav Zhuravlev <yar@nginx.com> parents: 2706 diff changeset	1033 <note>
e642fe346261 Added note about requests distribution to sticky cookie. Yaroslav Zhuravlev <yar@nginx.com> parents: 2706 diff changeset	1034 As a load balancing method always tries to evenly distribute the load
e642fe346261 Added note about requests distribution to sticky cookie. Yaroslav Zhuravlev <yar@nginx.com> parents: 2706 diff changeset	1035 considering already bound requests,
e642fe346261 Added note about requests distribution to sticky cookie. Yaroslav Zhuravlev <yar@nginx.com> parents: 2706 diff changeset	1036 the server with a higher number of active bound requests
e642fe346261 Added note about requests distribution to sticky cookie. Yaroslav Zhuravlev <yar@nginx.com> parents: 2706 diff changeset	1037 has less possibility of getting new unbound requests.
e642fe346261 Added note about requests distribution to sticky cookie. Yaroslav Zhuravlev <yar@nginx.com> parents: 2706 diff changeset	1038 </note>
960 48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	1039 </para>
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	1040
48ab154edf10 Upstream: removed obsoleted directives in the "sticky" module. Vladimir Homutov <vl@nginx.com> parents: 956 diff changeset	1041 <para>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1042 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	1043 The cookie value is
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	1044 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	1045 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	1046 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	1047 <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	1048 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	1049 <example>
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	1050 upstream backend {
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	1051 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	1052 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	1053
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	1054 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	1055 }
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	1056 </example>
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	1057 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	1058 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	1059 </para>
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	1060
29b68a7b42fc Documented cookie name for sticky cookie and server route. Yaroslav Zhuravlev <yar@nginx.com> parents: 2028 diff changeset	1061 <para>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1062 Additional parameters may be as follows:
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1063 <list type="tag">
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1064
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1065 <tag-name><literal>expires=</literal><value>time</value></tag-name>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1066 <tag-desc>
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1067 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	1068 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	1069 “<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	1070 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	1071 the end of a browser session.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1072 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1073
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1074 <tag-name><literal>domain=</literal><value>domain</value></tag-name>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1075 <tag-desc>
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1076 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	1077 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	1078 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1079
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1080 <tag-name><literal>httponly</literal></tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1081 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1082 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	1083 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1084
2632 52500ccb82c1 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2610 diff changeset	1085 <tag-name id="sticky_samesite"><literal>samesite=</literal><literal>strict</literal> \|
2914 3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	1086 <literal>lax</literal> \| <literal>none</literal> \| <value>$variable</value></tag-name>
2632 52500ccb82c1 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2610 diff changeset	1087 <tag-desc>
2914 3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	1088 Adds the <literal>SameSite</literal> (1.19.4) attribute to the cookie
3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	1089 with one of the following values:
3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	1090 <literal>Strict</literal>,
3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	1091 <literal>Lax</literal>,
3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	1092 <literal>None</literal>, or
3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	1093 using variables (1.23.3).
3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	1094 In the latter case, if the variable value is empty,
3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	1095 the <literal>SameSite</literal> attribute will not be added to the cookie,
3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	1096 if the value is resolved to
2632 52500ccb82c1 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2610 diff changeset	1097 <literal>Strict</literal>,
52500ccb82c1 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2610 diff changeset	1098 <literal>Lax</literal>, or
2914 3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	1099 <literal>None</literal>,
2917 a2708cf6ebdb Fixed typo in the sticky directive. Sergey A. Osokin <osa@FreeBSD.org.ru> parents: 2914 diff changeset	1100 the corresponding value will be assigned,
2914 3a2d342533fb Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2831 diff changeset	1101 otherwise the <literal>Strict</literal> value will be assigned.
2632 52500ccb82c1 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2610 diff changeset	1102 </tag-desc>
52500ccb82c1 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2610 diff changeset	1103
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1104 <tag-name><literal>secure</literal></tag-name>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1105 <tag-desc>
1450 f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1106 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	1107 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1108
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1109 <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	1110 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release. Ruslan Ermilov <ru@nginx.com> parents: 1424 diff changeset	1111 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	1112 </tag-desc>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1113
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1114 </list>
981 fc35441b4856 Fixed grammar. Vladimir Homutov <vl@nginx.com> parents: 969 diff changeset	1115 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	1116 </para>
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1117 </tag-desc>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1118
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1119 <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	1120 <tag-desc>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1121
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1122 <para>
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1123 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	1124 client a route on receipt of the first request.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1125 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	1126 in a cookie or URI.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1127 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	1128 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	1129 request should be proxied.
1854 dca985318cfe Documented default value for server route in sticky route. Yaroslav Zhuravlev <yar@nginx.com> parents: 1825 diff changeset	1130 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	1131 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	1132 or of the UNIX-domain socket path.
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1133 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	1134 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	1135 information in the request.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1136 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1137
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1138 <para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1139 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	1140 may contain routing information.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1141 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	1142 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1143
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1144 <para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1145 Example:
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1146 <example>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1147 map $cookie_jsessionid $route_cookie {
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1148 ~.+\.(?P<route>\w+)$ $route;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1149 }
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1150
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1151 map $request_uri $route_uri {
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1152 ~jsessionid=.+\.(?P<route>\w+)$ $route;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1153 }
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1154
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1155 upstream backend {
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1156 server backend1.example.com route=a;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1157 server backend2.example.com route=b;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1158
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1159 sticky route $route_cookie $route_uri;
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1160 }
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1161 </example>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1162 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	1163 if present in a request.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1164 Otherwise, the route from the URI is used.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1165 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1166
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1167 </tag-desc>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1168
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1169 <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	1170 <tag-desc>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1171 <para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1172 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	1173 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	1174 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	1175 <example>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1176 upstream backend {
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1177 server backend1.example.com:8080;
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1178 server backend2.example.com:8081;
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1179
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1180 sticky learn
1544 627a9309011c Renamed cookie in the example of the sticky directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1543 diff changeset	1181 create=$upstream_cookie_examplecookie
627a9309011c Renamed cookie in the example of the sticky directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1543 diff changeset	1182 lookup=$cookie_examplecookie
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1183 zone=client_sessions:1m;
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1184 }
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1185 </example>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1186
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1187 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	1188 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	1189 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	1190 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	1191 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	1192 </para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1193
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1194 <para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1195 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	1196 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	1197 sessions are searched, respectively.
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1198 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	1199 non-empty variable is used.
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1200 </para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1201
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1202 <para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1203 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	1204 <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	1205 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	1206 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	1207 <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	1208 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	1209 </para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1210
2028 5c55b7054b58 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1945 diff changeset	1211 <para id="sticky_learn_header">
5c55b7054b58 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1945 diff changeset	1212 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	1213 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	1214 </para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 1945 diff changeset	1215
2139 f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1216 <para id="sticky_learn_sync">
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1217 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	1218 <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	1219 of the shared memory zone.
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1220 </para>
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1221
1259 954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1222 </tag-desc>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1223 </list>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1224 </para>
954dcc02cb63 Upstream: "session learn" sticky method and upstream_conf changes. Ruslan Ermilov <ru@nginx.com> parents: 1241 diff changeset	1225
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1226 <para>
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1227 <note>
1128 1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	1228 This directive is available as part of our
1594ed379f1f De-i18n'ed <commercial_version/>. Ruslan Ermilov <ru@nginx.com> parents: 1127 diff changeset	1229 <commercial_version>commercial subscription</commercial_version>.
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1230 </note>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1231 </para>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1232
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1233 </directive>
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1234
aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 942 diff changeset	1235
1026 3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1236 <directive name="sticky_cookie_insert">
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1237 <syntax><value>name</value>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1238 [<literal>expires=</literal><value>time</value>]
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1239 [<literal>domain=</literal><value>domain</value>]
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1240 [<literal>path=</literal><value>path</value>]</syntax>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1241 <default/>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1242 <context>upstream</context>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1243
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1244 <para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1245 This directive is obsolete since version 1.5.7.
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1246 An equivalent
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1247 <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	1248 <note>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1249 <literal>sticky cookie</literal> <value>name</value>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1250 [<literal>expires=</literal><value>time</value>]
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1251 [<literal>domain=</literal><value>domain</value>]
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1252 [<literal>path=</literal><value>path</value>];
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1253 </note>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1254 </para>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1255
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1256 </directive>
3056640d5022 Upstream: documented new "sticky" features. Ruslan Ermilov <ru@nginx.com> parents: 1011 diff changeset	1257
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1258 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1259
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1260
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1261 <section id="variables" name="Embedded Variables">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1262
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1263 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1264 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	1265 supports the following embedded variables:
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1266 <list type="tag">
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1267
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1268 <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	1269 <tag-desc>
1391 0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1270 keeps the IP address and port,
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1271 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	1272 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	1273 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	1274 “<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	1275 If an internal redirect from one server group to another happens,
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1276 initiated by
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1277 <header>X-Accel-Redirect</header> or
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1278 <link doc="ngx_http_core_module.xml" id="error_page"/>,
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1279 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	1280 “<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	1281 If a server cannot be selected,
eb58ee50561d Documented upstream name in $upstream_addr. Yaroslav Zhuravlev <yar@nginx.com> parents: 2041 diff changeset	1282 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	1283 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1284
1783 031566771bbd Documented $upstream_bytes_received for http upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1722 diff changeset	1285 <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	1286 <tag-desc>
031566771bbd Documented $upstream_bytes_received for http upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1722 diff changeset	1287 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	1288 Values from several connections
031566771bbd Documented $upstream_bytes_received for http upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1722 diff changeset	1289 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	1290 <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	1291 </tag-desc>
031566771bbd Documented $upstream_bytes_received for http upstream. Yaroslav Zhuravlev <yar@nginx.com> parents: 1722 diff changeset	1292
2307 994207cf96da Documented the "$upstream_bytes_sent" variable for http. Yaroslav Zhuravlev <yar@nginx.com> parents: 2282 diff changeset	1293 <tag-name id="var_upstream_bytes_sent"><var>$upstream_bytes_sent</var></tag-name>
994207cf96da Documented the "$upstream_bytes_sent" variable for http. Yaroslav Zhuravlev <yar@nginx.com> parents: 2282 diff changeset	1294 <tag-desc>
994207cf96da Documented the "$upstream_bytes_sent" variable for http. Yaroslav Zhuravlev <yar@nginx.com> parents: 2282 diff changeset	1295 number of bytes sent to an upstream server (1.15.8).
994207cf96da Documented the "$upstream_bytes_sent" variable for http. Yaroslav Zhuravlev <yar@nginx.com> parents: 2282 diff changeset	1296 Values from several connections
994207cf96da Documented the "$upstream_bytes_sent" variable for http. Yaroslav Zhuravlev <yar@nginx.com> parents: 2282 diff changeset	1297 are separated by commas and colons like addresses in the
994207cf96da Documented the "$upstream_bytes_sent" variable for http. Yaroslav Zhuravlev <yar@nginx.com> parents: 2282 diff changeset	1298 <link id="var_upstream_addr">$upstream_addr</link> variable.
994207cf96da Documented the "$upstream_bytes_sent" variable for http. Yaroslav Zhuravlev <yar@nginx.com> parents: 2282 diff changeset	1299 </tag-desc>
994207cf96da Documented the "$upstream_bytes_sent" variable for http. Yaroslav Zhuravlev <yar@nginx.com> parents: 2282 diff changeset	1300
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1301 <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	1302 </tag-name>
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1303 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 962 diff changeset	1304 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	1305 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	1306 “<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	1307 “<literal>STALE</literal>”, “<literal>UPDATING</literal>”,
1391 0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1308 “<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	1309 </tag-desc>
f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1310
1481 f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1311 <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	1312 </tag-name>
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1313 <tag-desc>
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1314 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	1315 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	1316 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	1317 Times of several connections
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1318 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	1319 <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	1320 </tag-desc>
f29398a167d0 Documented the upstream_connect_time variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 1461 diff changeset	1321
1186 8125bec5c7a1 Upstream: documented the $upstream_cookie_* variables. Ruslan Ermilov <ru@nginx.com> parents: 1181 diff changeset	1322 <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	1323 </tag-name>
8125bec5c7a1 Upstream: documented the $upstream_cookie_* variables. Ruslan Ermilov <ru@nginx.com> parents: 1181 diff changeset	1324 <tag-desc>
8125bec5c7a1 Upstream: documented the $upstream_cookie_* variables. Ruslan Ermilov <ru@nginx.com> parents: 1181 diff changeset	1325 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	1326 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	1327 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	1328 </tag-desc>
8125bec5c7a1 Upstream: documented the $upstream_cookie_* variables. Ruslan Ermilov <ru@nginx.com> parents: 1181 diff changeset	1329
1393 15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1330 <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	1331 </tag-name>
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1332 <tag-desc>
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1333 keeps time
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1334 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	1335 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	1336 Times of several responses
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1337 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	1338 <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	1339 </tag-desc>
15e8779f0ceb Documented the $upstream_header_time variable. Ruslan Ermilov <ru@nginx.com> parents: 1392 diff changeset	1340
1392 82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1341 <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	1342 <tag-desc>
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1343 keep server response header fields.
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1344 For example, the <header>Server</header> response header field
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1345 is available through the <var>$upstream_http_server</var> variable.
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1346 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	1347 as for the variables that start with the
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1348 “<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	1349 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	1350 </tag-desc>
82e62822abe8 Sorted upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1391 diff changeset	1351
3029 27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1352 <tag-name id="var_upstream_last_server_name"><var>$upstream_last_server_name</var></tag-name>
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1353 <tag-desc>
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1354 keeps the name of last selected upstream server (1.25.3);
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1355 allows passing it
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1356 <link doc="ngx_http_proxy_module.xml" id="proxy_ssl_server_name">through SNI</link>:
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1357 <example>
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1358 proxy_ssl_server_name on;
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1359 proxy_ssl_name $upstream_last_server_name;
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1360 </example>
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1361
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1362 <para>
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1363 <note>
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1364 This variable is available as part of our
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1365 <commercial_version>commercial subscription</commercial_version>.
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1366 </note>
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1367 </para>
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1368
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1369 </tag-desc>
27008cb3fb27 Updated docs for the upcoming NGINX Plus release. Yaroslav Zhuravlev <yar@nginx.com> parents: 2917 diff changeset	1370
2139 f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1371 <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	1372 <tag-desc>
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1373 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	1374 (1.13.9);
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1375 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	1376 Times of several responses
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1377 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	1378 <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	1379 </tag-desc>
f6e578b1b02d Updated docs for the upcoming NGINX Plus release. Ruslan Ermilov <ru@nginx.com> parents: 2134 diff changeset	1380
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1381 <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	1382 </tag-name>
731 f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1383 <tag-desc>
1391 0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1384 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	1385 the length is kept in bytes.
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1386 Lengths of several responses
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1387 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	1388 <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	1389 </tag-desc>
f62328124e5b Documented $upstream_cache_status and $upstream_response_length variables. Vladimir Homutov <vl@nginx.com> parents: 654 diff changeset	1390
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1391 <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	1392 </tag-name>
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1393 <tag-desc>
1391 0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1394 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	1395 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	1396 Times of several responses
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1397 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	1398 <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	1399 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1400
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	1401 <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	1402 <tag-desc>
1391 0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1403 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	1404 Status codes of several responses
0702cc081c63 Revised descriptions of upstream module variables. Ruslan Ermilov <ru@nginx.com> parents: 1386 diff changeset	1405 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	1406 <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	1407 If a server cannot be selected,
7275c134ec67 Documented "no live upstreams" case for $upstream_status. Yaroslav Zhuravlev <yar@nginx.com> parents: 2058 diff changeset	1408 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	1409 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1410
2113 180269c4a220 Documented the "upstream_trailer_" variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 2097 diff changeset	1411 <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	1412 <tag-desc>
180269c4a220 Documented the "upstream_trailer_" variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 2097 diff changeset	1413 keeps fields from the end of the response
180269c4a220 Documented the "upstream_trailer_" variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 2097 diff changeset	1414 obtained from the upstream server (1.13.10).
180269c4a220 Documented the "upstream_trailer_" variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 2097 diff changeset	1415 </tag-desc>
180269c4a220 Documented the "upstream_trailer_" variable. Yaroslav Zhuravlev <yar@nginx.com> parents: 2097 diff changeset	1416
293 34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1417 </list>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1418 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1419
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1420 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1421
34246e706f48 English translation of the ngx_http_upstream_module documentation. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1422 </module>

Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_upstream_module.xml @ 3029:27008cb3fb27