Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_upstream_module.xml @ 2275:d93c8c32df75

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