Mercurial > hg > nginx-site
comparison xml/en/docs/ngx_mgmt_module.xml @ 3029:27008cb3fb27
Updated docs for the upcoming NGINX Plus release.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 19 Dec 2023 12:58:01 +0000 |
parents | |
children | 6ffde2466d2d |
comparison
equal
deleted
inserted
replaced
3028:55f8ce8a8cb0 | 3029:27008cb3fb27 |
---|---|
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_mgmt_module" | |
10 link="/en/docs/ngx_mgmt_module.html" | |
11 lang="en" | |
12 rev="1"> | |
13 | |
14 <section id="summary"> | |
15 | |
16 <para> | |
17 The <literal>ngx_mgmt_module</literal> module enables reporting of | |
18 current nginx installation to | |
19 <link url="https://docs.nginx.com/nginx-management-suite/about/">NGINX | |
20 Management Suite Instance Manager</link> (1.25.3). | |
21 By default, nginx sends usage info | |
22 to the Instance Manager located at <literal>nginx-mgmt.local</literal> | |
23 every 30 minutes using the SSL connection. | |
24 The system resolver is used unless | |
25 a <link id="resolver">custom resolver</link> is configured | |
26 and is invoked only once when the | |
27 configuration is <link doc="beginners_guide.xml" id="control">loaded</link>. | |
28 </para> | |
29 | |
30 <para> | |
31 <note> | |
32 This module is available as part of our | |
33 <commercial_version>commercial subscription</commercial_version>. | |
34 </note> | |
35 </para> | |
36 | |
37 </section> | |
38 | |
39 | |
40 <section id="example" name="Example Configuration"> | |
41 | |
42 <para> | |
43 <example> | |
44 mgmt { | |
45 usage_report endpoint=nginx-mgmt.local interval=30m; | |
46 resolver DNS_IP; | |
47 | |
48 uuid_file /var/lib/nginx/nginx.id; | |
49 | |
50 ssl_protocols TLSv1.2 TLSv1.3; | |
51 ssl_ciphers DEFAULT; | |
52 | |
53 ssl_certificate client_cert.pem; | |
54 ssl_certificate_key client_cert.key; | |
55 | |
56 # configure server certificate verification | |
57 # to validate the authenticity of NMS | |
58 ssl_trusted_certificate trusted_ca_cert.crt; | |
59 ssl_verify on; | |
60 ssl_verify_depth 2; | |
61 } | |
62 </example> | |
63 </para> | |
64 | |
65 </section> | |
66 | |
67 | |
68 <section id="directives" name="Directives"> | |
69 | |
70 <directive name="connect_timeout"> | |
71 <syntax><value>time</value></syntax> | |
72 <default>15s</default> | |
73 <context>mgmt</context> | |
74 | |
75 <para> | |
76 Defines a timeout for establishing a connection with the Instance Manager. | |
77 </para> | |
78 | |
79 </directive> | |
80 | |
81 | |
82 <directive name="mgmt"> | |
83 <syntax block="yes"/> | |
84 <default/> | |
85 <context>main</context> | |
86 | |
87 <para> | |
88 Provides the configuration file context | |
89 in which the management server directives are specified. | |
90 </para> | |
91 | |
92 </directive> | |
93 | |
94 | |
95 <directive name="read_timeout"> | |
96 <syntax><value>time</value></syntax> | |
97 <default>60s</default> | |
98 <context>mgmt</context> | |
99 | |
100 <para> | |
101 Defines a timeout for reading a response from the Instance Manager. | |
102 The timeout is set only between two successive read operations, | |
103 not for the transmission of the whole response. | |
104 If the Instance Manager does not transmit anything within this time, | |
105 the connection is closed. | |
106 </para> | |
107 | |
108 </directive> | |
109 | |
110 | |
111 <directive name="resolver"> | |
112 <syntax> | |
113 <value>address</value> ... | |
114 [<literal>valid</literal>=<value>time</value>] | |
115 [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] | |
116 [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] | |
117 [<literal>status_zone</literal>=<value>zone</value>]</syntax> | |
118 <default/> | |
119 <context>mgmt</context> | |
120 | |
121 <para> | |
122 Configures name servers used to resolve names of the Instance Manager | |
123 into addresses, for example: | |
124 <example> | |
125 resolver 127.0.0.1 [::1]:5353; | |
126 </example> | |
127 The address can be specified as a domain name or IP address, | |
128 with an optional port. | |
129 If port is not specified, the port 53 is used. | |
130 Name servers are queried in a round-robin fashion. | |
131 </para> | |
132 | |
133 <para id="resolver_ipv6"> | |
134 By default, nginx will look up both IPv4 and IPv6 addresses while resolving. | |
135 If looking up of IPv4 or IPv6 addresses is not desired, | |
136 the <literal>ipv4=off</literal> or | |
137 the <literal>ipv6=off</literal> parameter can be specified. | |
138 </para> | |
139 | |
140 <para id="resolver_valid"> | |
141 By default, nginx caches answers using the TTL value of a response. | |
142 An optional <literal>valid</literal> parameter allows overriding it: | |
143 <example> | |
144 resolver 127.0.0.1 [::1]:5353 valid=30s; | |
145 </example> | |
146 <note> | |
147 To prevent DNS spoofing, it is recommended | |
148 configuring DNS servers in a properly secured trusted local network. | |
149 </note> | |
150 </para> | |
151 | |
152 <para id="resolver_status_zone"> | |
153 The optional <literal>status_zone</literal> parameter | |
154 enables | |
155 <link doc="ngx_http_api_module.xml" id="resolvers_">collection</link> | |
156 of DNS server statistics of requests and responses | |
157 in the specified <value>zone</value>. | |
158 </para> | |
159 | |
160 </directive> | |
161 | |
162 | |
163 <directive name="resolver_timeout"> | |
164 <syntax><value>time</value></syntax> | |
165 <default>30s</default> | |
166 <context>mgmt</context> | |
167 | |
168 <para> | |
169 Sets a timeout for name resolution. | |
170 </para> | |
171 | |
172 </directive> | |
173 | |
174 | |
175 <directive name="send_timeout"> | |
176 <syntax><value>time</value></syntax> | |
177 <default>60s</default> | |
178 <context>mgmt</context> | |
179 | |
180 <para> | |
181 Sets a timeout for transmitting a request to the Instance Manager. | |
182 The timeout is set only between two successive write operations, | |
183 not for the transmission of the whole request. | |
184 If the Instance Manager does not receive anything within this time, | |
185 the connection is closed. | |
186 </para> | |
187 | |
188 </directive> | |
189 | |
190 | |
191 <directive name="ssl"> | |
192 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
193 <default>on</default> | |
194 <context>mgmt</context> | |
195 | |
196 <para> | |
197 Enables the HTTPS protocol for all | |
198 connections to the Instance Manager. | |
199 </para> | |
200 | |
201 </directive> | |
202 | |
203 | |
204 <directive name="ssl_certificate"> | |
205 <syntax><value>file</value></syntax> | |
206 <default/> | |
207 <context>mgmt</context> | |
208 | |
209 <para> | |
210 Specifies a <value>file</value> with the certificate in the PEM format | |
211 used for authentication to the Instance Manager. | |
212 </para> | |
213 | |
214 </directive> | |
215 | |
216 | |
217 <directive name="ssl_certificate_key"> | |
218 <syntax><value>file</value></syntax> | |
219 <default/> | |
220 <context>mgmt</context> | |
221 | |
222 <para> | |
223 Specifies a <value>file</value> with the secret key in the PEM format | |
224 used for authentication to the Instance Manager. | |
225 </para> | |
226 | |
227 </directive> | |
228 | |
229 | |
230 <directive name="ssl_ciphers"> | |
231 <syntax><value>ciphers</value></syntax> | |
232 <default>DEFAULT</default> | |
233 <context>mgmt</context> | |
234 | |
235 <para> | |
236 Specifies the enabled ciphers for requests to the Instance Manager. | |
237 The ciphers are specified in the format understood by the OpenSSL library. | |
238 </para> | |
239 | |
240 <para> | |
241 The full list can be viewed using the | |
242 “<command>openssl ciphers</command>” command. | |
243 </para> | |
244 | |
245 </directive> | |
246 | |
247 | |
248 <directive name="ssl_crl"> | |
249 <syntax><value>file</value></syntax> | |
250 <default/> | |
251 <context>mgmt</context> | |
252 | |
253 <para> | |
254 Specifies a <value>file</value> with revoked certificates (CRL) | |
255 in the PEM format used to <link id="ssl_verify">verify</link> | |
256 the certificate of the Instance Manager. | |
257 </para> | |
258 | |
259 </directive> | |
260 | |
261 | |
262 <directive name="ssl_name"> | |
263 <syntax><value>name</value></syntax> | |
264 <default>ssl_name host</default> | |
265 <context>mgmt</context> | |
266 | |
267 <para> | |
268 Allows overriding the server name used to | |
269 <link id="ssl_verify">verify</link> | |
270 the certificate of the Instance Manager and to be | |
271 <link id="ssl_server_name">passed through SNI</link> | |
272 when establishing a connection with the Instance Manager. | |
273 </para> | |
274 | |
275 </directive> | |
276 | |
277 | |
278 <directive name="ssl_password_file"> | |
279 <syntax><value>file</value></syntax> | |
280 <default/> | |
281 <context>mgmt</context> | |
282 | |
283 <para> | |
284 Specifies a <value>file</value> with passphrases for | |
285 <link id="ssl_certificate_key">secret keys</link> | |
286 where each passphrase is specified on a separate line. | |
287 Passphrases are tried in turn when loading the key. | |
288 </para> | |
289 | |
290 </directive> | |
291 | |
292 | |
293 <directive name="ssl_protocols"> | |
294 <syntax> | |
295 [<literal>SSLv2</literal>] | |
296 [<literal>SSLv3</literal>] | |
297 [<literal>TLSv1</literal>] | |
298 [<literal>TLSv1.1</literal>] | |
299 [<literal>TLSv1.2</literal>] | |
300 [<literal>TLSv1.3</literal>]</syntax> | |
301 <default>TLSv1 TLSv1.1 TLSv1.2 TLSv1.3</default> | |
302 <context>mgmt</context> | |
303 | |
304 <para> | |
305 Enables the specified protocols for requests to the Instance Manager. | |
306 </para> | |
307 | |
308 </directive> | |
309 | |
310 | |
311 <directive name="ssl_server_name"> | |
312 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
313 <default>off</default> | |
314 <context>mgmt</context> | |
315 | |
316 <para> | |
317 Enables or disables passing of the server name through | |
318 <link url="http://en.wikipedia.org/wiki/Server_Name_Indication">TLS | |
319 Server Name Indication extension</link> (SNI, RFC 6066) | |
320 when establishing a connection with the Instance Manager. | |
321 </para> | |
322 | |
323 </directive> | |
324 | |
325 | |
326 <directive name="ssl_trusted_certificate"> | |
327 <syntax><value>file</value></syntax> | |
328 <default/> | |
329 <context>mgmt</context> | |
330 | |
331 <para> | |
332 Specifies a <value>file</value> with trusted CA certificates in the PEM format | |
333 used to <link id="ssl_verify">verify</link> | |
334 the certificate of the Instance Manager. | |
335 </para> | |
336 | |
337 </directive> | |
338 | |
339 | |
340 <directive name="ssl_verify"> | |
341 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
342 <default>off</default> | |
343 <context>mgmt</context> | |
344 | |
345 <para> | |
346 Enables or disables verification of the Instance Manager certificate. | |
347 </para> | |
348 | |
349 </directive> | |
350 | |
351 | |
352 <directive name="ssl_verify_depth"> | |
353 <syntax><value>number</value></syntax> | |
354 <default>1</default> | |
355 <context>mgmt</context> | |
356 | |
357 <para> | |
358 Sets the verification depth in the Instance Manager certificates chain. | |
359 </para> | |
360 | |
361 </directive> | |
362 | |
363 | |
364 <directive name="usage_report"> | |
365 <syntax> [<literal>endpoint</literal>=<value>address</value>] | |
366 [<literal>interval</literal>=<value>time</value>]</syntax> | |
367 <default/> | |
368 <context>mgmt</context> | |
369 | |
370 <para> | |
371 Sets the <value>address</value> and <value>port</value> for IP, | |
372 or the <value>path</value> for a UNIX-domain socket on which | |
373 the Instance Manager is installed, | |
374 by default <literal>nginx-mgmt.local</literal>. | |
375 The <literal>interval</literal> sets an interval between reports | |
376 to the Instance Manager, by default 30m. | |
377 </para> | |
378 | |
379 </directive> | |
380 | |
381 | |
382 <directive name="uuid_file"> | |
383 <syntax><value>file</value></syntax> | |
384 <default>logs/uuid</default> | |
385 <context>mgmt</context> | |
386 | |
387 <para> | |
388 Specifies a <value>file</value> that keeps the ID of nginx instance. | |
389 </para> | |
390 | |
391 <para> | |
392 Examples: | |
393 <example> | |
394 state /var/lib/nginx/nginx.id; # path for Linux | |
395 state /var/db/nginx/nginx.id; # path for FreeBSD | |
396 </example> | |
397 </para> | |
398 | |
399 <para> | |
400 Changing the file content directly should be avoided. | |
401 </para> | |
402 | |
403 </directive> | |
404 | |
405 </section> | |
406 | |
407 </module> |