Mercurial > hg > nginx-site

annotate xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1406:ea73cd9d4cdb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Changed stream_upstream examples.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 05 Feb 2015 15:25:48 +0300
parents 4569719f4247
children f5dcc23b214f
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"
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
12 rev="3">
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>
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
37 upstream <emphasis>backend</emphasis> {
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
38 hash $remote_addr consistent;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
39
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
40 server backend1.example.com:12345 weight=5;
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
41 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s;
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
42 server unix:/tmp/backend3;
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
43 }
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
44
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
45 server {
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
46 listen 12346;
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
47 proxy_pass <emphasis>backend</emphasis>;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
48 }
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
49 </example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
50 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
51
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
52 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
53
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 <section id="directives" name="Directives">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
56
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
57 <directive name="upstream">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
58 <syntax block="yes"><value>name</value></syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
59 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
60 <context>stream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
61
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
62 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
63 Defines a group of servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
64 Servers can listen on different ports.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
65 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
66 can be mixed.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
67 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
68
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
69 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
70 Example:
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
71 <example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
72 upstream backend {
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
73 server backend1.example.com:12345 weight=5;
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
74 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
75 server unix:/tmp/backend3;
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
76
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
77 server backup1.example.com:12345 backup;
1367
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 </example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
80 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
81
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
82 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
83 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
84 weighted round-robin balancing method.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
85 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
86 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
87 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
88 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
89 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
90 servers will be tried.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
91 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
92 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
93
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
94 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
95
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
96
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
97 <directive name="server">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
98 <syntax><value>address</value> [<value>parameters</value>]</syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
99 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
100 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
101
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
102 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
103 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
104 of a server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
105 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
106 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
107 specified after the “<literal>unix:</literal>” prefix.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
108 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
109 multiple servers at once.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
110 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
111
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
112 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
113 The following parameters can be defined:
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
114 <list type="tag">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
115
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
116 <tag-name id="weight">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
117 <literal>weight</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
118 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
119 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
120 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
121 </tag-desc>
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="max_fails">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
124 <literal>max_fails</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 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
128 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
129 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
130 <literal>fail_timeout</literal> parameter.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
131 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
132 The zero value disables the accounting of attempts.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
133 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
134 while establishing a connection with the server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
135 </tag-desc>
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 <tag-name id="fail_timeout">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
138 <literal>fail_timeout</literal>=<value>time</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
139 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
140 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
141 sets
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
142 <list type="bullet">
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 <listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
145 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
146 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
147 </listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
148
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
149 <listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
150 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
151 </listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
152
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
153 </list>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
154 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
155 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
156
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
157 <tag-name id="backup">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
158 <literal>backup</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
159 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
160 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
161 marks the server as a backup server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
162 Connections to the backup server will be passed
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
163 when the primary servers are unavailable.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
164 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
165
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
166 <tag-name id="down">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
167 <literal>down</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
168 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
169 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
170 marks the server as permanently unavailable; used along with
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
171 the <link id="hash"/> directive.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
172 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
173
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
174 <tag-name id="max_conns">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
175 <literal>max_conns</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
176 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
177 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
178 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
179 proxied server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
180 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
181 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
182
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
183 <tag-name id="slow_start">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
184 <literal>slow_start</literal>=<value>time</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
185 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
186 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
187 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
188 from zero to a nominal value,
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
189 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
190 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
191 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
192 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
193
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
194 </list>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
195 </para>
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 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
198 <note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
199 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
200 <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
201 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
202 </note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
203 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
204
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
205 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
206
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
207
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
208 <directive name="hash">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
209 <syntax><value>key</value> [<literal>consistent</literal>]</syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
210 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
211 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
212
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
213 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
214 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
215 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
216 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
217 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
218 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
219 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
220 The method is compatible with the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
221 <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
222 Perl library.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
223 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
224
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
225 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
226 If the <literal>consistent</literal> parameter is specified,
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
227 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
228 consistent hashing method will be used instead.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
229 The method ensures that only a few keys
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
230 will be remapped to different servers
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
231 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
232 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
233 The method is compatible with the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
234 <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
235 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
236 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
237
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
238 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
239
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 <directive name="least_conn">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
242 <syntax/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
243 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
244 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
245
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
246 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
247 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
248 where a connection
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
249 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
250 taking into account weights of servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
251 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
252 weighted round-robin balancing method.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
253 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
254
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
255 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
256
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
257 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
258
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
259 </module>