Mercurial > hg > nginx-site

annotate xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1878:127ae107e5a9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Removed clause about shared memory and Windows versions with ASLR. Starting with nginx 1.9.0 shared memory can be used on Windows versions with address space layout randomization.
author Maxim Dounin <mdounin@mdounin.ru>
date Mon, 26 Dec 2016 19:38:06 +0300
parents 6f2c5a36b4d1
children 6225d50b3cba
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"
1866
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1817
diff changeset
12 rev="22">
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
1800
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
148 <tag-name id="max_conns">
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
149 <literal>max_conns</literal>=<value>number</value>
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
150 </tag-name>
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
151 <tag-desc>
1801
592f9fa804f6 Added info about shared memory to max_conns.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1800
diff changeset
152 limits the maximum <value>number</value> of simultaneous
592f9fa804f6 Added info about shared memory to max_conns.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1800
diff changeset
153 connections to the proxied server (1.11.5).
1800
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
154 Default value is zero, meaning there is no limit.
1801
592f9fa804f6 Added info about shared memory to max_conns.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1800
diff changeset
155 If the server group does not reside in the <link id="zone">shared memory</link>,
592f9fa804f6 Added info about shared memory to max_conns.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1800
diff changeset
156 the limitation works per each worker process.
1800
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
157 <note>
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
158 Prior to version 1.11.5, this parameter was available as part of our
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
159 <commercial_version>commercial subscription</commercial_version>.
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
160 </note>
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
161 </tag-desc>
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
162
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
163 <tag-name id="max_fails">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
164 <literal>max_fails</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
165 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
166 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
167 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
168 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
169 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
170 <literal>fail_timeout</literal> parameter.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
171 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
172 The zero value disables the accounting of attempts.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
173 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
174 while establishing a connection with the server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
175 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
176
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
177 <tag-name id="fail_timeout">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
178 <literal>fail_timeout</literal>=<value>time</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
179 </tag-name>
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 sets
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
182 <list type="bullet">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
183
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
184 <listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
185 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
186 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
187 </listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
188
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
189 <listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
190 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
191 </listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
192
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
193 </list>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
194 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
195 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
196
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
197 <tag-name id="backup">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
198 <literal>backup</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
199 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
200 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
201 marks the server as a backup server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
202 Connections to the backup server will be passed
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
203 when the primary servers are unavailable.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
204 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
205
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
206 <tag-name id="down">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
207 <literal>down</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
208 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
209 <tag-desc>
1410
f5dcc23b214f Deleted info about hash and ip_hash from the down parameter.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1406
diff changeset
210 marks the server as permanently unavailable.
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
211 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
212
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
213 </list>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
214 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
215
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
216 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
217 Additionally,
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
218 the following parameters are available as part of our
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
219 <commercial_version>commercial subscription</commercial_version>:
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
220 <list type="tag">
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
221
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
222 <tag-name id="resolve">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
223 <literal>resolve</literal>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
224 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
225 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
226 monitors changes of the IP addresses
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
227 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
228 and automatically modifies the upstream configuration
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
229 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
230 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
231 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
232 In order for this parameter to work,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
233 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
234 must be specified in the
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
235 <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
236 Example:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
237 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
238 stream {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
239 resolver 10.0.0.1;
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 upstream u {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
242 zone ...;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
243 ...
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
244 server example.com:12345 resolve;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
245 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
246 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
247 </example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
248 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
249 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
250
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
251 <tag-name id="service">
1700
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
252 <literal>service</literal>=<value>name</value>
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
253 </tag-name>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
254 <tag-desc>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
255 enables resolving of DNS
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
256 <link url="https://tools.ietf.org/html/rfc2782">SRV</link>
1700
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
257 records and sets the service <value>name</value> (1.9.13).
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
258 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
259 the <link id="resolve"/> parameter for the server
1700
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
260 and specify a hostname without a port number.
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
261 <para>
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
262 If the service name does not contain a dot (“<literal>.</literal>”), then
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
263 the <link url="https://tools.ietf.org/html/rfc2782">RFC</link>-compliant name
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
264 is constructed
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
265 and the TCP protocol is added to the service prefix.
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
266 For example, to look up the
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
267 <literal>_http._tcp.backend.example.com</literal> SRV record,
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
268 it is necessary to specify the directive:
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
269 <example>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
270 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
271 </example>
1700
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
272 If the service name contains one or more dots, then the name is constructed
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
273 by joining the service prefix and the server name.
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
274 For example, to look up the <literal>_http._tcp.backend.example.com</literal>
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
275 and <literal>server1.backend.example.com</literal> SRV records,
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
276 it is necessary to specify the directives:
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
277 <example>
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
278 server backend.example.com service=_http._tcp resolve;
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
279 server example.com service=server1.backend resolve;
1dbef8ab47c7 Updated description of service parameter in upstream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1680
diff changeset
280 </example>
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
281 </para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
282
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
283 <para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
284 Highest-priority SRV records
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
285 (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
286 are resolved as primary servers,
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
287 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
288 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
289 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
290 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
291 </para>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
292 </tag-desc>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
293
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
294 <tag-name id="slow_start">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
295 <literal>slow_start</literal>=<value>time</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
296 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
297 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
298 sets the <value>time</value> during which the server will recover its weight
1727
1a16dce51bce Unified description of slow_start in stream with http.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1700
diff changeset
299 from zero to a nominal value, when unhealthy server becomes
1a16dce51bce Unified description of slow_start in stream with http.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1700
diff changeset
300 <link id="health_check">healthy</link>,
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
301 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
302 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
303 Default value is zero, i.e. slow start is disabled.
1817
0160e8784417 Documented behavior of server slow_start with ip_hash and hash.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1809
diff changeset
304 <note>
0160e8784417 Documented behavior of server slow_start with ip_hash and hash.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1809
diff changeset
305 The parameter cannot be used along with the
0160e8784417 Documented behavior of server slow_start with ip_hash and hash.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1809
diff changeset
306 <link id="hash"/> load balancing method.
0160e8784417 Documented behavior of server slow_start with ip_hash and hash.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1809
diff changeset
307 </note>
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
308 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
309
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
310 </list>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
311 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
312
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
313 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
314 <note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
315 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
316 <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
317 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
318 </note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
319 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
320
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
321 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
322
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
323
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
324 <directive name="zone">
1495
8d134b482cc3 Documented zone usage with many upstreams.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1462
diff changeset
325 <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
326 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
327 <context>upstream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
328
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
329 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
330 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
331 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
332 shared between worker processes.
1495
8d134b482cc3 Documented zone usage with many upstreams.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1462
diff changeset
333 Several groups may share the same zone.
8d134b482cc3 Documented zone usage with many upstreams.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1462
diff changeset
334 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
335 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
336
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
337 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
338 Additionally,
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
339 as part of our <commercial_version>commercial subscription</commercial_version>,
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
340 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
341 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
342 without the need of restarting nginx.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
343 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
344 handled by
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
345 <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
346 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
347
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
348 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
349
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
350
1636
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
351 <directive name="state">
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
352 <syntax><value>file</value></syntax>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
353 <default/>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
354 <context>upstream</context>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
355 <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
356
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
357 <para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
358 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
359 of the dynamically configurable group.
1809
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1801
diff changeset
360 </para>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1801
diff changeset
361
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1801
diff changeset
362 <para>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1801
diff changeset
363 Examples:
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1801
diff changeset
364 <example>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1801
diff changeset
365 state /var/lib/nginx/state/servers.conf; # path for Linux
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1801
diff changeset
366 state /var/db/nginx/state/servers.conf; # path for FreeBSD
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1801
diff changeset
367 </example>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1801
diff changeset
368 </para>
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1801
diff changeset
369
2245f2827e2f Added examples of Linux and FreeBSD paths to "state" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1801
diff changeset
370 <para>
1636
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
371 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
372 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
373 the upstream configuration is
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
374 <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
375 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
376 The directive cannot be used
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
377 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
378 </para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
379
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
380 <para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
381 <note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
382 Changes made during
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
383 <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
384 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
385 can be lost.
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
386 </note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
387 </para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
388
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
389 <para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
390 <note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
391 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
392 <commercial_version>commercial subscription</commercial_version>.
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
393 </note>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
394 </para>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
395
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
396 </directive>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
397
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
398
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
399 <directive name="hash">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
400 <syntax><value>key</value> [<literal>consistent</literal>]</syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
401 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
402 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
403
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
404 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
405 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
406 where client-server mapping is based on the hashed <value>key</value> value.
1744
ab56dcd73af2 Added variables to stream hash, limit_conn_zone, proxy_bind.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1727
diff changeset
407 The <value>key</value> can contain text, variables,
ab56dcd73af2 Added variables to stream hash, limit_conn_zone, proxy_bind.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1727
diff changeset
408 and their combinations (1.11.2).
ab56dcd73af2 Added variables to stream hash, limit_conn_zone, proxy_bind.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1727
diff changeset
409 Usage example:
ab56dcd73af2 Added variables to stream hash, limit_conn_zone, proxy_bind.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1727
diff changeset
410 <example>
ab56dcd73af2 Added variables to stream hash, limit_conn_zone, proxy_bind.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1727
diff changeset
411 hash $remote_addr;
ab56dcd73af2 Added variables to stream hash, limit_conn_zone, proxy_bind.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1727
diff changeset
412 </example>
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
413 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
414 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
415 The method is compatible with the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
416 <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
417 Perl library.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
418 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
419
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
420 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
421 If the <literal>consistent</literal> parameter is specified,
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
422 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
423 consistent hashing method will be used instead.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
424 The method ensures that only a few keys
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
425 will be remapped to different servers
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
426 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
427 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
428 The method is compatible with the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
429 <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
430 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
431 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
432
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
433 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
434
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
435
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
436 <directive name="least_conn">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
437 <syntax/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
438 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
439 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
440
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
441 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
442 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
443 where a connection
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
444 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
445 taking into account weights of servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
446 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
447 weighted round-robin balancing method.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
448 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
449
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
450 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
451
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
452
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
453 <directive name="least_time">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
454 <syntax><literal>connect</literal> |
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
455 <literal>first_byte</literal> |
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
456 <literal>last_byte</literal></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
457 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
458 <context>upstream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
459
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 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
462 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
463 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
464 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
465 weighted round-robin balancing method.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
466 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
467
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
468 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
469 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
470 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
471 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
472 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
473 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
474 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
475 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
476
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
477 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
478 <note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
479 This directive is available as part of our
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
480 <commercial_version>commercial subscription</commercial_version>.
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
481 </note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
482 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
483
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
484 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
485
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
486
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
487 <directive name="health_check">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
488 <syntax>[<value>parameters</value>]</syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
489 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
490 <context>server</context>
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 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
493 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
494 <link id="upstream">group</link>.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
495 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
496
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
497 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
498 The following optional parameters are supported:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
499 <list type="tag">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
500
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
501 <tag-name id="interval">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
502 <literal>interval</literal>=<value>time</value>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
503 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
504 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
505 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
506 by default, 5 seconds;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
507 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
508
1866
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1817
diff changeset
509 <tag-name id="health_check_jitter">
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1817
diff changeset
510 <literal>jitter</literal>=<value>time</value>
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1817
diff changeset
511 </tag-name>
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1817
diff changeset
512 <tag-desc>
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1817
diff changeset
513 sets the time within which
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1817
diff changeset
514 each health check will be randomly delayed,
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1817
diff changeset
515 by default, there is no delay;
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1817
diff changeset
516 </tag-desc>
6f2c5a36b4d1 Documented the "jitter" parameter for health_check.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1817
diff changeset
517
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
518 <tag-name id="fails">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
519 <literal>fails</literal>=<value>number</value>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
520 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
521 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
522 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
523 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
524 by default, 1;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
525 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
526
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
527 <tag-name id="passes">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
528 <literal>passes</literal>=<value>number</value>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
529 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
530 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
531 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
532 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
533 by default, 1;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
534 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
535
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
536 <tag-name id="hc_match">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
537 <literal>match</literal>=<value>name</value>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
538 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
539 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
540 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
541 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
542 By default,
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
543 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
544 </tag-desc>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
545
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
546 <tag-name id="health_check_port">
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
547 <literal>port</literal>=<value>number</value>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
548 </tag-name>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
549 <tag-desc>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
550 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
551 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
552 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
553 </tag-desc>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
554
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
555 <tag-name id="health_check_udp">
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
556 <literal>udp</literal>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
557 </tag-name>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
558 <tag-desc>
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
559 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
560 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
561 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
562 <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
563 parameters.
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
564 </tag-desc>
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 </list>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
567 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
568
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
569 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
570 For example,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
571 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
572 server {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
573 proxy_pass backend;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
574 health_check;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
575 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
576 </example>
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
577 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
578 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
579 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
580 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
581 be considered unhealthy.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
582 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
583 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
584
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
585 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
586 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
587 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
588 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
589 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
590
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
591 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
592 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
593 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
594
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
595 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
596 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
597 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
598 considered unhealthy.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
599 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
600
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
601 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
602 <note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
603 This directive is available as part of our
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
604 <commercial_version>commercial subscription</commercial_version>.
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
605 </note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
606 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
607
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
608 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
609
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
610
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
611 <directive name="health_check_timeout">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
612 <syntax><value>timeout</value></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
613 <default>5s</default>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
614 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
615 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
616
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
617 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
618 Overrides the
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
619 <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
620 value for health checks.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
621 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
622
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
623 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
624 <note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
625 This directive is available as part of our
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
626 <commercial_version>commercial subscription</commercial_version>.
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
627 </note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
628 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
629
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
630 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
631
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
632
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
633 <directive name="match">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
634 <syntax block="yes"><value>name</value> </syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
635 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
636 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
637
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
638 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
639 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
640 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
641
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
642 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
643 The following parameters can be configured:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
644 <list type="tag">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
645
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
646 <tag-name id="match_send">
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
647 <literal>send</literal> <value>string</value>;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
648 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
649 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
650 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
651 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
652
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
653 <tag-name id="match_expect">
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
654 <literal>expect</literal> <value>string</value> |
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
655 <literal>~</literal> <value>regex</value>;
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
656 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
657 <tag-desc>
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
658 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
659 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
660 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
661 “<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
662 “<literal>~</literal>” modifier (for case-sensitive matching).
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
663 </tag-desc>
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 </list>
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
666 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
667 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
668 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
669 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
670
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 Health check is passed if:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
673 <list type="bullet">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
674 <listitem>
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
675 the TCP connection was successfully established;
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
676 </listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
677
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
678 <listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
679 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
680 if specified, was sent;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
681 </listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
682
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
683 <listitem>
1680
57c3f36b3b6a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1654
diff changeset
684 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
685 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
686 </listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
687
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
688 <listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
689 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
690 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
691 </listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
692
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
693 </list>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
694 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
695
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
696 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
697 Example:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
698 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
699 upstream backend {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
700 zone upstream_backend 10m;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
701 server 127.0.0.1:12345;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
702 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
703
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
704 match http {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
705 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
706 expect ~ "200 OK";
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
707 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
708
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
709 server {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
710 listen 12346;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
711 proxy_pass backend;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
712 health_check match=http;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
713 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
714 </example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
715 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
716
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
717 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
718 <note>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
719 Only the first
1654
f5dcf57c5eb5 Corrected note in the stream "match" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1636
diff changeset
720 <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
721 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
722 </note>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
723 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
724
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
725 <para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
726 <note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
727 This directive is available as part of our
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
728 <commercial_version>commercial subscription</commercial_version>.
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
729 </note>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
730 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
731
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
732 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
733
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
734 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
735
1772
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
736
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
737 <section id="variables" name="Embedded Variables">
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
738
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
739 <para>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
740 The <literal>ngx_stream_upstream_module</literal> module
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
741 supports the following embedded variables:
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
742 <list type="tag">
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
743
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
744 <tag-name id="var_upstream_addr"><var>$upstream_addr</var></tag-name>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
745 <tag-desc>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
746 keeps the IP address and port,
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
747 or the path to the UNIX-domain socket of the upstream server (1.11.4).
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
748 If several servers were contacted during proxying,
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
749 their addresses are separated by commas, e.g.
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
750 “<literal>192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock</literal>”.
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
751 </tag-desc>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
752
1773
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
753 <tag-name id="var_upstream_bytes_sent"><var>$upstream_bytes_sent</var></tag-name>
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
754 <tag-desc>
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
755 number of bytes sent to an upstream server (1.11.4).
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
756 Values from several connections
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
757 are separated by commas like addresses in the
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
758 <link id="var_upstream_addr">$upstream_addr</link> variable.
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
759 </tag-desc>
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
760
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
761 <tag-name id="var_upstream_bytes_received"><var>$upstream_bytes_received</var></tag-name>
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
762 <tag-desc>
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
763 number of bytes received from an upstream server (1.11.4).
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
764 Values from several connections
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
765 are separated by commas like addresses in the
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
766 <link id="var_upstream_addr">$upstream_addr</link> variable.
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
767 </tag-desc>
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
768
1774
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
769 <tag-name id="var_upstream_connect_time"><var>$upstream_connect_time</var></tag-name>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
770 <tag-desc>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
771 time to connect to the upstream server (1.11.4);
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
772 the time is kept in seconds with millisecond resolution.
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
773 Times of several connections
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
774 are separated by commas like addresses in the
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
775 <link id="var_upstream_addr">$upstream_addr</link> variable.
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
776 </tag-desc>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
777
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
778 <tag-name id="var_upstream_first_byte_time"><var>$upstream_first_byte_time</var></tag-name>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
779 <tag-desc>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
780 time to receive the first byte of data (1.11.4);
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
781 the time is kept in seconds with millisecond resolution.
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
782 Times of several connections
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
783 are separated by commas like addresses in the
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
784 <link id="var_upstream_addr">$upstream_addr</link> variable.
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
785 </tag-desc>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
786
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
787 <tag-name id="var_upstream_session_time"><var>$upstream_session_time</var></tag-name>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
788 <tag-desc>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
789 session duration in seconds with millisecond resolution (1.11.4).
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
790 Times of several connections
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
791 are separated by commas like addresses in the
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
792 <link id="var_upstream_addr">$upstream_addr</link> variable.
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
793 </tag-desc>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
794
1772
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
795 </list>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
796 </para>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
797
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
798 </section>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
799
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
800 </module>