Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_zone_sync_module.xml @ 2139:f6e578b1b02d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>