Mercurial > hg > nginx-site

annotate xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1367:f1e14d87d833

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 Mon, 01 Dec 2014 13:40:25 +0300
parents
children 4569719f4247
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) 2014 Yaroslav Zhuravlev
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
5 Copyright (C) Nginx, Inc.
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
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
9
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
10 <module name="Module ngx_stream_upstream_module"
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
11 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
12 lang="en"
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
13 rev="1">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
14
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
15 <section id="summary">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
17 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
18 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
19 is used to define groups of servers that can be referenced
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
20 by the <link doc="ngx_stream_module.xml" id="proxy_pass"/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
21 directive.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
22 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
23
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
24 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
25 <note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
26 This module is available as part of our
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
27 <commercial_version>commercial subscription</commercial_version>.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
28 </note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
29 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
30
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
31 </section>
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
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
34 <section id="example" name="Example Configuration">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
35
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
36 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
37 <example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
38 stream {
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
39 upstream backend {
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
40 hash $remote_addr consistent;
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
41 server backend1.example.com:8000;
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
42 server backend2.example.com:8000;
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
43 server backend3.example.com:8001;
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
44 }
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
45
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
46 server {
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
47 listen 9000;
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
48 proxy_pass backend;
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
49 }
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
50 }
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
51 </example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
52 </para>
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 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
55
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 <section id="directives" name="Directives">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
58
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
59 <directive name="upstream">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
60 <syntax block="yes"><value>name</value></syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
61 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
62 <context>stream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
63
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
64 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
65 Defines a group of servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
66 Servers can listen on different ports.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
67 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
68 can be mixed.
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
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
71 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
72 Example:
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
73 <example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
74 upstream backend {
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
75 server backend1.example.com:8080 weight=5;
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
76 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
77 server unix:/tmp/backend3;
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 server backup1.example.com:8080 backup;
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
80 }
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
81 </example>
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
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
84 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
85 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
86 weighted round-robin balancing method.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
87 In the above example, each 7 connections will be distributed as follows:
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
88 5 connections go to <literal>backend1.example.com</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
89 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
90 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
91 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
92 servers will be tried.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
93 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
94 </para>
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 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
97
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
98
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
99 <directive name="server">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
100 <syntax><value>address</value> [<value>parameters</value>]</syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
101 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
102 <context>upstream</context>
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 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
105 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
106 of a server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
107 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
108 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
109 specified after the “<literal>unix:</literal>” prefix.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
110 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
111 multiple servers at once.
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
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
114 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
115 The following parameters can be defined:
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
116 <list type="tag">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
117
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
118 <tag-name id="weight">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
119 <literal>weight</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
120 </tag-name>
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 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
123 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
124
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
125 <tag-name id="max_fails">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
126 <literal>max_fails</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
127 </tag-name>
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 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
130 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
131 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
132 <literal>fail_timeout</literal> parameter.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
133 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
134 The zero value disables the accounting of attempts.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
135 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
136 while establishing a connection with the server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
137 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
138
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
139 <tag-name id="fail_timeout">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
140 <literal>fail_timeout</literal>=<value>time</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
141 </tag-name>
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 sets
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
144 <list type="bullet">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
145
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
146 <listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
147 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
148 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
149 </listitem>
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 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
153 </listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
154
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
155 </list>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
156 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
157 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
158
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
159 <tag-name id="backup">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
160 <literal>backup</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
161 </tag-name>
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 marks the server as a backup server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
164 Connections to the backup server will be passed
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
165 when the primary servers are unavailable.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
166 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
167
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
168 <tag-name id="down">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
169 <literal>down</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
170 </tag-name>
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 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
173 the <link id="hash"/> directive.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
174 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
175
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
176 <tag-name id="max_conns">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
177 <literal>max_conns</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
178 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
179 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
180 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
181 proxied server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
182 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
183 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
184
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
185 <tag-name id="slow_start">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
186 <literal>slow_start</literal>=<value>time</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
187 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
188 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
189 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
190 from zero to a nominal value,
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
191 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
192 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
193 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
194 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
195
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
196 </list>
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
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
199 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
200 <note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
201 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
202 <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
203 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
204 </note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
205 </para>
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 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
208
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
209
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
210 <directive name="hash">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
211 <syntax><value>key</value> [<literal>consistent</literal>]</syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
212 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
213 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
214
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
215 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
216 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
217 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
218 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
219 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
220 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
221 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
222 The method is compatible with the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
223 <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
224 Perl library.
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
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
227 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
228 If the <literal>consistent</literal> parameter is specified,
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
229 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
230 consistent hashing method will be used instead.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
231 The method ensures that only a few keys
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
232 will be remapped to different servers
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
233 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
234 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
235 The method is compatible with the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
236 <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
237 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
238 </para>
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 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
241
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
242
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
243 <directive name="least_conn">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
244 <syntax/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
245 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
246 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
247
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
248 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
249 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
250 where a connection
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
251 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
252 taking into account weights of servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
253 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
254 weighted round-robin balancing method.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
255 </para>
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 </directive>
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 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
260
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
261 </module>