Mercurial > hg > nginx-site

annotate xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1697:147e3d0339e8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Reduced syntax clutter in the error_log directive. The description text explains special values like "stderr", "syslog:...", and "memory:...". It is believed that syntax without explicitly listing these variants is more readable.
author Maxim Dounin <mdounin@mdounin.ru>
date Tue, 10 May 2016 15:19:47 +0300
parents 57c3f36b3b6a
children 1dbef8ab47c7
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
2
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
3 <!--
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
4 Copyright (C) Nginx, Inc.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
5 -->
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
6
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
8
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
9 <module name="Module ngx_stream_upstream_module"
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
10 link="/en/docs/stream/ngx_stream_upstream_module.html"
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
11 lang="en"
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
12 rev="11">
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
13
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
14 <section id="summary">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
15
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16 <para>
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
17 The <literal>ngx_stream_upstream_module</literal> module (1.9.0)
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
18 is used to define groups of servers that can be referenced
1405
4569719f4247 Split stream module into stream_core and stream_proxy modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1367
diff changeset
19 by the <link doc="ngx_stream_proxy_module.xml" id="proxy_pass"/>
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
20 directive.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
21 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
22
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
23 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
24
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
25
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
26 <section id="example" name="Example Configuration">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
27
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
28 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
29 <example>
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
30 upstream <emphasis>backend</emphasis> {
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
31 hash $remote_addr consistent;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
32
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
33 server backend1.example.com:12345 weight=5;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
34 server backend2.example.com:12345;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
35 server unix:/tmp/backend3;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
36
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
37 server backup1.example.com:12345 backup;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
38 server backup2.example.com:12345 backup;
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
39 }
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
40
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
41 server {
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
42 listen 12346;
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
43 proxy_pass <emphasis>backend</emphasis>;
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
44 }
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
45 </example>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
46 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
47
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
48 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
49 Dynamically configurable group,
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
50 available as part of our
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
51 <commercial_version>commercial subscription</commercial_version>:
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
52 <example>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
53 resolver 10.0.0.1;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
54
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
55 upstream <emphasis>dynamic</emphasis> {
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
56 zone upstream_dynamic 64k;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
57
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
58 server backend1.example.com:12345 weight=5;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
59 server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
60 server 192.0.2.1:12345 max_fails=3;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
61 server backend3.example.com:12345 resolve;
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
62 server backend4.example.com service=http resolve;
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
63
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
64 server backup1.example.com:12345 backup;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
65 server backup2.example.com:12345 backup;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
66 }
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
67
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
68 server {
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
69 listen 12346;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
70 proxy_pass <emphasis>dynamic</emphasis>;
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
71 health_check;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
72 }
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
73 </example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
74 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
75
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
76 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
77
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
78
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
79 <section id="directives" name="Directives">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
80
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
81 <directive name="upstream">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
82 <syntax block="yes"><value>name</value></syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
83 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
84 <context>stream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
85
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
86 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
87 Defines a group of servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
88 Servers can listen on different ports.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
89 In addition, servers listening on TCP and UNIX-domain sockets
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
90 can be mixed.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
91 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
92
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
93 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
94 Example:
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
95 <example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
96 upstream backend {
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
97 server backend1.example.com:12345 weight=5;
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
98 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s;
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
99 server unix:/tmp/backend2;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
100 server backend3.example.com:12345 resolve;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
101
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
102 server backup1.example.com:12345 backup;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
103 }
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
104 </example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
105 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
106
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
107 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
108 By default, connections are distributed between the servers using a
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
109 weighted round-robin balancing method.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
110 In the above example, each 7 connections will be distributed as follows:
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
111 5 connections go to <literal>backend1.example.com:12345</literal>
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
112 and one connection to each of the second and third servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
113 If an error occurs during communication with a server, the connection will
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
114 be passed to the next server, and so on until all of the functioning
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
115 servers will be tried.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
116 If communication with all servers fails, the connection will be closed.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
117 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
118
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
119 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
120
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
121
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
122 <directive name="server">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
123 <syntax><value>address</value> [<value>parameters</value>]</syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
124 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
125 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
126
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
127 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
128 Defines the <value>address</value> and other <value>parameters</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
129 of a server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
130 The address can be specified as a domain name or IP address
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
131 with an obligatory port, or as a UNIX-domain socket path
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
132 specified after the “<literal>unix:</literal>” prefix.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
133 A domain name that resolves to several IP addresses defines
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
134 multiple servers at once.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
135 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
136
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
137 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
138 The following parameters can be defined:
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
139 <list type="tag">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
140
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
141 <tag-name id="weight">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
142 <literal>weight</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
143 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
144 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
145 sets the weight of the server, by default, 1.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
146 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
147
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
148 <tag-name id="max_fails">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
149 <literal>max_fails</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
150 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
151 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
152 sets the number of unsuccessful attempts to communicate with the server
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
153 that should happen in the duration set by the <literal>fail_timeout</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
154 parameter to consider the server unavailable for a duration also set by the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
155 <literal>fail_timeout</literal> parameter.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
156 By default, the number of unsuccessful attempts is set to 1.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
157 The zero value disables the accounting of attempts.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
158 Here, an unsuccessful attempt is an error or timeout
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
159 while establishing a connection with the server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
160 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
161
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
162 <tag-name id="fail_timeout">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
163 <literal>fail_timeout</literal>=<value>time</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
164 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
165 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
166 sets
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
167 <list type="bullet">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
168
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
169 <listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
170 the time during which the specified number of unsuccessful attempts to
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
171 communicate with the server should happen to consider the server unavailable;
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
172 </listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
173
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
174 <listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
175 and the period of time the server will be considered unavailable.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
176 </listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
177
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
178 </list>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
179 By default, the parameter is set to 10 seconds.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
180 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
181
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
182 <tag-name id="backup">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
183 <literal>backup</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
184 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
185 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
186 marks the server as a backup server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
187 Connections to the backup server will be passed
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
188 when the primary servers are unavailable.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
189 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
190
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
191 <tag-name id="down">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
192 <literal>down</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
193 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
194 <tag-desc>
1410
f5dcc23b214f Deleted info about hash and ip_hash from the down parameter.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1406
diff changeset
195 marks the server as permanently unavailable.
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
196 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
197
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
198 </list>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
199 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
200
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
201 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
202 Additionally,
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
203 the following parameters are available as part of our
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
204 <commercial_version>commercial subscription</commercial_version>:
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
205 <list type="tag">
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
206
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
207 <tag-name id="max_conns">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
208 <literal>max_conns</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
209 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
210 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
211 limits the maximum <value>number</value> of simultaneous connections to the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
212 proxied server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
213 Default value is zero, meaning there is no limit.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
214 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
215
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
216 <tag-name id="resolve">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
217 <literal>resolve</literal>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
218 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
219 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
220 monitors changes of the IP addresses
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
221 that correspond to a domain name of the server,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
222 and automatically modifies the upstream configuration
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
223 without the need of restarting nginx.
1581
201bf8fa69e5 Added shared memory requirement to resolver in http and stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1495
diff changeset
224 The server group must reside in the <link id="zone">shared memory</link>.
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
225 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
226 In order for this parameter to work,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
227 the <link doc="ngx_stream_core_module.xml" id="resolver"/> directive
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
228 must be specified in the
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
229 <link doc="ngx_stream_core_module.xml" id="stream"/> block.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
230 Example:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
231 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
232 stream {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
233 resolver 10.0.0.1;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
234
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
235 upstream u {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
236 zone ...;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
237 ...
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
238 server example.com:12345 resolve;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
239 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
240 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
241 </example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
242 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
243 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
244
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
245 <tag-name id="service">
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
246 <literal>service</literal>=<value>name</value> | <value>_name._protocol</value>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
247 </tag-name>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
248 <tag-desc>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
249 enables resolving of DNS
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
250 <link url="https://tools.ietf.org/html/rfc2782">SRV</link>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
251 records and sets the service <value>name</value>,
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
252 or <value>name</value> and <value>protocol</value> in the following format:
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
253 <value>_name._protocol</value> (1.9.13).
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
254 If only the <value>name</value> is specified,
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
255 the <literal>TCP</literal> protocol is used.
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
256 <para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
257 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: 1654
diff changeset
258 the <link id="resolve"/> parameter for the server
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
259 and specify a hostname without a port number:
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
260 <example>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
261 server backend.example.com service=http resolve;
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
262 server backend.example.com service=_http._tcp resolve;
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
263 </example>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
264 Both directives specify the same SRV record:
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
265 <literal>_http._tcp.backend.example.com</literal>.
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
266 </para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
267
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
268 <para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
269 Highest-priority SRV records
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
270 (records with the same lowest-number priority value)
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
271 are resolved as primary servers,
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
272 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: 1654
diff changeset
273 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: 1654
diff changeset
274 high-priority SRV records are resolved as backup servers,
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
275 the rest of SRV records are ignored.
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
276 </para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
277 </tag-desc>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
278
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
279 <tag-name id="slow_start">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
280 <literal>slow_start</literal>=<value>time</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
281 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
282 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
283 sets the <value>time</value> during which the server will recover its weight
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
284 from zero to a nominal value,
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
285 or when the server becomes available after a period of time
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
286 it was considered <link id="fail_timeout">unavailable</link>.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
287 Default value is zero, i.e. slow start is disabled.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
288 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
289
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
290 </list>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
291 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
292
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
293 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
294 <note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
295 If there is only a single server in a group, <literal>max_fails</literal>,
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
296 <literal>fail_timeout</literal> and <literal>slow_start</literal> parameters
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
297 are ignored, and such a server will never be considered unavailable.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
298 </note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
299 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
300
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
301 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
302
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
303
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
304 <directive name="zone">
1495
8d134b482cc3 Documented zone usage with many upstreams.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1462
diff changeset
305 <syntax><value>name</value> [<value>size</value>]</syntax>
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
306 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
307 <context>upstream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
308
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
309 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
310 Defines the <value>name</value> and <value>size</value> of the shared
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
311 memory zone that keeps the group’s configuration and run-time state that are
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
312 shared between worker processes.
1495
8d134b482cc3 Documented zone usage with many upstreams.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1462
diff changeset
313 Several groups may share the same zone.
8d134b482cc3 Documented zone usage with many upstreams.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1462
diff changeset
314 In this case, it is enough to specify the zone size only once.
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
315 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
316
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
317 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
318 Additionally,
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
319 as part of our <commercial_version>commercial subscription</commercial_version>,
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
320 such groups allow changing the group membership
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
321 or modifying the settings of a particular server
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
322 without the need of restarting nginx.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
323 The configuration is accessible via a special location
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
324 handled by
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
325 <link doc="../http/ngx_http_upstream_conf_module.xml" id="upstream_conf"/>.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
326 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
327
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
328 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
329
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
330
1636
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
331 <directive name="state">
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
332 <syntax><value>file</value></syntax>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
333 <default/>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
334 <context>upstream</context>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
335 <appeared-in>1.9.7</appeared-in>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
336
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
337 <para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
338 Specifies a <value>file</value> that keeps the state
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
339 of the dynamically configurable group.
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
340 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: 1581
diff changeset
341 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: 1581
diff changeset
342 the upstream configuration is
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
343 <link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf">changed</link>.
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
344 Changing the file content directly should be avoided.
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
345 The directive cannot be used
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
346 along with the <link id="server"/> directive.
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
347 </para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
348
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
349 <para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
350 <note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
351 Changes made during
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
352 <link doc="../control.xml" id="reconfiguration">configuration reload</link>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
353 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: 1581
diff changeset
354 can be lost.
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
355 </note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
356 </para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
357
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
358 <para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
359 <note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
360 This directive is available as part of our
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
361 <commercial_version>commercial subscription</commercial_version>.
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
362 </note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
363 </para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
364
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
365 </directive>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
366
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
367
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
368 <directive name="hash">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
369 <syntax><value>key</value> [<literal>consistent</literal>]</syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
370 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
371 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
372
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
373 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
374 Specifies a load balancing method for a server group
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
375 where client-server mapping is based on the hashed <value>key</value> value.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
376 Currently, the only supported value for the <literal>key</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
377 is the client remote address specified as <literal>$remote_addr</literal>.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
378 Note that adding or removing a server from the group
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
379 may result in remapping most of the keys to different servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
380 The method is compatible with the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
381 <link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached">Cache::Memcached</link>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
382 Perl library.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
383 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
384
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
385 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
386 If the <literal>consistent</literal> parameter is specified,
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
387 the <link url="http://www.last.fm/user/RJ/journal/2007/04/10/392555/">ketama</link>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
388 consistent hashing method will be used instead.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
389 The method ensures that only a few keys
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
390 will be remapped to different servers
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
391 when a server is added to or removed from the group.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
392 This helps to achieve a higher cache hit ratio for caching servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
393 The method is compatible with the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
394 <link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached%3A%3AFast">Cache::Memcached::Fast</link>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
395 Perl library with the <value>ketama_points</value> parameter set to 160.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
396 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
397
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
398 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
399
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
400
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
401 <directive name="least_conn">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
402 <syntax/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
403 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
404 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
405
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
406 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
407 Specifies that a server group should use a load balancing method
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
408 where a connection
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
409 is passed to the server with the least number of active connections,
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
410 taking into account weights of servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
411 If there are several such servers, they are tried in turn using a
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
412 weighted round-robin balancing method.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
413 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
414
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
415 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
416
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
417
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
418 <directive name="least_time">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
419 <syntax><literal>connect</literal> |
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
420 <literal>first_byte</literal> |
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
421 <literal>last_byte</literal></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
422 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
423 <context>upstream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
424
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
425 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
426 Specifies that a group should use a load balancing method where a connection
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
427 is passed to the server with the least average time and
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
428 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: 1410
diff changeset
429 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: 1410
diff changeset
430 weighted round-robin balancing method.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
431 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
432
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
433 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
434 If the <literal>connect</literal> parameter is specified,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
435 time to connect to the upstream server is used.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
436 If the <literal>first_byte</literal> parameter is specified,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
437 time to receive the first byte of data is used.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
438 If the <literal>last_byte</literal> is specified,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
439 time to receive the last byte of data is used.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
440 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
441
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
442 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
443 <note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
444 This directive is available as part of our
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
445 <commercial_version>commercial subscription</commercial_version>.
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
446 </note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
447 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
448
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
449 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
451
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
452 <directive name="health_check">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
453 <syntax>[<value>parameters</value>]</syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
454 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
455 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
456
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
457 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
458 Enables periodic health checks of the servers in a
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
459 <link id="upstream">group</link>.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
460 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
461
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
462 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
463 The following optional parameters are supported:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
464 <list type="tag">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
465
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
466 <tag-name id="interval">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
467 <literal>interval</literal>=<value>time</value>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
468 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
469 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
470 sets the interval between two consecutive health checks,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
471 by default, 5 seconds;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
472 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
473
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
474 <tag-name id="fails">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
475 <literal>fails</literal>=<value>number</value>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
476 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
477 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
478 sets the number of consecutive failed health checks of a particular server
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
479 after which this server will be considered unhealthy,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
480 by default, 1;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
481 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
482
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
483 <tag-name id="passes">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
484 <literal>passes</literal>=<value>number</value>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
485 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
486 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
487 sets the number of consecutive passed health checks of a particular server
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
488 after which the server will be considered healthy,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
489 by default, 1;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
490 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
491
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
492 <tag-name id="hc_match">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
493 <literal>match</literal>=<value>name</value>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
494 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
495 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
496 specifies the <literal>match</literal> block configuring the tests that a
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
497 successful connection should pass in order for a health check to pass.
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
498 By default,
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
499 only the ability to establish a TCP connection with the server is checked;
1636
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
500 </tag-desc>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
501
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
502 <tag-name id="health_check_port">
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
503 <literal>port</literal>=<value>number</value>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
504 </tag-name>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
505 <tag-desc>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
506 defines the port used when connecting to a server
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
507 to perform a health check (1.9.7);
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
508 by default, equals the <link id="server"/> port;
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
509 </tag-desc>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
510
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
511 <tag-name id="health_check_udp">
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
512 <literal>udp</literal>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
513 </tag-name>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
514 <tag-desc>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
515 specifies that the <literal>UDP</literal> protocol should be used for
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
516 health checks instead of the default <literal>TCP</literal> protocol (1.9.13);
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
517 requires a <link id="hc_match">match</link> block with the
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
518 <link id="match_send">send</link> and <link id="match_expect">expect</link>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
519 parameters.
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
520 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
521
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
522 </list>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
523 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
524
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
525 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
526 For example,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
527 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
528 server {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
529 proxy_pass backend;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
530 health_check;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
531 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
532 </example>
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
533 will check the ability to establish a TCP connection to each server
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
534 in the <literal>backend</literal> group every five seconds.
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
535 When a connection to the server cannot be established,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
536 the health check will fail, and the server will
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
537 be considered unhealthy.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
538 Client connections are not passed to unhealthy servers.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
539 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
540
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
541 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
542 Health checks can also be configured to test data obtained from the server.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
543 Tests are configured separately using the <link id="match"/> directive
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
544 and referenced in the <literal>match</literal> parameter.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
545 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
546
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
547 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
548 The server group must reside in the <link id="zone">shared memory</link>.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
549 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
550
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
551 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
552 If several health checks are defined for the same group of servers,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
553 a single failure of any check will make the corresponding server be
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
554 considered unhealthy.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
555 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
556
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
557 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
558 <note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
559 This directive is available as part of our
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
560 <commercial_version>commercial subscription</commercial_version>.
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
561 </note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
562 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
563
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
564 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
565
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
566
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
567 <directive name="health_check_timeout">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
568 <syntax><value>timeout</value></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
569 <default>5s</default>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
570 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
571 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
572
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
573 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
574 Overrides the
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
575 <link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
576 value for health checks.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
577 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
578
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
579 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
580 <note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
581 This directive is available as part of our
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
582 <commercial_version>commercial subscription</commercial_version>.
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
583 </note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
584 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
585
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
586 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
587
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
588
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
589 <directive name="match">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
590 <syntax block="yes"><value>name</value> </syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
591 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
592 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
593
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
594 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
595 Defines the named test set used to verify server responses to health checks.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
596 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
597
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
598 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
599 The following parameters can be configured:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
600 <list type="tag">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
601
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
602 <tag-name id="match_send">
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
603 <literal>send</literal> <value>string</value>;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
604 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
605 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
606 sends a <value>string</value> to the server;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
607 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
608
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
609 <tag-name id="match_expect">
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
610 <literal>expect</literal> <value>string</value> |
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
611 <literal>~</literal> <value>regex</value>;
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
612 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
613 <tag-desc>
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
614 a literal string (1.9.12) or a regular expression
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
615 that the data obtained from the server should match.
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
616 The regular expression is specified with the preceding
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
617 “<literal>~*</literal>” modifier (for case-insensitive matching), or the
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
618 “<literal>~</literal>” modifier (for case-sensitive matching).
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
619 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
620
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
621 </list>
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
622 Both <literal>send</literal> and <literal>expect</literal> parameters
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
623 can contain hexadecimal literals with the prefix “<literal>\x</literal>”
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
624 followed by two hex digits, for example, “<literal>\x80</literal>” (1.9.12).
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
625 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
626
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
627 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
628 Health check is passed if:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
629 <list type="bullet">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
630 <listitem>
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
631 the TCP connection was successfully established;
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
632 </listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
633
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
634 <listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
635 the <value>string</value> from the <literal>send</literal> parameter,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
636 if specified, was sent;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
637 </listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
638
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
639 <listitem>
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
640 the data obtained from the server matched the string or regular expression
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
641 from the <literal>expect</literal> parameter, if specified;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
642 </listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
643
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
644 <listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
645 the time elapsed does not exceed the value specified
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
646 in the <link id="health_check_timeout"/> directive.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
647 </listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
648
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
649 </list>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
650 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
651
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
652 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
653 Example:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
654 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
655 upstream backend {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
656 zone upstream_backend 10m;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
657 server 127.0.0.1:12345;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
658 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
659
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
660 match http {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
661 send "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n";
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
662 expect ~ "200 OK";
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
663 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
664
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
665 server {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
666 listen 12346;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
667 proxy_pass backend;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
668 health_check match=http;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
669 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
670 </example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
671 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
672
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
673 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
674 <note>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
675 Only the first
1654
f5dcf57c5eb5 Corrected note in the stream "match" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1636
diff changeset
676 <link doc="ngx_stream_proxy_module.xml" id="proxy_buffer_size"/>
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
677 bytes of data obtained from the server are examined.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
678 </note>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
679 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
680
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
681 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
682 <note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
683 This directive is available as part of our
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
684 <commercial_version>commercial subscription</commercial_version>.
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
685 </note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
686 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
687
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
688 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
689
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
690 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
691
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
692 </module>