Mercurial > hg > nginx-site

annotate xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1450:f5b5eefc43cb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated commercial docs for the upcoming release.
author Ruslan Ermilov <ru@nginx.com>
date Thu, 09 Apr 2015 19:18:54 +0300
parents f5dcc23b214f
children e69e4dbcc760
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"
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
12 rev="5">
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>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
17 The <literal>ngx_stream_upstream_module</literal> module (1.7.7)
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 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
24 <note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
25 This module is available as part of our
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
26 <commercial_version>commercial subscription</commercial_version>.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
27 </note>
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
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
30 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
31
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
32
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
33 <section id="example" name="Example Configuration">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
34
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
35 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
36 <example>
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
37 resolver 10.0.0.1;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
38
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
39 upstream <emphasis>backend</emphasis> {
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
40 zone upstream_backend 64k;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
41
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
42 hash $remote_addr consistent;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
43
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
44 server backend1.example.com:12345 weight=5;
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
45 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
46 server unix:/tmp/backend2;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
47 server backend3.example.com:12345 resolve;
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
48 }
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
49
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
50 server {
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
51 listen 12346;
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
52 proxy_pass <emphasis>backend</emphasis>;
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
53 health_check;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
54 }
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
55 </example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
56 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
57
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
58 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
59
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
60
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
61 <section id="directives" name="Directives">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
62
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
63 <directive name="upstream">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
64 <syntax block="yes"><value>name</value></syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
65 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
66 <context>stream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
67
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
68 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
69 Defines a group of servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
70 Servers can listen on different ports.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
71 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
72 can be mixed.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
73 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
74
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
75 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
76 Example:
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
77 <example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
78 upstream backend {
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
79 server backend1.example.com:12345 weight=5;
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
80 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
81 server unix:/tmp/backend2;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
82 server backend3.example.com:12345 resolve;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
83
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
84 server backup1.example.com:12345 backup;
1367
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 </example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
87 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
88
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
89 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
90 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
91 weighted round-robin balancing method.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
92 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
93 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
94 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
95 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
96 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
97 servers will be tried.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
98 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
99 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
100
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
101 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
102
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 <directive name="server">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
105 <syntax><value>address</value> [<value>parameters</value>]</syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
106 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
107 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
108
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
109 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
110 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
111 of a server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
112 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
113 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
114 specified after the “<literal>unix:</literal>” prefix.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
115 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
116 multiple servers at once.
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 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
120 The following parameters can be defined:
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
121 <list type="tag">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
122
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
123 <tag-name id="weight">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
124 <literal>weight</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
125 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
126 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
127 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
128 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
129
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
130 <tag-name id="max_fails">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
131 <literal>max_fails</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
132 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
133 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
134 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
135 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
136 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
137 <literal>fail_timeout</literal> parameter.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
138 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
139 The zero value disables the accounting of attempts.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
140 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
141 while establishing a connection with the server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
142 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
143
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
144 <tag-name id="fail_timeout">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
145 <literal>fail_timeout</literal>=<value>time</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
146 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
147 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
148 sets
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
149 <list type="bullet">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
150
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
151 <listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
152 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
153 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
154 </listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
155
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
156 <listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
157 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
158 </listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
159
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
160 </list>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
161 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
162 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
163
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
164 <tag-name id="backup">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
165 <literal>backup</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
166 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
167 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
168 marks the server as a backup server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
169 Connections to the backup server will be passed
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
170 when the primary servers are unavailable.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
171 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
172
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
173 <tag-name id="down">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
174 <literal>down</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
175 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
176 <tag-desc>
1410
f5dcc23b214f Deleted info about hash and ip_hash from the down parameter.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1406
diff changeset
177 marks the server as permanently unavailable.
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
178 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
179
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
180 <tag-name id="max_conns">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
181 <literal>max_conns</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
182 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
183 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
184 limits the maximum <value>number</value> of simultaneous connections to the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
185 proxied server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
186 Default value is zero, meaning there is no limit.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
187 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
188
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
189 <tag-name id="resolve">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
190 <literal>resolve</literal>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
191 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
192 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
193 monitors changes of the IP addresses
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
194 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
195 and automatically modifies the upstream configuration
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
196 without the need of restarting nginx (1.7.10).
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
197 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
198 In order for this parameter to work,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
199 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
200 must be specified in the
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
201 <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
202 Example:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
203 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
204 stream {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
205 resolver 10.0.0.1;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
206
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
207 upstream u {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
208 zone ...;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
209 ...
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
210 server example.com:12345 resolve;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
211 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
212 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
213 </example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
214 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
215 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
216
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
217 <tag-name id="slow_start">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
218 <literal>slow_start</literal>=<value>time</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
219 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
220 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
221 sets the <value>time</value> during which the server will recover its weight
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
222 from zero to a nominal value,
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
223 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
224 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
225 Default value is zero, i.e. slow start is disabled.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
226 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
227
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
228 </list>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
229 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
230
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
231 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
232 <note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
233 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
234 <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
235 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
236 </note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
237 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
238
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
239 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
240
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
241
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
242 <directive name="zone">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
243 <syntax><value>name</value> <value>size</value></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
244 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
245 <context>upstream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
246 <appeared-in>1.7.10</appeared-in>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
247
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 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
250 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
251 shared between worker processes.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
252 Such groups allow changing the group membership
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
253 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
254 without the need of restarting nginx.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
255 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
256 handled by
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
257 <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
258 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
259
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
260 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
261
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
262
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
263 <directive name="hash">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
264 <syntax><value>key</value> [<literal>consistent</literal>]</syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
265 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
266 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
267
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
268 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
269 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
270 where client-server mapping is based on the hashed <value>key</value> value.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
271 Currently, the only supported value for the <literal>key</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
272 is the client remote address specified as <literal>$remote_addr</literal>.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
273 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
274 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
275 The method is compatible with the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
276 <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
277 Perl library.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
278 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
279
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
280 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
281 If the <literal>consistent</literal> parameter is specified,
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
282 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
283 consistent hashing method will be used instead.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
284 The method ensures that only a few keys
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
285 will be remapped to different servers
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
286 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
287 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
288 The method is compatible with the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
289 <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
290 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
291 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
292
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
293 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
294
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
295
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
296 <directive name="least_conn">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
297 <syntax/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
298 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
299 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
300
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
301 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
302 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
303 where a connection
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
304 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
305 taking into account weights of servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
306 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
307 weighted round-robin balancing method.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
308 </para>
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 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
311
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
312
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
313 <directive name="least_time">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
314 <syntax><literal>connect</literal> |
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
315 <literal>first_byte</literal> |
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
316 <literal>last_byte</literal></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
317 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
318 <context>upstream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
319 <appeared-in>1.7.11</appeared-in>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
320
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
321 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
322 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
323 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
324 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
325 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
326 weighted round-robin balancing method.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
327 </para>
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 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
331 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
332 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
333 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
334 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
335 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
336 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
337
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
338 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
339
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
340
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
341 <directive name="health_check">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
342 <syntax>[<value>parameters</value>]</syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
343 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
344 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
345 <appeared-in>1.7.10</appeared-in>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
346
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
347 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
348 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
349 <link id="upstream">group</link>.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
350 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
351
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
352 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
353 The following optional parameters are supported:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
354 <list type="tag">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
355
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
356 <tag-name id="interval">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
357 <literal>interval</literal>=<value>time</value>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
358 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
359 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
360 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
361 by default, 5 seconds;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
362 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
363
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
364 <tag-name id="fails">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
365 <literal>fails</literal>=<value>number</value>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
366 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
367 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
368 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
369 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
370 by default, 1;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
371 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
372
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
373 <tag-name id="passes">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
374 <literal>passes</literal>=<value>number</value>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
375 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
376 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
377 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
378 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
379 by default, 1;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
380 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
381
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
382 <tag-name id="hc_match">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
383 <literal>match</literal>=<value>name</value>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
384 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
385 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
386 specifies the <literal>match</literal> block configuring the tests that a
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
387 successful connection should pass in order for a health check to pass;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
388 by default, only the ability to connect to the server is checked.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
389 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
390
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
391 </list>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
392 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
393
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
394 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
395 For example,
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
396 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
397 server {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
398 proxy_pass backend;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
399 health_check;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
400 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
401 </example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
402 will check the ability to connect to each
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
403 server in the <literal>backend</literal> group every five seconds.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
404 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
405 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
406 be considered unhealthy.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
407 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
408 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
409
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
410 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
411 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
412 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
413 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
414 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
415
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
416 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
417 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
418 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
419
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
420 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
421 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
422 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
423 considered unhealthy.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
424 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
425
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
426 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
427
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
428
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
429 <directive name="health_check_timeout">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
430 <syntax><value>timeout</value></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
431 <default>5s</default>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
432 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
433 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
434 <appeared-in>1.7.10</appeared-in>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
435
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
436 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
437 Overrides the
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
438 <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
439 value for health checks.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
440 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
441
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
442 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
443
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
444
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
445 <directive name="match">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
446 <syntax block="yes"><value>name</value> </syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
447 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
448 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
449 <appeared-in>1.7.10</appeared-in>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
451 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
452 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
453 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
454
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
455 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
456 The following parameters can be configured:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
457 <list type="tag">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
458
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
459 <tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
460 <literal>send</literal> <value>string</value>;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
461 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
462 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
463 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
464 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
465
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
466 <tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
467 <literal>expect</literal> <literal>~</literal> <value>regexp</value>;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
468 </tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
469 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
470 a regular expression that the data obtained from the server should match.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
471 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
472 “<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
473 “<literal>~</literal>” modifier (for case-sensitive matching).
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
474 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
475
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
476 </list>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
477 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
478
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
479 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
480 Health check is passed if:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
481 <list type="bullet">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
482 <listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
483 the connection was successfully established;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
484 </listitem>
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 <listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
487 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
488 if specified, was sent;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
489 </listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
490
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
491 <listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
492 the data obtained from the server matched the regular expression
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
493 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
494 </listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
495
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
496 <listitem>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
497 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
498 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
499 </listitem>
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 </list>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
502 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
503
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
504 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
505 Example:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
506 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
507 upstream backend {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
508 zone upstream_backend 10m;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
509 server 127.0.0.1:12345;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
510 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
511
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
512 match http {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
513 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
514 expect ~ "200 OK";
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
515 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
516
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
517 server {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
518 listen 12346;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
519 proxy_pass backend;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
520 health_check match=http;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
521 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
522 </example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
523 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
524
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
525 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
526 <note>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
527 Only the first
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
528 <link doc="ngx_stream_proxy_module.xml" id="proxy_upstream_buffer"/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
529 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
530 </note>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
531 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
532
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
533 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
534
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
535 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
536
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
537 </module>