Mercurial > hg > nginx-site
comparison xml/en/docs/stream/ngx_stream_zone_sync_module.xml @ 2139:f6e578b1b02d
Updated docs for the upcoming NGINX Plus release.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Mon, 09 Apr 2018 11:52:48 +0300 |
parents | |
children | acef9537383c |
comparison
equal
deleted
inserted
replaced
2138:cf86c259c9a0 | 2139:f6e578b1b02d |
---|---|
1 <?xml version="1.0"?> | |
2 | |
3 <!-- | |
4 Copyright (C) Nginx, Inc. | |
5 --> | |
6 | |
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> | |
8 | |
9 <module name="Module ngx_stream_zone_sync_module" | |
10 link="/en/docs/stream/ngx_stream_zone_sync_module.html" | |
11 lang="en" | |
12 rev="1"> | |
13 | |
14 <section id="summary"> | |
15 | |
16 <para> | |
17 The <literal>ngx_stream_zone_sync_module</literal> module (1.13.8) | |
18 provides the necessary support for synchronizing contents of | |
19 <link doc="ngx_stream_upstream_module.xml" id="zone">shared memory zones</link> | |
20 between nodes of a cluster. | |
21 To enable synchronization for a particular zone, a corresponding module | |
22 must support this feature. | |
23 Currently, it is possible to synchronize | |
24 <link doc="../http/ngx_http_upstream_module.xml" id="sticky">sticky</link> | |
25 sessions. | |
26 </para> | |
27 </section> | |
28 | |
29 | |
30 <section id="example" name="Example Configuration"> | |
31 | |
32 <para> | |
33 Minimal configuration: | |
34 <example> | |
35 http { | |
36 ... | |
37 | |
38 upstream backend { | |
39 server backend1.example.com:8080; | |
40 server backend2.example.com:8081; | |
41 | |
42 sticky learn | |
43 create=$upstream_cookie_examplecookie | |
44 lookup=$cookie_examplecookie | |
45 zone=client_sessions:1m <emphasis>sync</emphasis>; | |
46 } | |
47 | |
48 ... | |
49 } | |
50 | |
51 stream { | |
52 ... | |
53 | |
54 | |
55 server { | |
56 zone_sync; | |
57 | |
58 listen 127.0.0.1:8090; | |
59 | |
60 # cluster of 2 nodes: each name resolves to a single IP address | |
61 zone_sync_server a.example.com; | |
62 zone_sync_server b.example.com; | |
63 | |
64 } | |
65 </example> | |
66 A more complex configuration with SSL enabled | |
67 and with cluster members defined by DNS: | |
68 <example> | |
69 ... | |
70 | |
71 stream { | |
72 ... | |
73 | |
74 resolver 127.0.0.1 valid=10s; | |
75 | |
76 server { | |
77 zone_sync; | |
78 | |
79 # the name resolves to multiple addresses that correspond to cluster nodes | |
80 zone_sync_server cluster.example.com resolve; | |
81 | |
82 listen 127.0.0.1:4433 ssl; | |
83 | |
84 ssl_certificate localhost.crt; | |
85 ssl_certificate_key localhost.key; | |
86 | |
87 zone_sync_ssl on; | |
88 | |
89 zone_sync_ssl_certificate localhost.crt; | |
90 zone_sync_ssl_certificate_key localhost.key; | |
91 } | |
92 } | |
93 </example> | |
94 </para> | |
95 | |
96 </section> | |
97 | |
98 | |
99 <section id="directives" name="Directives"> | |
100 | |
101 <directive name="zone_sync"> | |
102 <syntax></syntax> | |
103 <default></default> | |
104 <context>stream</context> | |
105 <context>server</context> | |
106 | |
107 <para> | |
108 Enables the synchronization of shared memory zones between cluster nodes. | |
109 Cluster nodes are defined using <link id="zone_sync_server"/> directives. | |
110 </para> | |
111 | |
112 </directive> | |
113 | |
114 | |
115 <directive name="zone_sync_server"> | |
116 <syntax><value>address</value> [<literal>resolve</literal>]</syntax> | |
117 <default></default> | |
118 <context>stream</context> | |
119 <context>server</context> | |
120 | |
121 <para> | |
122 Defines the <value>address</value> of a cluster node | |
123 and an optional method of resolving it. | |
124 The address can be specified as a domain name or IP address | |
125 with a mandatory port, or as a UNIX-domain socket path | |
126 specified after the “<literal>unix:</literal>” prefix. | |
127 A domain name that resolves to several IP addresses defines | |
128 multiple servers at once. | |
129 </para> | |
130 | |
131 <para> | |
132 The "<literal>resolve</literal>" parameter makes nginx to | |
133 monitor changes of the IP addresses | |
134 that correspond to a domain name of the server | |
135 and automatically modifies the configuration | |
136 without the need of restarting nginx. | |
137 </para> | |
138 | |
139 <para> | |
140 In order for this parameter to work, | |
141 the <link doc="ngx_stream_core_module.xml" id="resolver"/> directive | |
142 must be specified in the | |
143 <link doc="ngx_stream_core_module.xml" id="stream"/> block. | |
144 Example: | |
145 <example> | |
146 stream { | |
147 resolver 10.0.0.1; | |
148 | |
149 server { | |
150 zone_sync; | |
151 ... | |
152 zone_sync_server example.com resolve; | |
153 } | |
154 } | |
155 </example> | |
156 </para> | |
157 | |
158 <para> | |
159 <note> | |
160 Each cluster node must be specified only once. | |
161 If using domain names, ensure they are resolvable to a single IP address. | |
162 </note> | |
163 <note> | |
164 The own address of a node is ignored, thus, there is no need to have different | |
165 configurations on different nodes. | |
166 </note> | |
167 </para> | |
168 | |
169 </directive> | |
170 | |
171 | |
172 <directive name="zone_sync_interval"> | |
173 <syntax><value>time</value></syntax> | |
174 <default>1s</default> | |
175 <context>stream</context> | |
176 <context>server</context> | |
177 | |
178 <para> | |
179 Defines an interval for polling updates in a shared memory zone. | |
180 </para> | |
181 | |
182 </directive> | |
183 | |
184 | |
185 <directive name="zone_sync_connect_timeout"> | |
186 <syntax><value>time</value></syntax> | |
187 <default>5s</default> | |
188 <context>stream</context> | |
189 <context>server</context> | |
190 | |
191 <para> | |
192 Defines a timeout for establishing a connection with another cluster node. | |
193 </para> | |
194 | |
195 </directive> | |
196 | |
197 | |
198 <directive name="zone_sync_connect_retry_interval"> | |
199 <syntax><value>time</value></syntax> | |
200 <default>1s</default> | |
201 <context>stream</context> | |
202 <context>server</context> | |
203 | |
204 <para> | |
205 Defines an interval between connection attempts to another cluster node. | |
206 </para> | |
207 | |
208 </directive> | |
209 | |
210 | |
211 <directive name="zone_sync_timeout"> | |
212 <syntax><value>timeout</value></syntax> | |
213 <default>5s</default> | |
214 <context>stream</context> | |
215 <context>server</context> | |
216 | |
217 <para> | |
218 Sets the <value>timeout</value> between two successive | |
219 read or write operations on connection to another cluster node. | |
220 If no data is transmitted within this time, the connection is closed. | |
221 </para> | |
222 | |
223 </directive> | |
224 | |
225 | |
226 <directive name="zone_sync_buffers"> | |
227 <syntax><value>number</value> <value>size</value></syntax> | |
228 <default>256 4k|8k</default> | |
229 <context>stream</context> | |
230 <context>server</context> | |
231 | |
232 <para> | |
233 Sets the <value>number</value> and <value>size</value> of the | |
234 per-zone buffers used for pushing zone contents. | |
235 By default, the buffer size is equal to one memory page. | |
236 This is either 4K or 8K, depending on a platform. | |
237 </para> | |
238 | |
239 </directive> | |
240 | |
241 | |
242 <directive name="zone_sync_recv_buffer_size"> | |
243 <syntax><value>size</value></syntax> | |
244 <default>4k|8k</default> | |
245 <context>stream</context> | |
246 <context>server</context> | |
247 | |
248 <para> | |
249 Sets <value>size</value> of a per-connection receive buffer used to parse | |
250 incoming stream of synchronization messages. | |
251 By default, the buffer size is equal to one memory page. | |
252 This is either 4K or 8K, depending on a platform. | |
253 </para> | |
254 | |
255 </directive> | |
256 | |
257 | |
258 <directive name="zone_sync_ssl"> | |
259 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
260 <default>off</default> | |
261 <context>stream</context> | |
262 <context>server</context> | |
263 | |
264 <para> | |
265 Enables the SSL/TLS protocol for connections to another cluster server. | |
266 </para> | |
267 | |
268 </directive> | |
269 | |
270 | |
271 <directive name="zone_sync_ssl_certificate"> | |
272 <syntax><value>file</value></syntax> | |
273 <default/> | |
274 <context>stream</context> | |
275 <context>server</context> | |
276 | |
277 <para> | |
278 Specifies a <value>file</value> with the certificate in the PEM format | |
279 used for authentication to another cluster server. | |
280 </para> | |
281 | |
282 </directive> | |
283 | |
284 | |
285 <directive name="zone_sync_ssl_certificate_key"> | |
286 <syntax><value>file</value></syntax> | |
287 <default/> | |
288 <context>stream</context> | |
289 <context>server</context> | |
290 | |
291 <para> | |
292 Specifies a <value>file</value> with the secret key in the PEM format | |
293 used for authentication to another cluster server. | |
294 </para> | |
295 | |
296 </directive> | |
297 | |
298 | |
299 <directive name="zone_sync_ssl_ciphers"> | |
300 <syntax><value>ciphers</value></syntax> | |
301 <default>DEFAULT</default> | |
302 <context>stream</context> | |
303 <context>server</context> | |
304 | |
305 <para> | |
306 Specifies the enabled ciphers for connections to another cluster server. | |
307 The ciphers are specified in the format understood by the OpenSSL library. | |
308 </para> | |
309 | |
310 <para> | |
311 The full list can be viewed using the | |
312 “<command>openssl ciphers</command>” command. | |
313 </para> | |
314 | |
315 </directive> | |
316 | |
317 | |
318 <directive name="zone_sync_ssl_crl"> | |
319 <syntax><value>file</value></syntax> | |
320 <default/> | |
321 <context>stream</context> | |
322 <context>server</context> | |
323 | |
324 <para> | |
325 Specifies a <value>file</value> with revoked certificates (CRL) | |
326 in the PEM format used to <link id="zone_sync_ssl_verify">verify</link> | |
327 the certificate of another cluster server. | |
328 </para> | |
329 | |
330 </directive> | |
331 | |
332 | |
333 <directive name="zone_sync_ssl_password_file"> | |
334 <syntax><value>file</value></syntax> | |
335 <default/> | |
336 <context>stream</context> | |
337 <context>server</context> | |
338 | |
339 <para> | |
340 Specifies a <value>file</value> with passphrases for | |
341 <link id="zone_sync_ssl_certificate_key">secret keys</link> | |
342 where each passphrase is specified on a separate line. | |
343 Passphrases are tried in turn when loading the key. | |
344 </para> | |
345 | |
346 </directive> | |
347 | |
348 | |
349 <directive name="zone_sync_ssl_protocols"> | |
350 <syntax> | |
351 [<literal>SSLv2</literal>] | |
352 [<literal>SSLv3</literal>] | |
353 [<literal>TLSv1</literal>] | |
354 [<literal>TLSv1.1</literal>] | |
355 [<literal>TLSv1.2</literal>] | |
356 [<literal>TLSv1.3</literal>]</syntax> | |
357 <default>TLSv1 TLSv1.1 TLSv1.2</default> | |
358 <context>stream</context> | |
359 <context>server</context> | |
360 | |
361 <para> | |
362 Enables the specified protocols for connections to another cluster server. | |
363 </para> | |
364 | |
365 </directive> | |
366 | |
367 | |
368 <directive name="zone_sync_ssl_trusted_certificate"> | |
369 <syntax><value>file</value></syntax> | |
370 <default/> | |
371 <context>stream</context> | |
372 <context>server</context> | |
373 | |
374 <para> | |
375 Specifies a <value>file</value> with trusted CA certificates in the PEM format | |
376 used to <link id="zone_sync_ssl_verify">verify</link> | |
377 the certificate of another cluster server. | |
378 </para> | |
379 | |
380 </directive> | |
381 | |
382 | |
383 <directive name="zone_sync_ssl_verify"> | |
384 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
385 <default>off</default> | |
386 <context>stream</context> | |
387 <context>server</context> | |
388 | |
389 <para> | |
390 Enables or disables verification of another cluster server certificate. | |
391 </para> | |
392 | |
393 </directive> | |
394 | |
395 | |
396 <directive name="zone_sync_ssl_verify_depth"> | |
397 <syntax><value>number</value></syntax> | |
398 <default>1</default> | |
399 <context>stream</context> | |
400 <context>server</context> | |
401 | |
402 <para> | |
403 Sets the verification depth in another cluster server certificates chain. | |
404 </para> | |
405 | |
406 </directive> | |
407 | |
408 </section> | |
409 | |
410 | |
411 <section id="stream_zone_sync_status" name="API endpoints"> | |
412 <para> | |
413 The synchronization status of a node is available via the | |
414 <link doc= "../http/ngx_http_api_module.xml" id="stream_zone_sync_">/stream/zone_sync/</link> | |
415 endpoint of the API which returns the | |
416 <link doc= "../http/ngx_http_api_module.xml" id="def_nginx_stream_zone_sync">following</link> | |
417 metrics. | |
418 </para> | |
419 | |
420 </section> | |
421 | |
422 | |
423 <section id="controlling_cluster_node" name="Starting, stopping, removing a cluster node"> | |
424 <para> | |
425 To start a new node, update a DNS record of a cluster hostname | |
426 with the IP address of the new node and start an instance. | |
427 The new node will discover other nodes from DNS or static configuration | |
428 and will start sending updates to them. | |
429 Other nodes will eventually discover the new node using DNS and | |
430 start pushing updates to it. | |
431 In case of static configuration, | |
432 other nodes need to be reloaded in order to send updates to the new node. | |
433 </para> | |
434 | |
435 <para> | |
436 To stop a node, send the <literal>QUIT</literal> signal to the instance. | |
437 The node will finish zone synchronization | |
438 and gracefully close open connections. | |
439 </para> | |
440 | |
441 <para> | |
442 To remove a node, update a DNS record of a cluster hostname | |
443 and remove the IP address of the node. | |
444 All other nodes will eventually discover that the node is removed, | |
445 close connections to the node, and will no longer try to connect to it. | |
446 After the node is removed, it can be stopped as described above. | |
447 In case of static configuration, other nodes need to be reloaded | |
448 in order to stop sending updates to the removed node. | |
449 </para> | |
450 | |
451 </section> | |
452 | |
453 </module> |