Mercurial > hg > nginx-site

comparison xml/en/docs/ngx_mgmt_module.xml @ 3029:27008cb3fb27

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 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>