Mercurial > hg > nginx-site
annotate xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1392:82e62822abe8
Sorted upstream module variables.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Mon, 19 Jan 2015 15:23:48 +0300 |
parents | f1e14d87d833 |
children | 4569719f4247 |
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> |