Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_api_module.xml @ 2034:7e7edf832099
Added the generated ngx_http_api_module and separate target for it.
This avoids unnecessary build steps and dependencies. The separate
'genapi' target is added to regenerate the ngx_http_api_module from
yaml source. The generated file is not removed during 'clean' step.
author | Vladimir Homutov <vl@nginx.com> |
---|---|
date | Fri, 08 Sep 2017 13:58:41 +0300 |
parents | |
children | a810103f8a75 |
comparison
equal
deleted
inserted
replaced
2033:113a4c7cfeb0 | 2034:7e7edf832099 |
---|---|
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_http_api_module" | |
10 link="/en/docs/http/ngx_http_api_module.html" | |
11 lang="en" | |
12 rev="1"> | |
13 | |
14 <section id="summary"> | |
15 | |
16 <para> | |
17 The <literal>ngx_http_api_module</literal> module (1.13.3) provides REST API | |
18 for accessing various status information, | |
19 configuring upstream server groups on-the-fly, and managing | |
20 <link doc="ngx_http_keyval_module.xml">key-value pairs</link> | |
21 without the need of reconfiguring nginx. | |
22 </para> | |
23 | |
24 <para> | |
25 <note> | |
26 The module supersedes the | |
27 <link doc="ngx_http_status_module.xml">ngx_http_status_module</link> and | |
28 <link doc="ngx_http_upstream_conf_module.xml">ngx_http_upstream_conf_module</link> | |
29 modules. | |
30 </note> | |
31 </para> | |
32 | |
33 <para> | |
34 <note> | |
35 This module is available as part of our | |
36 <commercial_version>commercial subscription</commercial_version>. | |
37 </note> | |
38 </para> | |
39 | |
40 </section> | |
41 | |
42 | |
43 <section id="example" name="Example Configuration"> | |
44 | |
45 <para> | |
46 <example> | |
47 http { | |
48 upstream backend { | |
49 zone http_backend 64k; | |
50 | |
51 server backend1.example.com weight=5; | |
52 server backend2.example.com; | |
53 } | |
54 | |
55 proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m; | |
56 | |
57 server { | |
58 server_name backend.example.com; | |
59 | |
60 location / { | |
61 proxy_pass http://backend; | |
62 proxy_cache cache_backend; | |
63 | |
64 health_check; | |
65 } | |
66 | |
67 status_zone server_backend; | |
68 } | |
69 | |
70 keyval_zone zone=one:32k state=one.keyval; | |
71 keyval $arg_text $text zone=one; | |
72 | |
73 server { | |
74 listen 127.0.0.1; | |
75 | |
76 location /api { | |
77 <emphasis>api</emphasis> write=on; | |
78 allow 127.0.0.1; | |
79 deny all; | |
80 } | |
81 } | |
82 } | |
83 | |
84 stream { | |
85 upstream backend { | |
86 zone stream_backend 64k; | |
87 | |
88 server backend1.example.com:12345 weight=5; | |
89 server backend2.example.com:12345; | |
90 } | |
91 | |
92 server { | |
93 listen 127.0.0.1:12345; | |
94 proxy_pass backend; | |
95 status_zone server_backend; | |
96 health_check; | |
97 } | |
98 } | |
99 </example> | |
100 All API requests include a supported API version in the URI. | |
101 Examples of API requests with this configuration: | |
102 <example> | |
103 http://127.0.0.1/api/1/ | |
104 http://127.0.0.1/api/1/nginx | |
105 http://127.0.0.1/api/1/connections | |
106 http://127.0.0.1/api/1/http/requests | |
107 http://127.0.0.1/api/1/http/server_zones/server_backend | |
108 http://127.0.0.1/api/1/http/caches/cache_backend | |
109 http://127.0.0.1/api/1/http/upstreams/backend | |
110 http://127.0.0.1/api/1/http/upstreams/backend/servers/ | |
111 http://127.0.0.1/api/1/http/upstreams/backend/servers/1 | |
112 http://127.0.0.1/api/1/http/keyvals/one?key=arg1 | |
113 http://127.0.0.1/api/1/stream/ | |
114 http://127.0.0.1/api/1/stream/server_zones/server_backend | |
115 http://127.0.0.1/api/1/stream/upstreams/ | |
116 http://127.0.0.1/api/1/stream/upstreams/backend | |
117 http://127.0.0.1/api/1/stream/upstreams/backend/servers/1 | |
118 </example> | |
119 </para> | |
120 | |
121 </section> | |
122 | |
123 | |
124 <section id="directives" name="Directives"> | |
125 | |
126 <directive name="api"> | |
127 <syntax> | |
128 [<literal>write</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> | |
129 <default/> | |
130 <context>location</context> | |
131 | |
132 <para> | |
133 Turns on the REST API interface in the surrounding location. | |
134 Access to this location should be | |
135 <link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. | |
136 </para> | |
137 | |
138 <para> | |
139 The <literal>write</literal> parameter determines whether the API | |
140 is read-only or read-write. | |
141 By default, the API is read-only. | |
142 </para> | |
143 | |
144 <para> | |
145 All API requests should contain a supported API version in the URI. | |
146 If the request URI equals the location prefix, | |
147 the list of supported API versions is returned. | |
148 The current and the only API version is “<literal>1</literal>”. | |
149 </para> | |
150 | |
151 <para> | |
152 The optional “<literal>fields</literal>” argument in the request line | |
153 specifies which fields of the requested objects will be output: | |
154 <example> | |
155 http://127.0.0.1/api/1/nginx?fields=version,build | |
156 </example> | |
157 </para> | |
158 | |
159 </directive> | |
160 | |
161 </section> | |
162 <section id="endpoints" name="Endpoints"> | |
163 <para> | |
164 <list type="tag"> | |
165 <tag-name id="root" name="/"> | |
166 <literal>/</literal> | |
167 </tag-name> | |
168 <tag-desc> | |
169 <para>Supported methods:</para> | |
170 <list type="bullet" compact="yes"> | |
171 <listitem id="getAPIEndpoints"> | |
172 <literal>GET</literal> - Return list of root endpoints | |
173 | |
174 <para>Returns a list of root endpoints.</para> | |
175 <para> | |
176 Possible responses: | |
177 </para> | |
178 <list type="bullet"> | |
179 <listitem>200 - Success, returns an array of strings</listitem> | |
180 </list> | |
181 </listitem> | |
182 </list> | |
183 </tag-desc> | |
184 <tag-name id="nginx" name="/nginx"> | |
185 <literal>/nginx</literal> | |
186 </tag-name> | |
187 <tag-desc> | |
188 <para>Supported methods:</para> | |
189 <list type="bullet" compact="yes"> | |
190 <listitem id="getNginx"> | |
191 <literal>GET</literal> - Return status of nginx running instance | |
192 | |
193 <para>Returns nginx version, build name, address, | |
194 number of configuration reloads, IDs of master and worker processes.</para> | |
195 <para> | |
196 Request parameters: | |
197 <list type="tag"> | |
198 <tag-name><literal>fields</literal> | |
199 (<literal>string</literal>, optional)</tag-name> | |
200 <tag-desc> | |
201 Limits which fields of nginx running instance will be output.</tag-desc> | |
202 </list> | |
203 </para> | |
204 <para> | |
205 Possible responses: | |
206 </para> | |
207 <list type="bullet"> | |
208 <listitem>200 - Success, returns <link id="def_nginx_object">nginx</link></listitem> | |
209 </list> | |
210 </listitem> | |
211 </list> | |
212 </tag-desc> | |
213 <tag-name id="processes" name="/processes"> | |
214 <literal>/processes</literal> | |
215 </tag-name> | |
216 <tag-desc> | |
217 <para>Supported methods:</para> | |
218 <list type="bullet" compact="yes"> | |
219 <listitem id="getProcesses"> | |
220 <literal>GET</literal> - Return nginx processes status | |
221 | |
222 <para>Returns the number of abnormally terminated | |
223 and respawned child processes.</para> | |
224 <para> | |
225 Possible responses: | |
226 </para> | |
227 <list type="bullet"> | |
228 <listitem>200 - Success, returns <link id="def_nginx_processes">Processes</link></listitem> | |
229 </list> | |
230 </listitem> | |
231 <listitem id="deleteProcesses"> | |
232 <literal>DELETE</literal> - Reset nginx processes statistics | |
233 | |
234 <para>Resets counters of abnormally terminated and respawned | |
235 child processes.</para> | |
236 <para> | |
237 Possible responses: | |
238 </para> | |
239 <list type="bullet"> | |
240 <listitem>204 - Success</listitem> | |
241 </list> | |
242 </listitem> | |
243 </list> | |
244 </tag-desc> | |
245 <tag-name id="connections" name="/connections"> | |
246 <literal>/connections</literal> | |
247 </tag-name> | |
248 <tag-desc> | |
249 <para>Supported methods:</para> | |
250 <list type="bullet" compact="yes"> | |
251 <listitem id="getConnections"> | |
252 <literal>GET</literal> - Return client connections statistics | |
253 | |
254 <para>Returns statistics of client connections.</para> | |
255 <para> | |
256 Request parameters: | |
257 <list type="tag"> | |
258 <tag-name><literal>fields</literal> | |
259 (<literal>string</literal>, optional)</tag-name> | |
260 <tag-desc> | |
261 Limits which fields of the connections statistics will be output.</tag-desc> | |
262 </list> | |
263 </para> | |
264 <para> | |
265 Possible responses: | |
266 </para> | |
267 <list type="bullet"> | |
268 <listitem>200 - Success, returns <link id="def_nginx_connections">Connections</link></listitem> | |
269 </list> | |
270 </listitem> | |
271 <listitem id="deleteConnections"> | |
272 <literal>DELETE</literal> - Reset client connections statistics | |
273 | |
274 <para>Resets statistics of accepted and dropped | |
275 client connections.</para> | |
276 <para> | |
277 Possible responses: | |
278 </para> | |
279 <list type="bullet"> | |
280 <listitem>204 - Success</listitem> | |
281 </list> | |
282 </listitem> | |
283 </list> | |
284 </tag-desc> | |
285 <tag-name id="ssl" name="/ssl"> | |
286 <literal>/ssl</literal> | |
287 </tag-name> | |
288 <tag-desc> | |
289 <para>Supported methods:</para> | |
290 <list type="bullet" compact="yes"> | |
291 <listitem id="getSsl"> | |
292 <literal>GET</literal> - Return SSL statistics | |
293 | |
294 <para>Returns SSL statistics.</para> | |
295 <para> | |
296 Request parameters: | |
297 <list type="tag"> | |
298 <tag-name><literal>fields</literal> | |
299 (<literal>string</literal>, optional)</tag-name> | |
300 <tag-desc> | |
301 Limits which fields of SSL statistics will be output.</tag-desc> | |
302 </list> | |
303 </para> | |
304 <para> | |
305 Possible responses: | |
306 </para> | |
307 <list type="bullet"> | |
308 <listitem>200 - Success, returns <link id="def_nginx_ssl_object">SSL</link></listitem> | |
309 </list> | |
310 </listitem> | |
311 <listitem id="deleteSslStat"> | |
312 <literal>DELETE</literal> - Reset SSL statistics | |
313 | |
314 <para>Resets counters of SSL handshakes and session reuses.</para> | |
315 <para> | |
316 Possible responses: | |
317 </para> | |
318 <list type="bullet"> | |
319 <listitem>204 - Success</listitem> | |
320 </list> | |
321 </listitem> | |
322 </list> | |
323 </tag-desc> | |
324 <tag-name id="slabs_" name="/slabs/"> | |
325 <literal>/slabs/</literal> | |
326 </tag-name> | |
327 <tag-desc> | |
328 <para>Supported methods:</para> | |
329 <list type="bullet" compact="yes"> | |
330 <listitem id="getSlabs"> | |
331 <literal>GET</literal> - Return status of all slabs | |
332 | |
333 <para>Returns status of slabs | |
334 for each shared memory zone with slab allocator.</para> | |
335 <para> | |
336 Request parameters: | |
337 <list type="tag"> | |
338 <tag-name><literal>fields</literal> | |
339 (<literal>string</literal>, optional)</tag-name> | |
340 <tag-desc> | |
341 Limits which fields of slab zones will be output. | |
342 If the “<literal>fields</literal>” value is empty, | |
343 then only zone names are output.</tag-desc> | |
344 </list> | |
345 </para> | |
346 <para> | |
347 Possible responses: | |
348 </para> | |
349 <list type="bullet"> | |
350 <listitem>200 - Success, returns a collection of "<link id="def_nginx_slab_zone">Shared memory zone with slab allocator</link>" objects for all slabs </listitem> | |
351 </list> | |
352 </listitem> | |
353 </list> | |
354 </tag-desc> | |
355 <tag-name id="slabs_slab_zone_name" name="/slabs/{slabZoneName}"> | |
356 <literal>/slabs/{slabZoneName}</literal> | |
357 </tag-name> | |
358 <tag-desc> | |
359 Parameters common for all methods: | |
360 <list type="tag"> | |
361 <tag-name><literal>slabZoneName</literal> | |
362 (<literal>string</literal>, required)</tag-name> | |
363 <tag-desc> | |
364 The name of the shared memory zone with slab allocator.</tag-desc> | |
365 </list> | |
366 <para>Supported methods:</para> | |
367 <list type="bullet" compact="yes"> | |
368 <listitem id="getSlabZone"> | |
369 <literal>GET</literal> - Return status of a slab | |
370 | |
371 <para>Returns status of slabs for a particular shared memory zone | |
372 with slab allocator.</para> | |
373 <para> | |
374 Request parameters: | |
375 <list type="tag"> | |
376 <tag-name><literal>fields</literal> | |
377 (<literal>string</literal>, optional)</tag-name> | |
378 <tag-desc> | |
379 Limits which fields of the slab zone will be output.</tag-desc> | |
380 </list> | |
381 </para> | |
382 <para> | |
383 Possible responses: | |
384 </para> | |
385 <list type="bullet"> | |
386 <listitem>200 - Success, returns <link id="def_nginx_slab_zone">Shared memory zone with slab allocator</link></listitem> | |
387 <listitem>404 - Slab not found (<literal>SlabNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
388 </list> | |
389 </listitem> | |
390 <listitem id="deleteSlabZoneStats"> | |
391 <literal>DELETE</literal> - Reset slab statistics | |
392 | |
393 <para>Resets the “<literal>reqs</literal>” and “<literal>fails</literal>” | |
394 metrics for each memory slot.</para> | |
395 <para> | |
396 Possible responses: | |
397 </para> | |
398 <list type="bullet"> | |
399 <listitem>204 - Success</listitem> | |
400 <listitem>404 - Slab not found (<literal>SlabNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
401 </list> | |
402 </listitem> | |
403 </list> | |
404 </tag-desc> | |
405 <tag-name id="http_" name="/http/"> | |
406 <literal>/http/</literal> | |
407 </tag-name> | |
408 <tag-desc> | |
409 <para>Supported methods:</para> | |
410 <list type="bullet" compact="yes"> | |
411 <listitem id="getHttp"> | |
412 <literal>GET</literal> - Return list of HTTP-related endpoints | |
413 | |
414 <para>Returns a list of first level HTTP endpoints.</para> | |
415 <para> | |
416 Possible responses: | |
417 </para> | |
418 <list type="bullet"> | |
419 <listitem>200 - Success, returns an array of strings</listitem> | |
420 </list> | |
421 </listitem> | |
422 </list> | |
423 </tag-desc> | |
424 <tag-name id="http_requests" name="/http/requests"> | |
425 <literal>/http/requests</literal> | |
426 </tag-name> | |
427 <tag-desc> | |
428 <para>Supported methods:</para> | |
429 <list type="bullet" compact="yes"> | |
430 <listitem id="getHttpRequests"> | |
431 <literal>GET</literal> - Return HTTP requests statistics | |
432 | |
433 <para>Returns status of client HTTP requests.</para> | |
434 <para> | |
435 Request parameters: | |
436 <list type="tag"> | |
437 <tag-name><literal>fields</literal> | |
438 (<literal>string</literal>, optional)</tag-name> | |
439 <tag-desc> | |
440 Limits which fields of client HTTP requests statistics | |
441 will be output.</tag-desc> | |
442 </list> | |
443 </para> | |
444 <para> | |
445 Possible responses: | |
446 </para> | |
447 <list type="bullet"> | |
448 <listitem>200 - Success, returns <link id="def_nginx_http_requests">HTTP Requests</link></listitem> | |
449 </list> | |
450 </listitem> | |
451 <listitem id="deleteHttpRequests"> | |
452 <literal>DELETE</literal> - Reset HTTP requests statistics | |
453 | |
454 <para>Resets the number of total client HTTP requests.</para> | |
455 <para> | |
456 Possible responses: | |
457 </para> | |
458 <list type="bullet"> | |
459 <listitem>204 - Success</listitem> | |
460 </list> | |
461 </listitem> | |
462 </list> | |
463 </tag-desc> | |
464 <tag-name id="http_server_zones_" name="/http/server_zones/"> | |
465 <literal>/http/server_zones/</literal> | |
466 </tag-name> | |
467 <tag-desc> | |
468 <para>Supported methods:</para> | |
469 <list type="bullet" compact="yes"> | |
470 <listitem id="getHttpServerZones"> | |
471 <literal>GET</literal> - Return status of all HTTP server zones | |
472 | |
473 <para>Returns status information for each HTTP | |
474 <link url="https://nginx.org/en/docs/http/ngx_http_status_module.html#status_zone">server zone</link>.</para> | |
475 <para> | |
476 Request parameters: | |
477 <list type="tag"> | |
478 <tag-name><literal>fields</literal> | |
479 (<literal>string</literal>, optional)</tag-name> | |
480 <tag-desc> | |
481 Limits which fields of server zones will be output. | |
482 If the “<literal>fields</literal>” value is empty, | |
483 then only server zone names are output.</tag-desc> | |
484 </list> | |
485 </para> | |
486 <para> | |
487 Possible responses: | |
488 </para> | |
489 <list type="bullet"> | |
490 <listitem>200 - Success, returns a collection of "<link id="def_nginx_http_server_zone">HTTP Server Zone</link>" objects for all http server zones </listitem> | |
491 </list> | |
492 </listitem> | |
493 </list> | |
494 </tag-desc> | |
495 <tag-name id="http_server_zones_http_server_zone_name" name="/http/server_zones/{httpServerZoneName}"> | |
496 <literal>/http/server_zones/{httpServerZoneName}</literal> | |
497 </tag-name> | |
498 <tag-desc> | |
499 Parameters common for all methods: | |
500 <list type="tag"> | |
501 <tag-name><literal>httpServerZoneName</literal> | |
502 (<literal>string</literal>, required)</tag-name> | |
503 <tag-desc> | |
504 The name of an HTTP server zone.</tag-desc> | |
505 </list> | |
506 <para>Supported methods:</para> | |
507 <list type="bullet" compact="yes"> | |
508 <listitem id="getHttpServerZone"> | |
509 <literal>GET</literal> - Return status of an HTTP server zone | |
510 | |
511 <para>Returns status of a particular HTTP server zone.</para> | |
512 <para> | |
513 Request parameters: | |
514 <list type="tag"> | |
515 <tag-name><literal>fields</literal> | |
516 (<literal>string</literal>, optional)</tag-name> | |
517 <tag-desc> | |
518 Limits which fields of the server zone will be output.</tag-desc> | |
519 </list> | |
520 </para> | |
521 <para> | |
522 Possible responses: | |
523 </para> | |
524 <list type="bullet"> | |
525 <listitem>200 - Success, returns <link id="def_nginx_http_server_zone">HTTP Server Zone</link></listitem> | |
526 <listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
527 </list> | |
528 </listitem> | |
529 <listitem id="deleteHttpServerZoneStat"> | |
530 <literal>DELETE</literal> - Reset statistics for an HTTP server zone | |
531 | |
532 <para>Resets statistics of accepted and discarded requests, responses, | |
533 received and sent bytes in a particular HTTP server zone.</para> | |
534 <para> | |
535 Possible responses: | |
536 </para> | |
537 <list type="bullet"> | |
538 <listitem>204 - Success</listitem> | |
539 <listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
540 </list> | |
541 </listitem> | |
542 </list> | |
543 </tag-desc> | |
544 <tag-name id="http_caches_" name="/http/caches/"> | |
545 <literal>/http/caches/</literal> | |
546 </tag-name> | |
547 <tag-desc> | |
548 <para>Supported methods:</para> | |
549 <list type="bullet" compact="yes"> | |
550 <listitem id="getHttpCaches"> | |
551 <literal>GET</literal> - Return status of all caches | |
552 | |
553 <para>Returns status of each cache configured by | |
554 <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path">proxy_cache_path</link> | |
555 and other “<literal>*_cache_path</literal>” directives.</para> | |
556 <para> | |
557 Request parameters: | |
558 <list type="tag"> | |
559 <tag-name><literal>fields</literal> | |
560 (<literal>string</literal>, optional)</tag-name> | |
561 <tag-desc> | |
562 Limits which fields of cache zones will be output. | |
563 If the “<literal>fields</literal>” value is empty, | |
564 then only names of cache zones are output.</tag-desc> | |
565 </list> | |
566 </para> | |
567 <para> | |
568 Possible responses: | |
569 </para> | |
570 <list type="bullet"> | |
571 <listitem>200 - Success, returns a collection of "<link id="def_nginx_http_cache">HTTP Cache</link>" objects for all http caches </listitem> | |
572 </list> | |
573 </listitem> | |
574 </list> | |
575 </tag-desc> | |
576 <tag-name id="http_caches_http_cache_zone_name" name="/http/caches/{httpCacheZoneName}"> | |
577 <literal>/http/caches/{httpCacheZoneName}</literal> | |
578 </tag-name> | |
579 <tag-desc> | |
580 Parameters common for all methods: | |
581 <list type="tag"> | |
582 <tag-name><literal>httpCacheZoneName</literal> | |
583 (<literal>string</literal>, required)</tag-name> | |
584 <tag-desc> | |
585 The name of the cache zone.</tag-desc> | |
586 </list> | |
587 <para>Supported methods:</para> | |
588 <list type="bullet" compact="yes"> | |
589 <listitem id="getHttpCacheZone"> | |
590 <literal>GET</literal> - Return status of a cache | |
591 | |
592 <para>Returns status of a particular cache.</para> | |
593 <para> | |
594 Request parameters: | |
595 <list type="tag"> | |
596 <tag-name><literal>fields</literal> | |
597 (<literal>string</literal>, optional)</tag-name> | |
598 <tag-desc> | |
599 Limits which fields of the cache zone will be output.</tag-desc> | |
600 </list> | |
601 </para> | |
602 <para> | |
603 Possible responses: | |
604 </para> | |
605 <list type="bullet"> | |
606 <listitem>200 - Success, returns <link id="def_nginx_http_cache">HTTP Cache</link></listitem> | |
607 <listitem>404 - Cache not found (<literal>CacheNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
608 </list> | |
609 </listitem> | |
610 <listitem id="deleteHttpCacheZoneStat"> | |
611 <literal>DELETE</literal> - Reset cache statistics | |
612 | |
613 <para>Resets statistics of cache hits/misses in a particular cache zone.</para> | |
614 <para> | |
615 Possible responses: | |
616 </para> | |
617 <list type="bullet"> | |
618 <listitem>204 - Success</listitem> | |
619 <listitem>404 - Cache not found (<literal>CacheNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
620 </list> | |
621 </listitem> | |
622 </list> | |
623 </tag-desc> | |
624 <tag-name id="http_upstreams_" name="/http/upstreams/"> | |
625 <literal>/http/upstreams/</literal> | |
626 </tag-name> | |
627 <tag-desc> | |
628 <para>Supported methods:</para> | |
629 <list type="bullet" compact="yes"> | |
630 <listitem id="getHttpUpstreams"> | |
631 <literal>GET</literal> - Return status of all HTTP upstream server groups | |
632 | |
633 <para>Returns status of each HTTP upstream server group | |
634 and its servers.</para> | |
635 <para> | |
636 Request parameters: | |
637 <list type="tag"> | |
638 <tag-name><literal>fields</literal> | |
639 (<literal>string</literal>, optional)</tag-name> | |
640 <tag-desc> | |
641 Limits which fields of upstream server groups will be output. | |
642 If the “<literal>fields</literal>” value is empty, | |
643 only names of upstreams are output.</tag-desc> | |
644 </list> | |
645 </para> | |
646 <para> | |
647 Possible responses: | |
648 </para> | |
649 <list type="bullet"> | |
650 <listitem>200 - Success, returns a collection of "<link id="def_nginx_http_upstream">HTTP Upstream</link>" objects for all http upstreams </listitem> | |
651 </list> | |
652 </listitem> | |
653 </list> | |
654 </tag-desc> | |
655 <tag-name id="http_upstreams_http_upstream_name_" name="/http/upstreams/{httpUpstreamName}/"> | |
656 <literal>/http/upstreams/{httpUpstreamName}/</literal> | |
657 </tag-name> | |
658 <tag-desc> | |
659 Parameters common for all methods: | |
660 <list type="tag"> | |
661 <tag-name><literal>httpUpstreamName</literal> | |
662 (<literal>string</literal>, required)</tag-name> | |
663 <tag-desc> | |
664 The name of an HTTP upstream server group.</tag-desc> | |
665 </list> | |
666 <para>Supported methods:</para> | |
667 <list type="bullet" compact="yes"> | |
668 <listitem id="getHttpUpstreamName"> | |
669 <literal>GET</literal> - Return status of an HTTP upstream server group | |
670 | |
671 <para>Returns status of a particular HTTP upstream server group | |
672 and its servers.</para> | |
673 <para> | |
674 Request parameters: | |
675 <list type="tag"> | |
676 <tag-name><literal>fields</literal> | |
677 (<literal>string</literal>, optional)</tag-name> | |
678 <tag-desc> | |
679 Limits which fields of the upstream server group will be output.</tag-desc> | |
680 </list> | |
681 </para> | |
682 <para> | |
683 Possible responses: | |
684 </para> | |
685 <list type="bullet"> | |
686 <listitem>200 - Success, returns <link id="def_nginx_http_upstream">HTTP Upstream</link></listitem> | |
687 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
688 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
689 </list> | |
690 </listitem> | |
691 <listitem id="deleteHttpUpstreamStat"> | |
692 <literal>DELETE</literal> - Reset statistics of an HTTP upstream server group | |
693 | |
694 <para>Resets the statistics for each upstream server | |
695 in an upstream server group and queue statistics.</para> | |
696 <para> | |
697 Possible responses: | |
698 </para> | |
699 <list type="bullet"> | |
700 <listitem>204 - Success</listitem> | |
701 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
702 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
703 </list> | |
704 </listitem> | |
705 </list> | |
706 </tag-desc> | |
707 <tag-name id="http_upstreams_http_upstream_name_servers_" name="/http/upstreams/{httpUpstreamName}/servers/"> | |
708 <literal>/http/upstreams/{httpUpstreamName}/servers/</literal> | |
709 </tag-name> | |
710 <tag-desc> | |
711 Parameters common for all methods: | |
712 <list type="tag"> | |
713 <tag-name><literal>httpUpstreamName</literal> | |
714 (<literal>string</literal>, required)</tag-name> | |
715 <tag-desc> | |
716 The name of an upstream server group.</tag-desc> | |
717 </list> | |
718 <para>Supported methods:</para> | |
719 <list type="bullet" compact="yes"> | |
720 <listitem id="getHttpUpstreamServers"> | |
721 <literal>GET</literal> - Return configuration of all servers in an HTTP upstream server group | |
722 | |
723 <para>Returns configuration of each server | |
724 in a particular HTTP upstream server group.</para> | |
725 <para> | |
726 Possible responses: | |
727 </para> | |
728 <list type="bullet"> | |
729 <listitem>200 - Success, returns an array of <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Servers</link></listitem> | |
730 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
731 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
732 </list> | |
733 </listitem> | |
734 <listitem id="postHttpUpstreamServer"> | |
735 <literal>POST</literal> - Add a server to an HTTP upstream server group | |
736 | |
737 <para>Adds a new server to an HTTP upstream server group. | |
738 Server parameters are specified in the JSON format.</para> | |
739 <para> | |
740 Request parameters: | |
741 <list type="tag"> | |
742 <tag-name><literal>postHttpUpstreamServer</literal> | |
743 (<link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link>, required)</tag-name> | |
744 <tag-desc> | |
745 Address of a new server and other optional parameters | |
746 in the JSON format. | |
747 The “<literal>ID</literal>”, “<literal>backup</literal>”, and “<literal>service</literal>” parameters | |
748 cannot be changed.</tag-desc> | |
749 </list> | |
750 </para> | |
751 <para> | |
752 Possible responses: | |
753 </para> | |
754 <list type="bullet"> | |
755 <listitem>201 - Created, returns <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link></listitem> | |
756 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), | |
757 invalid “<value>parameter</value>” value (<literal>UpstreamConfFormatError</literal>), | |
758 missing “<literal>server</literal>” argument (<literal>UpstreamConfFormatError</literal>), | |
759 unknown parameter “<value>name</value>” (<literal>UpstreamConfFormatError</literal>), | |
760 nested object or list (<literal>UpstreamConfFormatError</literal>), | |
761 “<literal>error</literal>” while parsing (<literal>UpstreamBadAddress</literal>), | |
762 service upstream “<literal>host</literal>” may not have port (<literal>UpstreamBadAddress</literal>), | |
763 service upstream “<literal>host</literal>” requires domain name (<literal>UpstreamBadAddress</literal>), | |
764 invalid “<literal>weight</literal>” (<literal>UpstreamBadWeight</literal>), | |
765 invalid “<literal>max_conns</literal>” (<literal>UpstreamBadMaxConns</literal>), | |
766 invalid “<literal>max_fails</literal>” (<literal>UpstreamBadMaxFails</literal>), | |
767 invalid “<literal>fail_timeout</literal>” (<literal>UpstreamBadFailTimeout</literal>), | |
768 invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>), | |
769 route is too long (<literal>UpstreamBadRoute</literal>), | |
770 “<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>), | |
771 no resolver defined to resolve (<literal>UpstreamConfNoResolver</literal>), | |
772 upstream “<value>name</value>” has no backup (<literal>UpstreamNoBackup</literal>), | |
773 upstream “<value>name</value>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
774 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
775 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
776 </list> | |
777 </listitem> | |
778 </list> | |
779 </tag-desc> | |
780 <tag-name id="http_upstreams_http_upstream_name_servers_http_upstream_server_id" name="/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId}"> | |
781 <literal>/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId}</literal> | |
782 </tag-name> | |
783 <tag-desc> | |
784 Parameters common for all methods: | |
785 <list type="tag"> | |
786 <tag-name><literal>httpUpstreamName</literal> | |
787 (<literal>string</literal>, required)</tag-name> | |
788 <tag-desc> | |
789 The name of the upstream server group.</tag-desc> | |
790 <tag-name><literal>httpUpstreamServerId</literal> | |
791 (<literal>string</literal>, required)</tag-name> | |
792 <tag-desc> | |
793 The ID of the server.</tag-desc> | |
794 </list> | |
795 <para>Supported methods:</para> | |
796 <list type="bullet" compact="yes"> | |
797 <listitem id="getHttpUpstreamPeer"> | |
798 <literal>GET</literal> - Return configuration of a server in an HTTP upstream server group | |
799 | |
800 <para>Returns configuration of a particular server | |
801 in the HTTP upstream server group.</para> | |
802 <para> | |
803 Possible responses: | |
804 </para> | |
805 <list type="bullet"> | |
806 <listitem>200 - Success, returns <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link></listitem> | |
807 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), | |
808 invalid server ID (<literal>UpstreamBadServerId</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
809 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | |
810 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
811 </list> | |
812 </listitem> | |
813 <listitem id="patchHttpUpstreamPeer"> | |
814 <literal>PATCH</literal> - Modify a server in an HTTP upstream server group | |
815 | |
816 <para>Modifies settings of a particular server | |
817 in an HTTP upstream server group. | |
818 Server parameters are specified in the JSON format.</para> | |
819 <para> | |
820 Request parameters: | |
821 <list type="tag"> | |
822 <tag-name><literal>patchHttpUpstreamServer</literal> | |
823 (<link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link>, required)</tag-name> | |
824 <tag-desc> | |
825 Server parameters, specified in the JSON format. | |
826 The “<literal>ID</literal>”, “<literal>backup</literal>”, and “<literal>service</literal>” parameters | |
827 cannot be changed.</tag-desc> | |
828 </list> | |
829 </para> | |
830 <para> | |
831 Possible responses: | |
832 </para> | |
833 <list type="bullet"> | |
834 <listitem>200 - Success, returns <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link></listitem> | |
835 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), | |
836 invalid “<value>parameter</value>” value (<literal>UpstreamConfFormatError</literal>), | |
837 unknown parameter “<value>name</value>” (<literal>UpstreamConfFormatError</literal>), | |
838 nested object or list (<literal>UpstreamConfFormatError</literal>), | |
839 “<literal>error</literal>” while parsing (<literal>UpstreamBadAddress</literal>), | |
840 invalid “<literal>server</literal>” argument (<literal>UpstreamBadAddress</literal>), | |
841 invalid server ID (<literal>UpstreamBadServerId</literal>), | |
842 invalid “<literal>weight</literal>” (<literal>UpstreamBadWeight</literal>), | |
843 invalid “<literal>max_conns</literal>” (<literal>UpstreamBadMaxConns</literal>), | |
844 invalid “<literal>max_fails</literal>” (<literal>UpstreamBadMaxFails</literal>), | |
845 invalid “<literal>fail_timeout</literal>” (<literal>UpstreamBadFailTimeout</literal>), | |
846 invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>), | |
847 route is too long (<literal>UpstreamBadRoute</literal>), | |
848 “<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>), | |
849 server “<value>ID</value>” address is immutable (<literal>UpstreamServerImmutable</literal>), | |
850 server “<literal>ID</literal>” weight is immutable (<literal>UpstreamServerWeightImmutable</literal>), | |
851 upstream “<literal>name</literal>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
852 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | |
853 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
854 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
855 </list> | |
856 </listitem> | |
857 <listitem id="deleteHttpUpstreamServer"> | |
858 <literal>DELETE</literal> - Remove a server from an HTTP upstream server group | |
859 | |
860 <para>Removes a server from an HTTP upstream server group.</para> | |
861 <para> | |
862 Possible responses: | |
863 </para> | |
864 <list type="bullet"> | |
865 <listitem>200 - Success, returns an array of <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Servers</link></listitem> | |
866 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), | |
867 invalid server ID (<literal>UpstreamBadServerId</literal>), | |
868 server “<value>id</value>” not removable (<literal>UpstreamServerImmutable</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
869 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | |
870 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
871 </list> | |
872 </listitem> | |
873 </list> | |
874 </tag-desc> | |
875 <tag-name id="http_keyvals_" name="/http/keyvals/"> | |
876 <literal>/http/keyvals/</literal> | |
877 </tag-name> | |
878 <tag-desc> | |
879 <para>Supported methods:</para> | |
880 <list type="bullet" compact="yes"> | |
881 <listitem id="getHttpKeyvalZones"> | |
882 <literal>GET</literal> - Return key-value pairs from all keyval zones | |
883 | |
884 <para>Returns key-value pairs for each keyval shared memory | |
885 <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para> | |
886 <para> | |
887 Request parameters: | |
888 <list type="tag"> | |
889 <tag-name><literal>fields</literal> | |
890 (<literal>string</literal>, optional)</tag-name> | |
891 <tag-desc> | |
892 If the “<literal>fields</literal>” value is empty, | |
893 then only keyval zone names are output.</tag-desc> | |
894 </list> | |
895 </para> | |
896 <para> | |
897 Possible responses: | |
898 </para> | |
899 <list type="bullet"> | |
900 <listitem>200 - Success, returns a collection of "<link id="def_nginx_http_keyval_zone">Keyval Shared Memory Zone</link>" objects for all http keyvals </listitem> | |
901 </list> | |
902 </listitem> | |
903 </list> | |
904 </tag-desc> | |
905 <tag-name id="http_keyvals_http_keyval_zone_name" name="/http/keyvals/{httpKeyvalZoneName}"> | |
906 <literal>/http/keyvals/{httpKeyvalZoneName}</literal> | |
907 </tag-name> | |
908 <tag-desc> | |
909 Parameters common for all methods: | |
910 <list type="tag"> | |
911 <tag-name><literal>httpKeyvalZoneName</literal> | |
912 (<literal>string</literal>, required)</tag-name> | |
913 <tag-desc> | |
914 The name of a keyval shared memory zone.</tag-desc> | |
915 </list> | |
916 <para>Supported methods:</para> | |
917 <list type="bullet" compact="yes"> | |
918 <listitem id="getHttpKeyvalZoneKeysValues"> | |
919 <literal>GET</literal> - Return key-value pairs from a keyval zone | |
920 | |
921 <para>Returns key-value pairs stored in a particular keyval shared memory | |
922 <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para> | |
923 <para> | |
924 Request parameters: | |
925 <list type="tag"> | |
926 <tag-name><literal>key</literal> | |
927 (<literal>string</literal>, optional)</tag-name> | |
928 <tag-desc> | |
929 Get a particular key-value pair from the keyval zone.</tag-desc> | |
930 </list> | |
931 </para> | |
932 <para> | |
933 Possible responses: | |
934 </para> | |
935 <list type="bullet"> | |
936 <listitem>200 - Success, returns <link id="def_nginx_http_keyval_zone">Keyval Shared Memory Zone</link></listitem> | |
937 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), | |
938 keyval key not found (<literal>KeyvalKeyNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
939 </list> | |
940 </listitem> | |
941 <listitem id="postHttpKeyvalZoneData"> | |
942 <literal>POST</literal> - Add a key-value pair to the keyval zone | |
943 | |
944 <para>Adds a new key-value pair to the keyval shared memory | |
945 <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>. | |
946 Several key-value pairs can be entered | |
947 if the keyval shared memory zone is empty.</para> | |
948 <para> | |
949 Request parameters: | |
950 <list type="tag"> | |
951 <tag-name><literal>Key-value</literal> | |
952 (<link id="def_nginx_http_keyval_zone">Keyval Shared Memory Zone</link>, required)</tag-name> | |
953 <tag-desc> | |
954 A key-value pair is specified in the JSON format. | |
955 Several key-value pairs can be entered | |
956 if the keyval shared memory zone is empty.</tag-desc> | |
957 </list> | |
958 </para> | |
959 <para> | |
960 Possible responses: | |
961 </para> | |
962 <list type="bullet"> | |
963 <listitem>201 - Created</listitem> | |
964 <listitem>400 - Key required (<literal>KeyvalFormatError</literal>), | |
965 only one key can be added (<literal>KeyvalFormatError</literal>), | |
966 nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
967 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
968 <listitem>409 - Key already exists (<literal>KeyvalKeyExists</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
969 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
970 </list> | |
971 </listitem> | |
972 <listitem id="patchHttpKeyvalZoneKeyValue"> | |
973 <literal>PATCH</literal> - Modify a key-value or delete a key | |
974 | |
975 <para>Changes the value of the selected key in the key-value pair | |
976 or deletes a key by setting the key value to <literal>null</literal>.</para> | |
977 <para> | |
978 Request parameters: | |
979 <list type="tag"> | |
980 <tag-name><literal>httpKeyvalZoneKeyValue</literal> | |
981 (<link id="def_nginx_http_keyval_zone">Keyval Shared Memory Zone</link>, required)</tag-name> | |
982 <tag-desc> | |
983 A new value for the key is specified in the JSON format.</tag-desc> | |
984 </list> | |
985 </para> | |
986 <para> | |
987 Possible responses: | |
988 </para> | |
989 <list type="bullet"> | |
990 <listitem>204 - Success</listitem> | |
991 <listitem>400 - Key required (<literal>KeyvalFormatError</literal>), | |
992 only one key can be updated (<literal>KeyvalFormatError</literal>), | |
993 nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
994 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), | |
995 keyval key not found (<literal>KeyvalKeyNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
996 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
997 </list> | |
998 </listitem> | |
999 <listitem id="deleteHttpKeyvalZoneData"> | |
1000 <literal>DELETE</literal> - Empty the keyval zone | |
1001 | |
1002 <para>Deletes all key-value pairs from the keyval shared memory | |
1003 <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para> | |
1004 <para> | |
1005 Possible responses: | |
1006 </para> | |
1007 <list type="bullet"> | |
1008 <listitem>204 - Success</listitem> | |
1009 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1010 </list> | |
1011 </listitem> | |
1012 </list> | |
1013 </tag-desc> | |
1014 <tag-name id="stream_" name="/stream/"> | |
1015 <literal>/stream/</literal> | |
1016 </tag-name> | |
1017 <tag-desc> | |
1018 <para>Supported methods:</para> | |
1019 <list type="bullet" compact="yes"> | |
1020 <listitem id="getStream"> | |
1021 <literal>GET</literal> - Return list of stream-related endpoints | |
1022 | |
1023 <para>Returns a list of first level stream endpoints.</para> | |
1024 <para> | |
1025 Possible responses: | |
1026 </para> | |
1027 <list type="bullet"> | |
1028 <listitem>200 - Success, returns an array of strings</listitem> | |
1029 </list> | |
1030 </listitem> | |
1031 </list> | |
1032 </tag-desc> | |
1033 <tag-name id="stream_server_zones_" name="/stream/server_zones/"> | |
1034 <literal>/stream/server_zones/</literal> | |
1035 </tag-name> | |
1036 <tag-desc> | |
1037 <para>Supported methods:</para> | |
1038 <list type="bullet" compact="yes"> | |
1039 <listitem id="getStreamServerZones"> | |
1040 <literal>GET</literal> - Return status of all stream server zones | |
1041 | |
1042 <para>Returns status information for each stream | |
1043 <link url="https://nginx.org/en/docs/http/ngx_http_status_module.html#status_zone">server zone</link>.</para> | |
1044 <para> | |
1045 Request parameters: | |
1046 <list type="tag"> | |
1047 <tag-name><literal>fields</literal> | |
1048 (<literal>string</literal>, optional)</tag-name> | |
1049 <tag-desc> | |
1050 Limits which fields of server zones will be output. | |
1051 If the “<literal>fields</literal>” value is empty, | |
1052 then only server zone names are output.</tag-desc> | |
1053 </list> | |
1054 </para> | |
1055 <para> | |
1056 Possible responses: | |
1057 </para> | |
1058 <list type="bullet"> | |
1059 <listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_server_zone">Stream Server Zone</link>" objects for all stream server zones </listitem> | |
1060 <listitem>404 - <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> | |
1061 not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1062 </list> | |
1063 </listitem> | |
1064 </list> | |
1065 </tag-desc> | |
1066 <tag-name id="stream_server_zones_stream_server_zone_name" name="/stream/server_zones/{streamServerZoneName}"> | |
1067 <literal>/stream/server_zones/{streamServerZoneName}</literal> | |
1068 </tag-name> | |
1069 <tag-desc> | |
1070 Parameters common for all methods: | |
1071 <list type="tag"> | |
1072 <tag-name><literal>streamServerZoneName</literal> | |
1073 (<literal>string</literal>, required)</tag-name> | |
1074 <tag-desc> | |
1075 The name of a stream server zone.</tag-desc> | |
1076 </list> | |
1077 <para>Supported methods:</para> | |
1078 <list type="bullet" compact="yes"> | |
1079 <listitem id="getStreamServerZone"> | |
1080 <literal>GET</literal> - Return status of a stream server zone | |
1081 | |
1082 <para>Returns status of a particular stream server zone.</para> | |
1083 <para> | |
1084 Request parameters: | |
1085 <list type="tag"> | |
1086 <tag-name><literal>fields</literal> | |
1087 (<literal>string</literal>, optional)</tag-name> | |
1088 <tag-desc> | |
1089 Limits which fields of the server zone will be output.</tag-desc> | |
1090 </list> | |
1091 </para> | |
1092 <para> | |
1093 Possible responses: | |
1094 </para> | |
1095 <list type="bullet"> | |
1096 <listitem>200 - Success, returns <link id="def_nginx_stream_server_zone">Stream Server Zone</link></listitem> | |
1097 <listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), | |
1098 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> | |
1099 not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1100 </list> | |
1101 </listitem> | |
1102 <listitem id="deleteStreamServerZoneStat"> | |
1103 <literal>DELETE</literal> - Reset statistics for a stream server zone | |
1104 | |
1105 <para>Resets statistics of accepted and discarded connections, sessions, | |
1106 received and sent bytes in a particular stream server zone.</para> | |
1107 <para> | |
1108 Possible responses: | |
1109 </para> | |
1110 <list type="bullet"> | |
1111 <listitem>204 - Success</listitem> | |
1112 <listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), | |
1113 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> | |
1114 not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1115 </list> | |
1116 </listitem> | |
1117 </list> | |
1118 </tag-desc> | |
1119 <tag-name id="stream_upstreams_" name="/stream/upstreams/"> | |
1120 <literal>/stream/upstreams/</literal> | |
1121 </tag-name> | |
1122 <tag-desc> | |
1123 <para>Supported methods:</para> | |
1124 <list type="bullet" compact="yes"> | |
1125 <listitem id="getStreamUpstreams"> | |
1126 <literal>GET</literal> - Return status of all stream upstream server groups | |
1127 | |
1128 <para>Returns status of each stream upstream server group | |
1129 and its servers.</para> | |
1130 <para> | |
1131 Request parameters: | |
1132 <list type="tag"> | |
1133 <tag-name><literal>fields</literal> | |
1134 (<literal>string</literal>, optional)</tag-name> | |
1135 <tag-desc> | |
1136 Limits which fields of upstream server groups will be output. | |
1137 If the “<literal>fields</literal>” value is empty, | |
1138 only names of upstreams are output.</tag-desc> | |
1139 </list> | |
1140 </para> | |
1141 <para> | |
1142 Possible responses: | |
1143 </para> | |
1144 <list type="bullet"> | |
1145 <listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_upstream">Stream Upstream</link>" objects for all stream upstreams </listitem> | |
1146 <listitem>404 - <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> | |
1147 not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1148 </list> | |
1149 </listitem> | |
1150 </list> | |
1151 </tag-desc> | |
1152 <tag-name id="stream_upstreams_stream_upstream_name_" name="/stream/upstreams/{streamUpstreamName}/"> | |
1153 <literal>/stream/upstreams/{streamUpstreamName}/</literal> | |
1154 </tag-name> | |
1155 <tag-desc> | |
1156 Parameters common for all methods: | |
1157 <list type="tag"> | |
1158 <tag-name><literal>streamUpstreamName</literal> | |
1159 (<literal>string</literal>, required)</tag-name> | |
1160 <tag-desc> | |
1161 The name of a stream upstream server group.</tag-desc> | |
1162 </list> | |
1163 <para>Supported methods:</para> | |
1164 <list type="bullet" compact="yes"> | |
1165 <listitem id="getStreamUpstream"> | |
1166 <literal>GET</literal> - Return status of a stream upstream server group | |
1167 | |
1168 <para>Returns status of a particular stream upstream server group | |
1169 and its servers.</para> | |
1170 <para> | |
1171 Request parameters: | |
1172 <list type="tag"> | |
1173 <tag-name><literal>fields</literal> | |
1174 (<literal>string</literal>, optional)</tag-name> | |
1175 <tag-desc> | |
1176 Limits which fields of the upstream server group will be output.</tag-desc> | |
1177 </list> | |
1178 </para> | |
1179 <para> | |
1180 Possible responses: | |
1181 </para> | |
1182 <list type="bullet"> | |
1183 <listitem>200 - Success, returns <link id="def_nginx_stream_upstream">Stream Upstream</link></listitem> | |
1184 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1185 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | |
1186 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> | |
1187 not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1188 </list> | |
1189 </listitem> | |
1190 <listitem id="deleteStreamUpstreamStat"> | |
1191 <literal>DELETE</literal> - Reset statistics of a stream upstream server group | |
1192 | |
1193 <para>Resets the statistics for each upstream server | |
1194 in an upstream server group.</para> | |
1195 <para> | |
1196 Possible responses: | |
1197 </para> | |
1198 <list type="bullet"> | |
1199 <listitem>204 - Success</listitem> | |
1200 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1201 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | |
1202 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> | |
1203 not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1204 </list> | |
1205 </listitem> | |
1206 </list> | |
1207 </tag-desc> | |
1208 <tag-name id="stream_upstreams_stream_upstream_name_servers_" name="/stream/upstreams/{streamUpstreamName}/servers/"> | |
1209 <literal>/stream/upstreams/{streamUpstreamName}/servers/</literal> | |
1210 </tag-name> | |
1211 <tag-desc> | |
1212 Parameters common for all methods: | |
1213 <list type="tag"> | |
1214 <tag-name><literal>streamUpstreamName</literal> | |
1215 (<literal>string</literal>, required)</tag-name> | |
1216 <tag-desc> | |
1217 The name of an upstream server group.</tag-desc> | |
1218 </list> | |
1219 <para>Supported methods:</para> | |
1220 <list type="bullet" compact="yes"> | |
1221 <listitem id="getStreamUpstreamServers"> | |
1222 <literal>GET</literal> - Return configuration of all servers in a stream upstream server group | |
1223 | |
1224 <para>Returns configuration of each server | |
1225 in a particular stream upstream server group.</para> | |
1226 <para> | |
1227 Possible responses: | |
1228 </para> | |
1229 <list type="bullet"> | |
1230 <listitem>200 - Success, returns an array of <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Servers</link></listitem> | |
1231 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1232 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | |
1233 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> | |
1234 not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1235 </list> | |
1236 </listitem> | |
1237 <listitem id="postStreamUpstreamServer"> | |
1238 <literal>POST</literal> - Add a server to a stream upstream server group | |
1239 | |
1240 <para>Adds a new server to a stream upstream server group. | |
1241 Server parameters are specified in the JSON format.</para> | |
1242 <para> | |
1243 Request parameters: | |
1244 <list type="tag"> | |
1245 <tag-name><literal>postStreamUpstreamServer</literal> | |
1246 (<link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link>, required)</tag-name> | |
1247 <tag-desc> | |
1248 Address of a new server and other optional parameters | |
1249 in the JSON format. | |
1250 The “<literal>ID</literal>”, “<literal>backup</literal>”, and “<literal>service</literal>” parameters | |
1251 cannot be changed.</tag-desc> | |
1252 </list> | |
1253 </para> | |
1254 <para> | |
1255 Possible responses: | |
1256 </para> | |
1257 <list type="bullet"> | |
1258 <listitem>201 - Created, returns <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link></listitem> | |
1259 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), | |
1260 invalid “<value>parameter</value>” value (<literal>UpstreamConfFormatError</literal>), | |
1261 missing “<literal>server</literal>” argument (<literal>UpstreamConfFormatError</literal>), | |
1262 unknown parameter “<value>name</value>” (<literal>UpstreamConfFormatError</literal>), | |
1263 nested object or list (<literal>UpstreamConfFormatError</literal>), | |
1264 “<literal>error</literal>” while parsing (<literal>UpstreamBadAddress</literal>), | |
1265 no port in server “<literal>host</literal>” (<literal>UpstreamBadAddress</literal>), | |
1266 service upstream “<literal>host</literal>” may not have port (<literal>UpstreamBadAddress</literal>), | |
1267 service upstream “<literal>host</literal>” requires domain name (<literal>UpstreamBadAddress</literal>), | |
1268 invalid “<literal>weight</literal>” (<literal>UpstreamBadWeight</literal>), | |
1269 invalid “<literal>max_conns</literal>” (<literal>UpstreamBadMaxConns</literal>), | |
1270 invalid “<literal>max_fails</literal>” (<literal>UpstreamBadMaxFails</literal>), | |
1271 invalid “<literal>fail_timeout</literal>” (<literal>UpstreamBadFailTimeout</literal>), | |
1272 invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>), | |
1273 “<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>), | |
1274 no resolver defined to resolve (<literal>UpstreamConfNoResolver</literal>), | |
1275 upstream “<value>name</value>” has no backup (<literal>UpstreamNoBackup</literal>), | |
1276 upstream “<value>name</value>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1277 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | |
1278 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> | |
1279 not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1280 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1281 </list> | |
1282 </listitem> | |
1283 </list> | |
1284 </tag-desc> | |
1285 <tag-name id="stream_upstreams_stream_upstream_name_servers_stream_upstream_server_id" name="/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}"> | |
1286 <literal>/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}</literal> | |
1287 </tag-name> | |
1288 <tag-desc> | |
1289 Parameters common for all methods: | |
1290 <list type="tag"> | |
1291 <tag-name><literal>streamUpstreamName</literal> | |
1292 (<literal>string</literal>, required)</tag-name> | |
1293 <tag-desc> | |
1294 The name of the upstream server group.</tag-desc> | |
1295 <tag-name><literal>streamUpstreamServerId</literal> | |
1296 (<literal>string</literal>, required)</tag-name> | |
1297 <tag-desc> | |
1298 The ID of the server.</tag-desc> | |
1299 </list> | |
1300 <para>Supported methods:</para> | |
1301 <list type="bullet" compact="yes"> | |
1302 <listitem id="getStreamUpstreamServer"> | |
1303 <literal>GET</literal> - Return configuration of a server in a stream upstream server group | |
1304 | |
1305 <para>Returns configuration of a particular server | |
1306 in the stream upstream server group.</para> | |
1307 <para> | |
1308 Possible responses: | |
1309 </para> | |
1310 <list type="bullet"> | |
1311 <listitem>200 - Success, returns <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link></listitem> | |
1312 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), | |
1313 invalid server ID (<literal>UpstreamBadServerId</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1314 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | |
1315 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), | |
1316 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> | |
1317 not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1318 </list> | |
1319 </listitem> | |
1320 <listitem id="patchStreamUpstreamServer"> | |
1321 <literal>PATCH</literal> - Modify a server in a stream upstream server group | |
1322 | |
1323 <para>Modifies settings of a particular server | |
1324 in a stream upstream server group. | |
1325 Server parameters are specified in the JSON format.</para> | |
1326 <para> | |
1327 Request parameters: | |
1328 <list type="tag"> | |
1329 <tag-name><literal>patchStreamUpstreamServer</literal> | |
1330 (<link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link>, required)</tag-name> | |
1331 <tag-desc> | |
1332 Server parameters, specified in the JSON format. | |
1333 The “<literal>ID</literal>”, “<literal>backup</literal>”, and “<literal>service</literal>” parameters | |
1334 cannot be changed.</tag-desc> | |
1335 </list> | |
1336 </para> | |
1337 <para> | |
1338 Possible responses: | |
1339 </para> | |
1340 <list type="bullet"> | |
1341 <listitem>200 - Success, returns <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link></listitem> | |
1342 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), | |
1343 invalid “<value>parameter</value>” value (<literal>UpstreamConfFormatError</literal>), | |
1344 unknown parameter “<value>name</value>” (<literal>UpstreamConfFormatError</literal>), | |
1345 nested object or list (<literal>UpstreamConfFormatError</literal>), | |
1346 “<literal>error</literal>” while parsing (<literal>UpstreamBadAddress</literal>), | |
1347 invalid “<literal>server</literal>” argument (<literal>UpstreamBadAddress</literal>), | |
1348 no port in server “<literal>host</literal>” (<literal>UpstreamBadAddress</literal>), | |
1349 invalid server ID (<literal>UpstreamBadServerId</literal>), | |
1350 invalid “<literal>weight</literal>” (<literal>UpstreamBadWeight</literal>), | |
1351 invalid “<literal>max_conns</literal>” (<literal>UpstreamBadMaxConns</literal>), | |
1352 invalid “<literal>max_fails</literal>” (<literal>UpstreamBadMaxFails</literal>), | |
1353 invalid “<literal>fail_timeout</literal>” (<literal>UpstreamBadFailTimeout</literal>), | |
1354 invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>), | |
1355 “<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>), | |
1356 server “<value>ID</value>” address is immutable (<literal>UpstreamServerImmutable</literal>), | |
1357 server “<value>ID</value>” weight is immutable (<literal>UpstreamServerWeightImmutable</literal>), | |
1358 upstream “<literal>name</literal>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1359 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | |
1360 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), | |
1361 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> | |
1362 not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1363 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1364 </list> | |
1365 </listitem> | |
1366 <listitem id="deleteStreamUpstreamServer"> | |
1367 <literal>DELETE</literal> - Remove a server from a stream upstream server group | |
1368 | |
1369 <para>Removes a server from a stream server group.</para> | |
1370 <para> | |
1371 Possible responses: | |
1372 </para> | |
1373 <list type="bullet"> | |
1374 <listitem>200 - Success, returns an array of <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Servers</link></listitem> | |
1375 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), | |
1376 invalid server ID (<literal>UpstreamBadServerId</literal>), | |
1377 server “<value>id</value>” not removable (<literal>UpstreamServerImmutable</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1378 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | |
1379 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), | |
1380 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> | |
1381 not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> | |
1382 </list> | |
1383 </listitem> | |
1384 </list> | |
1385 </tag-desc> | |
1386 </list> | |
1387 </para> | |
1388 </section> | |
1389 <section id="definitions" name="Response Objects"> | |
1390 <para> | |
1391 <list type="bullet"> | |
1392 <listitem id="def_nginx_object"> | |
1393 <para>nginx:</para> | |
1394 General information about nginx:<list type="tag"> | |
1395 <tag-name> | |
1396 <literal>version</literal> (<literal>string</literal>) | |
1397 </tag-name> | |
1398 <tag-desc> | |
1399 Version of nginx. | |
1400 </tag-desc> | |
1401 <tag-name> | |
1402 <literal>build</literal> (<literal>string</literal>) | |
1403 </tag-name> | |
1404 <tag-desc> | |
1405 Name of nginx build. | |
1406 </tag-desc> | |
1407 <tag-name> | |
1408 <literal>address</literal> (<literal>string</literal>) | |
1409 </tag-name> | |
1410 <tag-desc> | |
1411 The address of the server that accepted status request. | |
1412 </tag-desc> | |
1413 <tag-name> | |
1414 <literal>generation</literal> (<literal>integer</literal>) | |
1415 </tag-name> | |
1416 <tag-desc> | |
1417 The total number of configuration | |
1418 <link url="https://nginx.org/en/docs/control.html#reconfiguration">reloads</link>. | |
1419 </tag-desc> | |
1420 <tag-name> | |
1421 <literal>load_timestamp</literal> (<literal>string</literal>) | |
1422 </tag-name> | |
1423 <tag-desc> | |
1424 Time of the last reload of configuration, | |
1425 in milliseconds since Epoch. | |
1426 </tag-desc> | |
1427 <tag-name> | |
1428 <literal>timestamp</literal> (<literal>string</literal>) | |
1429 </tag-name> | |
1430 <tag-desc> | |
1431 Current time in milliseconds since Epoch. | |
1432 </tag-desc> | |
1433 <tag-name> | |
1434 <literal>pid</literal> (<literal>integer</literal>) | |
1435 </tag-name> | |
1436 <tag-desc> | |
1437 The ID of the worker process that handled status request. | |
1438 </tag-desc> | |
1439 <tag-name> | |
1440 <literal>ppid</literal> (<literal>integer</literal>) | |
1441 </tag-name> | |
1442 <tag-desc> | |
1443 The ID of the master process that started the | |
1444 <link url="https://nginx.org/en/docs/http/ngx_http_status_module.html#pid">worker process</link>. | |
1445 </tag-desc> | |
1446 </list> | |
1447 <para>Example:</para> | |
1448 <example> | |
1449 { | |
1450 "nginx" : { | |
1451 "version" : "1.13.3", | |
1452 "build" : "nginx-plus-r12-p3", | |
1453 "address" : "206.251.255.64", | |
1454 "generation" : 2, | |
1455 "load_timestamp" : "2017-07-07T11:09:21.594Z", | |
1456 "timestamp" : "2017-07-11T09:31:13.477Z", | |
1457 "pid" : 32212, | |
1458 "ppid" : 32210 | |
1459 } | |
1460 }</example> | |
1461 </listitem> | |
1462 <listitem id="def_nginx_processes"> | |
1463 <para>Processes:</para> | |
1464 <list type="tag"> | |
1465 <tag-name> | |
1466 <literal>respawned</literal> (<literal>integer</literal>) | |
1467 </tag-name> | |
1468 <tag-desc> | |
1469 The total number of abnormally terminated | |
1470 and respawned child processes. | |
1471 </tag-desc> | |
1472 </list> | |
1473 <para>Example:</para> | |
1474 <example> | |
1475 { | |
1476 "respawned" : 0 | |
1477 }</example> | |
1478 </listitem> | |
1479 <listitem id="def_nginx_connections"> | |
1480 <para>Connections:</para> | |
1481 The number of accepted, dropped, active, and idle connections.<list type="tag"> | |
1482 <tag-name> | |
1483 <literal>accepted</literal> (<literal>integer</literal>) | |
1484 </tag-name> | |
1485 <tag-desc> | |
1486 The total number of accepted client connections. | |
1487 </tag-desc> | |
1488 <tag-name> | |
1489 <literal>dropped</literal> (<literal>integer</literal>) | |
1490 </tag-name> | |
1491 <tag-desc> | |
1492 The total number of dropped client connections. | |
1493 </tag-desc> | |
1494 <tag-name> | |
1495 <literal>active</literal> (<literal>integer</literal>) | |
1496 </tag-name> | |
1497 <tag-desc> | |
1498 The current number of active client connections. | |
1499 </tag-desc> | |
1500 <tag-name> | |
1501 <literal>idle</literal> (<literal>integer</literal>) | |
1502 </tag-name> | |
1503 <tag-desc> | |
1504 The current number of idle client connections. | |
1505 </tag-desc> | |
1506 </list> | |
1507 <para>Example:</para> | |
1508 <example> | |
1509 { | |
1510 "accepted" : 4968119, | |
1511 "dropped" : 0, | |
1512 "active" : 5, | |
1513 "idle" : 117 | |
1514 }</example> | |
1515 </listitem> | |
1516 <listitem id="def_nginx_ssl_object"> | |
1517 <para>SSL:</para> | |
1518 <list type="tag"> | |
1519 <tag-name> | |
1520 <literal>handshakes</literal> (<literal>integer</literal>) | |
1521 </tag-name> | |
1522 <tag-desc> | |
1523 The total number of successful SSL handshakes. | |
1524 </tag-desc> | |
1525 <tag-name> | |
1526 <literal>handshakes_failed</literal> (<literal>integer</literal>) | |
1527 </tag-name> | |
1528 <tag-desc> | |
1529 The total number of failed SSL handshakes. | |
1530 </tag-desc> | |
1531 <tag-name> | |
1532 <literal>session_reuses</literal> (<literal>integer</literal>) | |
1533 </tag-name> | |
1534 <tag-desc> | |
1535 The total number of session reuses during SSL handshake. | |
1536 </tag-desc> | |
1537 </list> | |
1538 <para>Example:</para> | |
1539 <example> | |
1540 { | |
1541 "handshakes" : 79572, | |
1542 "handshakes_failed" : 21025, | |
1543 "session_reuses" : 15762 | |
1544 }</example> | |
1545 </listitem> | |
1546 <listitem id="def_nginx_slab_zone"> | |
1547 <para>Shared memory zone with slab allocator:</para> | |
1548 <list type="tag"> | |
1549 <tag-name> | |
1550 <literal>pages</literal></tag-name> | |
1551 <tag-desc> | |
1552 The number of free and used memory pages.<list type="tag"> | |
1553 <tag-name> | |
1554 <literal>used</literal> (<literal>integer</literal>) | |
1555 </tag-name> | |
1556 <tag-desc> | |
1557 The current number of used memory pages. | |
1558 </tag-desc> | |
1559 <tag-name> | |
1560 <literal>free</literal> (<literal>integer</literal>) | |
1561 </tag-name> | |
1562 <tag-desc> | |
1563 The current number of free memory pages. | |
1564 </tag-desc> | |
1565 </list> | |
1566 </tag-desc> | |
1567 <tag-name> | |
1568 <literal>slots</literal></tag-name> | |
1569 <tag-desc> | |
1570 <para>Status data for memory slots (8, 16, 32, 64, 128, etc.)</para><para>A collection of "<link id="def_nginx_slab_zone_slot">Memory Slot</link>" objects</para> | |
1571 </tag-desc> | |
1572 </list> | |
1573 <para>Example:</para> | |
1574 <example> | |
1575 { | |
1576 "pages" : { | |
1577 "used" : 1143, | |
1578 "free" : 2928 | |
1579 }, | |
1580 "slots" : { | |
1581 "8" : { | |
1582 "used" : 0, | |
1583 "free" : 0, | |
1584 "reqs" : 0, | |
1585 "fails" : 0 | |
1586 }, | |
1587 "16" : { | |
1588 "used" : 0, | |
1589 "free" : 0, | |
1590 "reqs" : 0, | |
1591 "fails" : 0 | |
1592 }, | |
1593 "32" : { | |
1594 "used" : 0, | |
1595 "free" : 0, | |
1596 "reqs" : 0, | |
1597 "fails" : 0 | |
1598 }, | |
1599 "64" : { | |
1600 "used" : 1, | |
1601 "free" : 63, | |
1602 "reqs" : 1, | |
1603 "fails" : 0 | |
1604 }, | |
1605 "128" : { | |
1606 "used" : 0, | |
1607 "free" : 0, | |
1608 "reqs" : 0, | |
1609 "fails" : 0 | |
1610 }, | |
1611 "256" : { | |
1612 "used" : 18078, | |
1613 "free" : 178, | |
1614 "reqs" : 1635736, | |
1615 "fails" : 0 | |
1616 } | |
1617 } | |
1618 }</example> | |
1619 </listitem> | |
1620 <listitem id="def_nginx_slab_zone_slot"> | |
1621 <para>Memory Slot:</para> | |
1622 <list type="tag"> | |
1623 <tag-name> | |
1624 <literal>used</literal> (<literal>integer</literal>) | |
1625 </tag-name> | |
1626 <tag-desc> | |
1627 The current number of used memory slots. | |
1628 </tag-desc> | |
1629 <tag-name> | |
1630 <literal>free</literal> (<literal>integer</literal>) | |
1631 </tag-name> | |
1632 <tag-desc> | |
1633 The current number of free memory slots. | |
1634 </tag-desc> | |
1635 <tag-name> | |
1636 <literal>reqs</literal> (<literal>integer</literal>) | |
1637 </tag-name> | |
1638 <tag-desc> | |
1639 The total number of attempts | |
1640 to allocate memory of specified size. | |
1641 </tag-desc> | |
1642 <tag-name> | |
1643 <literal>fails</literal> (<literal>integer</literal>) | |
1644 </tag-name> | |
1645 <tag-desc> | |
1646 The number of unsuccessful attempts | |
1647 to allocate memory of specified size. | |
1648 </tag-desc> | |
1649 </list> | |
1650 </listitem> | |
1651 <listitem id="def_nginx_http_requests"> | |
1652 <para>HTTP Requests:</para> | |
1653 <list type="tag"> | |
1654 <tag-name> | |
1655 <literal>total</literal> (<literal>integer</literal>) | |
1656 </tag-name> | |
1657 <tag-desc> | |
1658 The total number of client requests. | |
1659 </tag-desc> | |
1660 <tag-name> | |
1661 <literal>current</literal> (<literal>integer</literal>) | |
1662 </tag-name> | |
1663 <tag-desc> | |
1664 The current number of client requests. | |
1665 </tag-desc> | |
1666 </list> | |
1667 <para>Example:</para> | |
1668 <example> | |
1669 { | |
1670 "total" : 10624511, | |
1671 "current" : 4 | |
1672 }</example> | |
1673 </listitem> | |
1674 <listitem id="def_nginx_http_server_zone"> | |
1675 <para>HTTP Server Zone:</para> | |
1676 <list type="tag"> | |
1677 <tag-name> | |
1678 <literal>processing</literal> (<literal>integer</literal>) | |
1679 </tag-name> | |
1680 <tag-desc> | |
1681 The number of client requests | |
1682 that are currently being processed. | |
1683 </tag-desc> | |
1684 <tag-name> | |
1685 <literal>requests</literal> (<literal>integer</literal>) | |
1686 </tag-name> | |
1687 <tag-desc> | |
1688 The total number of client requests received from clients. | |
1689 </tag-desc> | |
1690 <tag-name> | |
1691 <literal>responses</literal></tag-name> | |
1692 <tag-desc> | |
1693 The total number of responses sent to clients and the | |
1694 number of responses with status codes | |
1695 “<literal>1xx</literal>”, “<literal>2xx</literal>”, “<literal>3xx</literal>”, | |
1696 “<literal>4xx</literal>”, and “<literal>5xx</literal>”.<list type="tag"> | |
1697 <tag-name> | |
1698 <literal>1xx</literal> (<literal>integer</literal>) | |
1699 </tag-name> | |
1700 <tag-desc> | |
1701 The number of responses with “<literal>1xx</literal>” status codes. | |
1702 </tag-desc> | |
1703 <tag-name> | |
1704 <literal>2xx</literal> (<literal>integer</literal>) | |
1705 </tag-name> | |
1706 <tag-desc> | |
1707 The number of responses with “<literal>2xx</literal>” status codes. | |
1708 </tag-desc> | |
1709 <tag-name> | |
1710 <literal>3xx</literal> (<literal>integer</literal>) | |
1711 </tag-name> | |
1712 <tag-desc> | |
1713 The number of responses with “<literal>3xx</literal>” status codes. | |
1714 </tag-desc> | |
1715 <tag-name> | |
1716 <literal>4xx</literal> (<literal>integer</literal>) | |
1717 </tag-name> | |
1718 <tag-desc> | |
1719 The number of responses with “<literal>4xx</literal>” status codes. | |
1720 </tag-desc> | |
1721 <tag-name> | |
1722 <literal>5xx</literal> (<literal>integer</literal>) | |
1723 </tag-name> | |
1724 <tag-desc> | |
1725 The number of responses with “<literal>5xx</literal>” status codes. | |
1726 </tag-desc> | |
1727 <tag-name> | |
1728 <literal>total</literal> (<literal>integer</literal>) | |
1729 </tag-name> | |
1730 <tag-desc> | |
1731 The total number of responses sent to clients. | |
1732 </tag-desc> | |
1733 </list> | |
1734 </tag-desc> | |
1735 <tag-name> | |
1736 <literal>discarded</literal> (<literal>integer</literal>) | |
1737 </tag-name> | |
1738 <tag-desc> | |
1739 The total number of | |
1740 requests completed without sending a response. | |
1741 </tag-desc> | |
1742 <tag-name> | |
1743 <literal>received</literal> (<literal>integer</literal>) | |
1744 </tag-name> | |
1745 <tag-desc> | |
1746 The total number of bytes received from clients. | |
1747 </tag-desc> | |
1748 <tag-name> | |
1749 <literal>sent</literal> (<literal>integer</literal>) | |
1750 </tag-name> | |
1751 <tag-desc> | |
1752 The total number of bytes sent to clients. | |
1753 </tag-desc> | |
1754 </list> | |
1755 <para>Example:</para> | |
1756 <example> | |
1757 { | |
1758 "processing" : 1, | |
1759 "requests" : 706690, | |
1760 "responses" : { | |
1761 "1xx" : 0, | |
1762 "2xx" : 699482, | |
1763 "3xx" : 4522, | |
1764 "4xx" : 907, | |
1765 "5xx" : 266, | |
1766 "total" : 705177 | |
1767 }, | |
1768 "discarded" : 1513, | |
1769 "received" : 172711587, | |
1770 "sent" : 19415530115 | |
1771 }</example> | |
1772 </listitem> | |
1773 <listitem id="def_nginx_http_cache"> | |
1774 <para>HTTP Cache:</para> | |
1775 <list type="tag"> | |
1776 <tag-name> | |
1777 <literal>size</literal> (<literal>integer</literal>) | |
1778 </tag-name> | |
1779 <tag-desc> | |
1780 The current size of the cache. | |
1781 </tag-desc> | |
1782 <tag-name> | |
1783 <literal>max_size</literal> (<literal>integer</literal>) | |
1784 </tag-name> | |
1785 <tag-desc> | |
1786 The limit on the maximum size of the cache | |
1787 specified in the configuration. | |
1788 </tag-desc> | |
1789 <tag-name> | |
1790 <literal>cold</literal> (<literal>boolean</literal>) | |
1791 </tag-name> | |
1792 <tag-desc> | |
1793 A boolean value indicating whether the “cache loader” process | |
1794 is still loading data from disk into the cache. | |
1795 </tag-desc> | |
1796 <tag-name> | |
1797 <literal>hit</literal></tag-name> | |
1798 <tag-desc> | |
1799 <list type="tag"> | |
1800 <tag-name> | |
1801 <literal>responses</literal> (<literal>integer</literal>) | |
1802 </tag-name> | |
1803 <tag-desc> | |
1804 The total number of | |
1805 <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid">valid</link> | |
1806 responses read from the cache. | |
1807 </tag-desc> | |
1808 <tag-name> | |
1809 <literal>bytes</literal> (<literal>integer</literal>) | |
1810 </tag-name> | |
1811 <tag-desc> | |
1812 The total number of bytes read from the cache. | |
1813 </tag-desc> | |
1814 </list> | |
1815 </tag-desc> | |
1816 <tag-name> | |
1817 <literal>stale</literal></tag-name> | |
1818 <tag-desc> | |
1819 <list type="tag"> | |
1820 <tag-name> | |
1821 <literal>responses</literal> (<literal>integer</literal>) | |
1822 </tag-name> | |
1823 <tag-desc> | |
1824 The total number of expired responses read from the cache (see | |
1825 <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_use_stale">proxy_cache_use_stale</link> | |
1826 and other “<literal>*_cache_use_stale</literal>” directives). | |
1827 </tag-desc> | |
1828 <tag-name> | |
1829 <literal>bytes</literal> (<literal>integer</literal>) | |
1830 </tag-name> | |
1831 <tag-desc> | |
1832 The total number of bytes read from the cache. | |
1833 </tag-desc> | |
1834 </list> | |
1835 </tag-desc> | |
1836 <tag-name> | |
1837 <literal>updating</literal></tag-name> | |
1838 <tag-desc> | |
1839 <list type="tag"> | |
1840 <tag-name> | |
1841 <literal>responses</literal> (<literal>integer</literal>) | |
1842 </tag-name> | |
1843 <tag-desc> | |
1844 The total number of expired responses read from the cache | |
1845 while responses were being updated (see | |
1846 <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_use_stale_updating">proxy_cache_use_stale</link> | |
1847 and other “<literal>*_cache_use_stale</literal>” directives). | |
1848 </tag-desc> | |
1849 <tag-name> | |
1850 <literal>bytes</literal> (<literal>integer</literal>) | |
1851 </tag-name> | |
1852 <tag-desc> | |
1853 The total number of bytes read from the cache. | |
1854 </tag-desc> | |
1855 </list> | |
1856 </tag-desc> | |
1857 <tag-name> | |
1858 <literal>revalidated</literal></tag-name> | |
1859 <tag-desc> | |
1860 <list type="tag"> | |
1861 <tag-name> | |
1862 <literal>responses</literal> (<literal>integer</literal>) | |
1863 </tag-name> | |
1864 <tag-desc> | |
1865 The total number of expired and revalidated responses | |
1866 read from the cache (see | |
1867 <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_revalidate">proxy_cache_revalidate</link> | |
1868 and other “<literal>*_cache_revalidate</literal>” directives. | |
1869 </tag-desc> | |
1870 <tag-name> | |
1871 <literal>bytes</literal> (<literal>integer</literal>) | |
1872 </tag-name> | |
1873 <tag-desc> | |
1874 The total number of bytes read from the cache. | |
1875 </tag-desc> | |
1876 </list> | |
1877 </tag-desc> | |
1878 <tag-name> | |
1879 <literal>miss</literal></tag-name> | |
1880 <tag-desc> | |
1881 <list type="tag"> | |
1882 <tag-name> | |
1883 <literal>responses</literal> (<literal>integer</literal>) | |
1884 </tag-name> | |
1885 <tag-desc> | |
1886 The total number of responses not found in the cache. | |
1887 </tag-desc> | |
1888 <tag-name> | |
1889 <literal>bytes</literal> (<literal>integer</literal>) | |
1890 </tag-name> | |
1891 <tag-desc> | |
1892 The total number of bytes read from the proxied server. | |
1893 </tag-desc> | |
1894 <tag-name> | |
1895 <literal>responses_written</literal> (<literal>integer</literal>) | |
1896 </tag-name> | |
1897 <tag-desc> | |
1898 The total number of responses written to the cache. | |
1899 </tag-desc> | |
1900 <tag-name> | |
1901 <literal>bytes_written</literal> (<literal>integer</literal>) | |
1902 </tag-name> | |
1903 <tag-desc> | |
1904 The total number of bytes written to the cache. | |
1905 </tag-desc> | |
1906 </list> | |
1907 </tag-desc> | |
1908 <tag-name> | |
1909 <literal>expired</literal></tag-name> | |
1910 <tag-desc> | |
1911 <list type="tag"> | |
1912 <tag-name> | |
1913 <literal>responses</literal> (<literal>integer</literal>) | |
1914 </tag-name> | |
1915 <tag-desc> | |
1916 The total number of expired responses not taken from the cache. | |
1917 </tag-desc> | |
1918 <tag-name> | |
1919 <literal>bytes</literal> (<literal>integer</literal>) | |
1920 </tag-name> | |
1921 <tag-desc> | |
1922 The total number of bytes read from the proxied server. | |
1923 </tag-desc> | |
1924 <tag-name> | |
1925 <literal>responses_written</literal> (<literal>integer</literal>) | |
1926 </tag-name> | |
1927 <tag-desc> | |
1928 The total number of responses written to the cache. | |
1929 </tag-desc> | |
1930 <tag-name> | |
1931 <literal>bytes_written</literal> (<literal>integer</literal>) | |
1932 </tag-name> | |
1933 <tag-desc> | |
1934 The total number of bytes written to the cache. | |
1935 </tag-desc> | |
1936 </list> | |
1937 </tag-desc> | |
1938 <tag-name> | |
1939 <literal>bypass</literal></tag-name> | |
1940 <tag-desc> | |
1941 <list type="tag"> | |
1942 <tag-name> | |
1943 <literal>responses</literal> (<literal>integer</literal>) | |
1944 </tag-name> | |
1945 <tag-desc> | |
1946 The total number of responses not looked up in the cache due to the | |
1947 <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_bypass">proxy_cache_bypass</link> | |
1948 and other “<literal>*_cache_bypass</literal>” directives. | |
1949 </tag-desc> | |
1950 <tag-name> | |
1951 <literal>bytes</literal> (<literal>integer</literal>) | |
1952 </tag-name> | |
1953 <tag-desc> | |
1954 The total number of bytes read from the proxied server. | |
1955 </tag-desc> | |
1956 <tag-name> | |
1957 <literal>responses_written</literal> (<literal>integer</literal>) | |
1958 </tag-name> | |
1959 <tag-desc> | |
1960 The total number of responses written to the cache. | |
1961 </tag-desc> | |
1962 <tag-name> | |
1963 <literal>bytes_written</literal> (<literal>integer</literal>) | |
1964 </tag-name> | |
1965 <tag-desc> | |
1966 The total number of bytes written to the cache. | |
1967 </tag-desc> | |
1968 </list> | |
1969 </tag-desc> | |
1970 </list> | |
1971 <para>Example:</para> | |
1972 <example> | |
1973 { | |
1974 "size" : 530915328, | |
1975 "max_size" : 536870912, | |
1976 "cold" : false, | |
1977 "hit" : { | |
1978 "responses" : 254032, | |
1979 "bytes" : 6685627875 | |
1980 }, | |
1981 "stale" : { | |
1982 "responses" : 0, | |
1983 "bytes" : 0 | |
1984 }, | |
1985 "updating" : { | |
1986 "responses" : 0, | |
1987 "bytes" : 0 | |
1988 }, | |
1989 "revalidated" : { | |
1990 "responses" : 0, | |
1991 "bytes" : 0 | |
1992 }, | |
1993 "miss" : { | |
1994 "responses" : 1619201, | |
1995 "bytes" : 53841943822 | |
1996 }, | |
1997 "expired" : { | |
1998 "responses" : 45859, | |
1999 "bytes" : 1656847080, | |
2000 "responses_written" : 44992, | |
2001 "bytes_written" : 1641825173 | |
2002 }, | |
2003 "bypass" : { | |
2004 "responses" : 200187, | |
2005 "bytes" : 5510647548, | |
2006 "responses_written" : 200173, | |
2007 "bytes_written" : 44992 | |
2008 } | |
2009 }</example> | |
2010 </listitem> | |
2011 <listitem id="def_nginx_http_upstream"> | |
2012 <para>HTTP Upstream:</para> | |
2013 <list type="tag"> | |
2014 <tag-name> | |
2015 <literal>peers</literal></tag-name> | |
2016 <tag-desc> | |
2017 An array of:<list type="tag"> | |
2018 <tag-name> | |
2019 <literal>id</literal> (<literal>integer</literal>) | |
2020 </tag-name> | |
2021 <tag-desc> | |
2022 The ID of the server. | |
2023 </tag-desc> | |
2024 <tag-name> | |
2025 <literal>server</literal> (<literal>string</literal>) | |
2026 </tag-name> | |
2027 <tag-desc> | |
2028 An <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</link> | |
2029 of the server. | |
2030 </tag-desc> | |
2031 <tag-name> | |
2032 <literal>service</literal> (<literal>string</literal>) | |
2033 </tag-name> | |
2034 <tag-desc> | |
2035 The | |
2036 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</link> | |
2037 parameter value of the | |
2038 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</link> | |
2039 directive. | |
2040 </tag-desc> | |
2041 <tag-name> | |
2042 <literal>name</literal> (<literal>string</literal>) | |
2043 </tag-name> | |
2044 <tag-desc> | |
2045 The name of the server specified in the | |
2046 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</link> | |
2047 directive. | |
2048 </tag-desc> | |
2049 <tag-name> | |
2050 <literal>backup</literal> (<literal>boolean</literal>) | |
2051 </tag-name> | |
2052 <tag-desc> | |
2053 A boolean value indicating whether the server is a | |
2054 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</link> | |
2055 server. | |
2056 </tag-desc> | |
2057 <tag-name> | |
2058 <literal>weight</literal> (<literal>integer</literal>) | |
2059 </tag-name> | |
2060 <tag-desc> | |
2061 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">Weight</link> | |
2062 of the server. | |
2063 </tag-desc> | |
2064 <tag-name> | |
2065 <literal>state</literal> (<literal>string</literal>) | |
2066 </tag-name> | |
2067 <tag-desc> | |
2068 Current state, which may be one of | |
2069 “<literal>up</literal>”, “<literal>draining</literal>”, “<literal>down</literal>”, | |
2070 “<literal>unavail</literal>”, “<literal>checking</literal>”, | |
2071 and “<literal>unhealthy</literal>”. | |
2072 </tag-desc> | |
2073 <tag-name> | |
2074 <literal>active</literal> (<literal>integer</literal>) | |
2075 </tag-name> | |
2076 <tag-desc> | |
2077 The current number of active connections. | |
2078 </tag-desc> | |
2079 <tag-name> | |
2080 <literal>max_conns</literal> (<literal>integer</literal>) | |
2081 </tag-name> | |
2082 <tag-desc> | |
2083 The | |
2084 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</link> | |
2085 limit for the server. | |
2086 </tag-desc> | |
2087 <tag-name> | |
2088 <literal>requests</literal> (<literal>integer</literal>) | |
2089 </tag-name> | |
2090 <tag-desc> | |
2091 The total number of client requests forwarded to this server. | |
2092 </tag-desc> | |
2093 <tag-name> | |
2094 <literal>responses</literal></tag-name> | |
2095 <tag-desc> | |
2096 <list type="tag"> | |
2097 <tag-name> | |
2098 <literal>1xx</literal> (<literal>integer</literal>) | |
2099 </tag-name> | |
2100 <tag-desc> | |
2101 The number of responses with “<literal>1xx</literal>” status codes. | |
2102 </tag-desc> | |
2103 <tag-name> | |
2104 <literal>2xx</literal> (<literal>integer</literal>) | |
2105 </tag-name> | |
2106 <tag-desc> | |
2107 The number of responses with “<literal>2xx</literal>” status codes. | |
2108 </tag-desc> | |
2109 <tag-name> | |
2110 <literal>3xx</literal> (<literal>integer</literal>) | |
2111 </tag-name> | |
2112 <tag-desc> | |
2113 The number of responses with “<literal>3xx</literal>” status codes. | |
2114 </tag-desc> | |
2115 <tag-name> | |
2116 <literal>4xx</literal> (<literal>integer</literal>) | |
2117 </tag-name> | |
2118 <tag-desc> | |
2119 The number of responses with “<literal>4xx</literal>” status codes. | |
2120 </tag-desc> | |
2121 <tag-name> | |
2122 <literal>5xx</literal> (<literal>integer</literal>) | |
2123 </tag-name> | |
2124 <tag-desc> | |
2125 The number of responses with “<literal>5xx</literal>” status codes. | |
2126 </tag-desc> | |
2127 <tag-name> | |
2128 <literal>total</literal> (<literal>integer</literal>) | |
2129 </tag-name> | |
2130 <tag-desc> | |
2131 The total number of responses obtained from this server. | |
2132 </tag-desc> | |
2133 </list> | |
2134 </tag-desc> | |
2135 <tag-name> | |
2136 <literal>sent</literal> (<literal>integer</literal>) | |
2137 </tag-name> | |
2138 <tag-desc> | |
2139 The total number of bytes sent to this server. | |
2140 </tag-desc> | |
2141 <tag-name> | |
2142 <literal>received</literal> (<literal>integer</literal>) | |
2143 </tag-name> | |
2144 <tag-desc> | |
2145 The total number of bytes received from this server. | |
2146 </tag-desc> | |
2147 <tag-name> | |
2148 <literal>fails</literal> (<literal>integer</literal>) | |
2149 </tag-name> | |
2150 <tag-desc> | |
2151 The total number of unsuccessful attempts | |
2152 to communicate with the server. | |
2153 </tag-desc> | |
2154 <tag-name> | |
2155 <literal>unavail</literal> (<literal>integer</literal>) | |
2156 </tag-name> | |
2157 <tag-desc> | |
2158 How many times the server became unavailable for client requests | |
2159 (state “<literal>unavail</literal>”) due to the number of unsuccessful | |
2160 attempts reaching the | |
2161 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</link> | |
2162 threshold. | |
2163 </tag-desc> | |
2164 <tag-name> | |
2165 <literal>health_checks</literal></tag-name> | |
2166 <tag-desc> | |
2167 <list type="tag"> | |
2168 <tag-name> | |
2169 <literal>checks</literal> (<literal>integer</literal>) | |
2170 </tag-name> | |
2171 <tag-desc> | |
2172 The total number of | |
2173 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check">health check</link> | |
2174 requests made. | |
2175 </tag-desc> | |
2176 <tag-name> | |
2177 <literal>fails</literal> (<literal>integer</literal>) | |
2178 </tag-name> | |
2179 <tag-desc> | |
2180 The number of failed health checks. | |
2181 </tag-desc> | |
2182 <tag-name> | |
2183 <literal>unhealthy</literal> (<literal>integer</literal>) | |
2184 </tag-name> | |
2185 <tag-desc> | |
2186 How many times the server became unhealthy | |
2187 (state “<literal>unhealthy</literal>”). | |
2188 </tag-desc> | |
2189 <tag-name> | |
2190 <literal>last_passed</literal> (<literal>boolean</literal>) | |
2191 </tag-name> | |
2192 <tag-desc> | |
2193 Boolean indicating if the last health check request was successful | |
2194 and passed | |
2195 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#match">tests</link>. | |
2196 </tag-desc> | |
2197 </list> | |
2198 </tag-desc> | |
2199 <tag-name> | |
2200 <literal>downtime</literal> (<literal>integer</literal>) | |
2201 </tag-name> | |
2202 <tag-desc> | |
2203 Total time the server was in the “<literal>unavail</literal>”, | |
2204 “<literal>checking</literal>”, and “<literal>unhealthy</literal>” states. | |
2205 </tag-desc> | |
2206 <tag-name> | |
2207 <literal>downstart</literal> (<literal>string</literal>) | |
2208 </tag-name> | |
2209 <tag-desc> | |
2210 The time (in milliseconds since Epoch) when the server became | |
2211 “<literal>unavail</literal>”, “<literal>checking</literal>”, | |
2212 or “<literal>unhealthy</literal>”. | |
2213 </tag-desc> | |
2214 <tag-name> | |
2215 <literal>selected</literal> (<literal>string</literal>) | |
2216 </tag-name> | |
2217 <tag-desc> | |
2218 The time (in milliseconds since Epoch) | |
2219 when the server was last selected to process a request. | |
2220 </tag-desc> | |
2221 <tag-name> | |
2222 <literal>header_time</literal> (<literal>integer</literal>) | |
2223 </tag-name> | |
2224 <tag-desc> | |
2225 The average time to get the | |
2226 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_header_time">response header</link> | |
2227 from the server. | |
2228 </tag-desc> | |
2229 <tag-name> | |
2230 <literal>response_time</literal> (<literal>integer</literal>) | |
2231 </tag-name> | |
2232 <tag-desc> | |
2233 The average time to get the | |
2234 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_response_time">full response</link> | |
2235 from the server. | |
2236 </tag-desc> | |
2237 </list> | |
2238 </tag-desc> | |
2239 <tag-name> | |
2240 <literal>keepalive</literal> (<literal>integer</literal>) | |
2241 </tag-name> | |
2242 <tag-desc> | |
2243 The current number of idle | |
2244 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive">keepalive</link> | |
2245 connections. | |
2246 </tag-desc> | |
2247 <tag-name> | |
2248 <literal>zombies</literal> (<literal>integer</literal>) | |
2249 </tag-name> | |
2250 <tag-desc> | |
2251 The current number of servers removed | |
2252 from the group but still processing active client requests. | |
2253 </tag-desc> | |
2254 <tag-name> | |
2255 <literal>zone</literal> (<literal>string</literal>) | |
2256 </tag-name> | |
2257 <tag-desc> | |
2258 The name of the shared memory | |
2259 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone">zone</link> | |
2260 that keeps the group’s configuration and run-time state. | |
2261 </tag-desc> | |
2262 <tag-name> | |
2263 <literal>queue</literal></tag-name> | |
2264 <tag-desc> | |
2265 For the requests | |
2266 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue">queue</link>, | |
2267 the following data are provided:<list type="tag"> | |
2268 <tag-name> | |
2269 <literal>size</literal> (<literal>integer</literal>) | |
2270 </tag-name> | |
2271 <tag-desc> | |
2272 The current number of requests in the queue. | |
2273 </tag-desc> | |
2274 <tag-name> | |
2275 <literal>max_size</literal> (<literal>integer</literal>) | |
2276 </tag-name> | |
2277 <tag-desc> | |
2278 The maximum number of requests that can be in the queue | |
2279 at the same time. | |
2280 </tag-desc> | |
2281 <tag-name> | |
2282 <literal>overflows</literal> (<literal>integer</literal>) | |
2283 </tag-name> | |
2284 <tag-desc> | |
2285 The total number of requests rejected due to the queue overflow. | |
2286 </tag-desc> | |
2287 </list> | |
2288 </tag-desc> | |
2289 </list> | |
2290 <para>Example:</para> | |
2291 <example> | |
2292 { | |
2293 "upstream_backend" : { | |
2294 "peers" : [ | |
2295 { | |
2296 "id" : 0, | |
2297 "server" : "10.0.0.1:8088", | |
2298 "name" : "10.0.0.1:8088", | |
2299 "backup" : false, | |
2300 "weight" : 5, | |
2301 "state" : "up", | |
2302 "active" : 0, | |
2303 "max_conns" : 20, | |
2304 "requests" : 667231, | |
2305 "header_time" : 20, | |
2306 "response_time" : 36, | |
2307 "responses" : { | |
2308 "1xx" : 0, | |
2309 "2xx" : 666310, | |
2310 "3xx" : 0, | |
2311 "4xx" : 915, | |
2312 "5xx" : 6, | |
2313 "total" : 667231 | |
2314 }, | |
2315 "sent" : 251946292, | |
2316 "received" : 19222475454, | |
2317 "fails" : 0, | |
2318 "unavail" : 0, | |
2319 "health_checks" : { | |
2320 "checks" : 26214, | |
2321 "fails" : 0, | |
2322 "unhealthy" : 0, | |
2323 "last_passed" : true | |
2324 }, | |
2325 "downtime" : 0, | |
2326 "downstart" : "2017-07-07T11:09:21.602Z", | |
2327 "selected" : "2017-07-17T15:01:25.000Z" | |
2328 }, | |
2329 { | |
2330 "id" : 1, | |
2331 "server" : "10.0.0.1:8089", | |
2332 "name" : "10.0.0.1:8089", | |
2333 "backup" : true, | |
2334 "weight" : 1, | |
2335 "state" : "unhealthy", | |
2336 "active" : 0, | |
2337 "max_conns" : 20, | |
2338 "requests" : 0, | |
2339 "responses" : { | |
2340 "1xx" : 0, | |
2341 "2xx" : 0, | |
2342 "3xx" : 0, | |
2343 "4xx" : 0, | |
2344 "5xx" : 0, | |
2345 "total" : 0 | |
2346 }, | |
2347 "sent" : 0, | |
2348 "received" : 0, | |
2349 "fails" : 0, | |
2350 "unavail" : 0, | |
2351 "health_checks" : { | |
2352 "checks" : 26284, | |
2353 "fails" : 26284, | |
2354 "unhealthy" : 1, | |
2355 "last_passed" : false | |
2356 }, | |
2357 "downtime" : 262925617, | |
2358 "downstart" : "2017-07-07T11:09:21.602Z", | |
2359 "selected" : "2017-07-17T15:01:25.000Z" | |
2360 } | |
2361 ], | |
2362 "keepalive" : 0, | |
2363 "zombies" : 0, | |
2364 "zone" : "upstream_backend" | |
2365 } | |
2366 }</example> | |
2367 </listitem> | |
2368 <listitem id="def_nginx_http_upstream_conf_server"> | |
2369 <para>HTTP Upstream Server:</para> | |
2370 Dynamically configurable parameters of an HTTP upstream | |
2371 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</link>:<list type="tag"> | |
2372 <tag-name> | |
2373 <literal>id</literal> (<literal>integer</literal>) | |
2374 </tag-name> | |
2375 <tag-desc> | |
2376 The ID of the HTTP upstream server. | |
2377 The ID is assigned automatically and cannot be changed. | |
2378 </tag-desc> | |
2379 <tag-name> | |
2380 <literal>server</literal> (<literal>string</literal>) | |
2381 </tag-name> | |
2382 <tag-desc> | |
2383 Same as the | |
2384 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#address">address</link> | |
2385 parameter of the HTTP upstream server. | |
2386 When adding a server, it is possible to specify it as a domain name. | |
2387 In this case, changes of the IP addresses | |
2388 that correspond to a domain name will be monitored and automatically | |
2389 applied to the upstream configuration | |
2390 without the need of restarting nginx. | |
2391 This requires the | |
2392 <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver">resolver</link> | |
2393 directive in the “<literal>http</literal>” block. | |
2394 See also the | |
2395 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#resolve">resolve</link> | |
2396 parameter of the HTTP upstream server. | |
2397 </tag-desc> | |
2398 <tag-name> | |
2399 <literal>service</literal> (<literal>string</literal>) | |
2400 </tag-name> | |
2401 <tag-desc> | |
2402 Same as the | |
2403 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</link> | |
2404 parameter of the HTTP upstream server. | |
2405 This parameter cannot be changed. | |
2406 </tag-desc> | |
2407 <tag-name> | |
2408 <literal>weight</literal> (<literal>integer</literal>) | |
2409 </tag-name> | |
2410 <tag-desc> | |
2411 Same as the | |
2412 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">weight</link> | |
2413 parameter of the HTTP upstream server. | |
2414 </tag-desc> | |
2415 <tag-name> | |
2416 <literal>max_conns</literal> (<literal>integer</literal>) | |
2417 </tag-name> | |
2418 <tag-desc> | |
2419 Same as the | |
2420 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</link> | |
2421 parameter of the HTTP upstream server. | |
2422 </tag-desc> | |
2423 <tag-name> | |
2424 <literal>max_fails</literal> (<literal>integer</literal>) | |
2425 </tag-name> | |
2426 <tag-desc> | |
2427 Same as the | |
2428 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</link> | |
2429 parameter of the HTTP upstream server. | |
2430 </tag-desc> | |
2431 <tag-name> | |
2432 <literal>fail_timeout</literal> (<literal>integer</literal>) | |
2433 </tag-name> | |
2434 <tag-desc> | |
2435 Same as the | |
2436 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout">fail_timeout</link> | |
2437 parameter of the HTTP upstream server. | |
2438 </tag-desc> | |
2439 <tag-name> | |
2440 <literal>slow_start</literal> (<literal>integer</literal>) | |
2441 </tag-name> | |
2442 <tag-desc> | |
2443 Same as the | |
2444 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#slow_start">slow_start</link> | |
2445 parameter of the HTTP upstream server. | |
2446 </tag-desc> | |
2447 <tag-name> | |
2448 <literal>route</literal> (<literal>string</literal>) | |
2449 </tag-name> | |
2450 <tag-desc> | |
2451 Same as the | |
2452 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#route">route</link> | |
2453 parameter of the HTTP upstream server. | |
2454 </tag-desc> | |
2455 <tag-name> | |
2456 <literal>backup</literal> (<literal>boolean</literal>) | |
2457 </tag-name> | |
2458 <tag-desc> | |
2459 When <literal>true</literal>, adds a | |
2460 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</link> | |
2461 server. | |
2462 This parameter cannot be changed. | |
2463 </tag-desc> | |
2464 <tag-name> | |
2465 <literal>down</literal> (<literal>boolean</literal>) | |
2466 </tag-name> | |
2467 <tag-desc> | |
2468 Same as the | |
2469 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#down">down</link> | |
2470 parameter of the HTTP upstream server. | |
2471 </tag-desc> | |
2472 <tag-name> | |
2473 <literal>parent</literal> (<literal>string</literal>) | |
2474 </tag-name> | |
2475 <tag-desc> | |
2476 Parent server ID of the resolved server. | |
2477 The ID is assigned automatically and cannot be changed. | |
2478 </tag-desc> | |
2479 <tag-name> | |
2480 <literal>host</literal> (<literal>string</literal>) | |
2481 </tag-name> | |
2482 <tag-desc> | |
2483 Hostname of the resolved server. | |
2484 The hostname is assigned automatically and cannot be changed. | |
2485 </tag-desc> | |
2486 <tag-name> | |
2487 <literal>drain</literal> (<literal>string</literal>) | |
2488 </tag-name> | |
2489 <tag-desc> | |
2490 Puts the HTTP upstream server into the “draining” mode. | |
2491 In this mode, only requests | |
2492 <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#sticky">bound</link> | |
2493 to the server will be proxied to it. | |
2494 The parameter cannot be initially set, | |
2495 it can only be changed with the <literal>PATCH</literal> method. | |
2496 </tag-desc> | |
2497 </list> | |
2498 <para>Example:</para> | |
2499 <example> | |
2500 { | |
2501 "id" : 1, | |
2502 "server" : "10.0.0.1:8089", | |
2503 "weight" : 4, | |
2504 "max_conns" : 0, | |
2505 "max_fails" : 0, | |
2506 "fail_timeout" : "10s", | |
2507 "slow_start" : "10s", | |
2508 "route" : "", | |
2509 "backup" : true, | |
2510 "down" : true | |
2511 }</example> | |
2512 </listitem> | |
2513 <listitem id="def_nginx_http_keyval_zone"> | |
2514 <para>Keyval Shared Memory Zone:</para> | |
2515 Contents of a keyval shared memory zone.<para>Example:</para> | |
2516 <example> | |
2517 { | |
2518 "key1" : "value1", | |
2519 "key2" : "value2", | |
2520 "key3" : "value3" | |
2521 }</example> | |
2522 </listitem> | |
2523 <listitem id="def_nginx_stream_server_zone"> | |
2524 <para>Stream Server Zone:</para> | |
2525 <list type="tag"> | |
2526 <tag-name> | |
2527 <literal>processing</literal> (<literal>integer</literal>) | |
2528 </tag-name> | |
2529 <tag-desc> | |
2530 The number of client connections | |
2531 that are currently being processed. | |
2532 </tag-desc> | |
2533 <tag-name> | |
2534 <literal>connections</literal> (<literal>integer</literal>) | |
2535 </tag-name> | |
2536 <tag-desc> | |
2537 The total number of connections accepted from clients. | |
2538 </tag-desc> | |
2539 <tag-name> | |
2540 <literal>sessions</literal></tag-name> | |
2541 <tag-desc> | |
2542 Total number of completed sessions, | |
2543 and the number of sessions completed with status codes | |
2544 “<literal>2xx</literal>”, “<literal>4xx</literal>”, or “<literal>5xx</literal>”.<list type="tag"> | |
2545 <tag-name> | |
2546 <literal>2xx</literal> (<literal>integer</literal>) | |
2547 </tag-name> | |
2548 <tag-desc> | |
2549 The total number of sessions completed with | |
2550 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</link> | |
2551 “<literal>2xx</literal>”. | |
2552 </tag-desc> | |
2553 <tag-name> | |
2554 <literal>4xx</literal> (<literal>integer</literal>) | |
2555 </tag-name> | |
2556 <tag-desc> | |
2557 The total number of sessions completed with | |
2558 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</link> | |
2559 “<literal>4xx</literal>”. | |
2560 </tag-desc> | |
2561 <tag-name> | |
2562 <literal>5xx</literal> (<literal>integer</literal>) | |
2563 </tag-name> | |
2564 <tag-desc> | |
2565 The total number of sessions completed with | |
2566 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</link> | |
2567 “<literal>5xx</literal>”. | |
2568 </tag-desc> | |
2569 <tag-name> | |
2570 <literal>total</literal> (<literal>integer</literal>) | |
2571 </tag-name> | |
2572 <tag-desc> | |
2573 The total number of completed client sessions. | |
2574 </tag-desc> | |
2575 </list> | |
2576 </tag-desc> | |
2577 <tag-name> | |
2578 <literal>discarded</literal> (<literal>integer</literal>) | |
2579 </tag-name> | |
2580 <tag-desc> | |
2581 The total number of | |
2582 connections completed without creating a session. | |
2583 </tag-desc> | |
2584 <tag-name> | |
2585 <literal>received</literal> (<literal>integer</literal>) | |
2586 </tag-name> | |
2587 <tag-desc> | |
2588 The total number of bytes received from clients. | |
2589 </tag-desc> | |
2590 <tag-name> | |
2591 <literal>sent</literal> (<literal>integer</literal>) | |
2592 </tag-name> | |
2593 <tag-desc> | |
2594 The total number of bytes sent to clients. | |
2595 </tag-desc> | |
2596 </list> | |
2597 <para>Example:</para> | |
2598 <example> | |
2599 { | |
2600 "dns" : { | |
2601 "processing" : 1, | |
2602 "connections" : 155569, | |
2603 "sessions" : { | |
2604 "2xx" : 155564, | |
2605 "4xx" : 0, | |
2606 "5xx" : 0, | |
2607 "total" : 155569 | |
2608 }, | |
2609 "discarded" : 0, | |
2610 "received" : 4200363, | |
2611 "sent" : 20489184 | |
2612 } | |
2613 }</example> | |
2614 </listitem> | |
2615 <listitem id="def_nginx_stream_upstream"> | |
2616 <para>Stream Upstream:</para> | |
2617 <list type="tag"> | |
2618 <tag-name> | |
2619 <literal>peers</literal></tag-name> | |
2620 <tag-desc> | |
2621 An array of:<list type="tag"> | |
2622 <tag-name> | |
2623 <literal>id</literal> (<literal>integer</literal>) | |
2624 </tag-name> | |
2625 <tag-desc> | |
2626 The ID of the server. | |
2627 </tag-desc> | |
2628 <tag-name> | |
2629 <literal>server</literal> (<literal>string</literal>) | |
2630 </tag-name> | |
2631 <tag-desc> | |
2632 An | |
2633 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</link> | |
2634 of the server. | |
2635 </tag-desc> | |
2636 <tag-name> | |
2637 <literal>service</literal> (<literal>string</literal>) | |
2638 </tag-name> | |
2639 <tag-desc> | |
2640 The | |
2641 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</link> | |
2642 parameter value of the | |
2643 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</link> | |
2644 directive. | |
2645 </tag-desc> | |
2646 <tag-name> | |
2647 <literal>name</literal> (<literal>string</literal>) | |
2648 </tag-name> | |
2649 <tag-desc> | |
2650 The name of the server specified in the | |
2651 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</link> | |
2652 directive. | |
2653 </tag-desc> | |
2654 <tag-name> | |
2655 <literal>backup</literal> (<literal>boolean</literal>) | |
2656 </tag-name> | |
2657 <tag-desc> | |
2658 A boolean value indicating whether the server is a | |
2659 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</link> | |
2660 server. | |
2661 </tag-desc> | |
2662 <tag-name> | |
2663 <literal>weight</literal> (<literal>integer</literal>) | |
2664 </tag-name> | |
2665 <tag-desc> | |
2666 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">Weight</link> | |
2667 of the server. | |
2668 </tag-desc> | |
2669 <tag-name> | |
2670 <literal>state</literal> (<literal>string</literal>) | |
2671 </tag-name> | |
2672 <tag-desc> | |
2673 Current state, which may be one of | |
2674 “<literal>up</literal>”, “<literal>down</literal>”, “<literal>unavail</literal>”, | |
2675 “<literal>checking</literal>”, or “<literal>unhealthy</literal>”. | |
2676 </tag-desc> | |
2677 <tag-name> | |
2678 <literal>active</literal> (<literal>integer</literal>) | |
2679 </tag-name> | |
2680 <tag-desc> | |
2681 The current number of connections. | |
2682 </tag-desc> | |
2683 <tag-name> | |
2684 <literal>max_conns</literal> (<literal>integer</literal>) | |
2685 </tag-name> | |
2686 <tag-desc> | |
2687 The | |
2688 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</link> | |
2689 limit for the server. | |
2690 </tag-desc> | |
2691 <tag-name> | |
2692 <literal>connections</literal> (<literal>integer</literal>) | |
2693 </tag-name> | |
2694 <tag-desc> | |
2695 The total number of client connections forwarded to this server. | |
2696 </tag-desc> | |
2697 <tag-name> | |
2698 <literal>connect_time</literal> (<literal>integer</literal>) | |
2699 </tag-name> | |
2700 <tag-desc> | |
2701 The average time to connect to the upstream server. | |
2702 </tag-desc> | |
2703 <tag-name> | |
2704 <literal>first_byte_time</literal> (<literal>integer</literal>) | |
2705 </tag-name> | |
2706 <tag-desc> | |
2707 The average time to receive the first byte of data. | |
2708 </tag-desc> | |
2709 <tag-name> | |
2710 <literal>response_time</literal> (<literal>integer</literal>) | |
2711 </tag-name> | |
2712 <tag-desc> | |
2713 The average time to receive the last byte of data. | |
2714 </tag-desc> | |
2715 <tag-name> | |
2716 <literal>sent</literal> (<literal>integer</literal>) | |
2717 </tag-name> | |
2718 <tag-desc> | |
2719 The total number of bytes sent to this server. | |
2720 </tag-desc> | |
2721 <tag-name> | |
2722 <literal>received</literal> (<literal>integer</literal>) | |
2723 </tag-name> | |
2724 <tag-desc> | |
2725 The total number of bytes received from this server. | |
2726 </tag-desc> | |
2727 <tag-name> | |
2728 <literal>fails</literal> (<literal>integer</literal>) | |
2729 </tag-name> | |
2730 <tag-desc> | |
2731 The total number of unsuccessful attempts | |
2732 to communicate with the server. | |
2733 </tag-desc> | |
2734 <tag-name> | |
2735 <literal>unavail</literal> (<literal>integer</literal>) | |
2736 </tag-name> | |
2737 <tag-desc> | |
2738 How many times the server became unavailable for client connections | |
2739 (state “<literal>unavail</literal>”) due to the number of unsuccessful | |
2740 attempts reaching the | |
2741 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</link> | |
2742 threshold. | |
2743 </tag-desc> | |
2744 <tag-name> | |
2745 <literal>health_checks</literal></tag-name> | |
2746 <tag-desc> | |
2747 <list type="tag"> | |
2748 <tag-name> | |
2749 <literal>checks</literal> (<literal>integer</literal>) | |
2750 </tag-name> | |
2751 <tag-desc> | |
2752 The total number of | |
2753 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#health_check">health check</link> | |
2754 requests made. | |
2755 </tag-desc> | |
2756 <tag-name> | |
2757 <literal>fails</literal> (<literal>integer</literal>) | |
2758 </tag-name> | |
2759 <tag-desc> | |
2760 The number of failed health checks. | |
2761 </tag-desc> | |
2762 <tag-name> | |
2763 <literal>unhealthy</literal> (<literal>integer</literal>) | |
2764 </tag-name> | |
2765 <tag-desc> | |
2766 How many times the server became unhealthy | |
2767 (state “<literal>unhealthy</literal>”). | |
2768 </tag-desc> | |
2769 <tag-name> | |
2770 <literal>last_passed</literal> (<literal>boolean</literal>) | |
2771 </tag-name> | |
2772 <tag-desc> | |
2773 Boolean indicating whether the last health check request | |
2774 was successful and passed | |
2775 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match">tests</link>. | |
2776 </tag-desc> | |
2777 </list> | |
2778 </tag-desc> | |
2779 <tag-name> | |
2780 <literal>downtime</literal> (<literal>integer</literal>) | |
2781 </tag-name> | |
2782 <tag-desc> | |
2783 Total time the server was in the | |
2784 “<literal>unavail</literal>”, “<literal>checking</literal>”, | |
2785 and “<literal>unhealthy</literal>” states. | |
2786 </tag-desc> | |
2787 <tag-name> | |
2788 <literal>downstart</literal> (<literal>string</literal>) | |
2789 </tag-name> | |
2790 <tag-desc> | |
2791 The time (in milliseconds since Epoch) when the server became | |
2792 “<literal>unavail</literal>”, “<literal>checking</literal>”, | |
2793 or “<literal>unhealthy</literal>”. | |
2794 </tag-desc> | |
2795 <tag-name> | |
2796 <literal>selected</literal> (<literal>string</literal>) | |
2797 </tag-name> | |
2798 <tag-desc> | |
2799 The time (in milliseconds since Epoch) | |
2800 when the server was last selected to process a connection. | |
2801 </tag-desc> | |
2802 </list> | |
2803 </tag-desc> | |
2804 <tag-name> | |
2805 <literal>zombies</literal> (<literal>integer</literal>) | |
2806 </tag-name> | |
2807 <tag-desc> | |
2808 The current number of servers removed from the group | |
2809 but still processing active client connections. | |
2810 </tag-desc> | |
2811 <tag-name> | |
2812 <literal>zone</literal> (<literal>string</literal>) | |
2813 </tag-name> | |
2814 <tag-desc> | |
2815 The name of the shared memory | |
2816 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#zone">zone</link> | |
2817 that keeps the group’s configuration and run-time state. | |
2818 </tag-desc> | |
2819 </list> | |
2820 <para>Example:</para> | |
2821 <example> | |
2822 { | |
2823 "dns" : { | |
2824 "peers" : [ | |
2825 { | |
2826 "id" : 0, | |
2827 "server" : "10.0.0.1:12347", | |
2828 "name" : "10.0.0.1:12347", | |
2829 "backup" : false, | |
2830 "weight" : 5, | |
2831 "state" : "up", | |
2832 "active" : 0, | |
2833 "max_conns" : 50, | |
2834 "connections" : 667231, | |
2835 "sent" : 251946292, | |
2836 "received" : 19222475454, | |
2837 "fails" : 0, | |
2838 "unavail" : 0, | |
2839 "health_checks" : { | |
2840 "checks" : 26214, | |
2841 "fails" : 0, | |
2842 "unhealthy" : 0, | |
2843 "last_passed" : true | |
2844 }, | |
2845 "downtime" : 0, | |
2846 "downstart" : "2017-07-07T11:09:21.602Z", | |
2847 "selected" : "2017-07-17T15:01:25.000Z" | |
2848 }, | |
2849 { | |
2850 "id" : 1, | |
2851 "server" : "10.0.0.1:12348", | |
2852 "name" : "10.0.0.1:12348", | |
2853 "backup" : true, | |
2854 "weight" : 1, | |
2855 "state" : "unhealthy", | |
2856 "active" : 0, | |
2857 "max_conns" : 50, | |
2858 "connections" : 0, | |
2859 "sent" : 0, | |
2860 "received" : 0, | |
2861 "fails" : 0, | |
2862 "unavail" : 0, | |
2863 "health_checks" : { | |
2864 "checks" : 26284, | |
2865 "fails" : 26284, | |
2866 "unhealthy" : 1, | |
2867 "last_passed" : false | |
2868 }, | |
2869 "downtime" : 262925617, | |
2870 "downstart" : "2017-07-07T11:09:21.602Z", | |
2871 "selected" : "2017-07-17T15:01:25.000Z" | |
2872 } | |
2873 ], | |
2874 "zombies" : 0, | |
2875 "zone" : "dns" | |
2876 } | |
2877 }</example> | |
2878 </listitem> | |
2879 <listitem id="def_nginx_stream_upstream_conf_server"> | |
2880 <para>Stream Upstream Server:</para> | |
2881 Dynamically configurable parameters of a stream upstream | |
2882 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</link>:<list type="tag"> | |
2883 <tag-name> | |
2884 <literal>id</literal> (<literal>integer</literal>) | |
2885 </tag-name> | |
2886 <tag-desc> | |
2887 The ID of the stream upstream server. | |
2888 The ID is assigned automatically and cannot be changed. | |
2889 </tag-desc> | |
2890 <tag-name> | |
2891 <literal>server</literal> (<literal>string</literal>) | |
2892 </tag-name> | |
2893 <tag-desc> | |
2894 Same as the | |
2895 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</link> | |
2896 parameter of the stream upstream server. | |
2897 When adding a server, it is possible to specify it as a domain name. | |
2898 In this case, changes of the IP addresses | |
2899 that correspond to a domain name will be monitored and automatically | |
2900 applied to the upstream configuration | |
2901 without the need of restarting nginx. | |
2902 This requires the | |
2903 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#resolver">resolver</link> | |
2904 directive in the “<literal>stream</literal>” block. | |
2905 See also the | |
2906 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#resolve">resolve</link> | |
2907 parameter of the stream upstream server. | |
2908 </tag-desc> | |
2909 <tag-name> | |
2910 <literal>service</literal> (<literal>string</literal>) | |
2911 </tag-name> | |
2912 <tag-desc> | |
2913 Same as the | |
2914 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</link> | |
2915 parameter of the stream upstream server. | |
2916 This parameter cannot be changed. | |
2917 </tag-desc> | |
2918 <tag-name> | |
2919 <literal>weight</literal> (<literal>integer</literal>) | |
2920 </tag-name> | |
2921 <tag-desc> | |
2922 Same as the | |
2923 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">weight</link> | |
2924 parameter of the stream upstream server. | |
2925 </tag-desc> | |
2926 <tag-name> | |
2927 <literal>max_conns</literal> (<literal>integer</literal>) | |
2928 </tag-name> | |
2929 <tag-desc> | |
2930 Same as the | |
2931 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</link> | |
2932 parameter of the stream upstream server. | |
2933 </tag-desc> | |
2934 <tag-name> | |
2935 <literal>max_fails</literal> (<literal>integer</literal>) | |
2936 </tag-name> | |
2937 <tag-desc> | |
2938 Same as the | |
2939 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</link> | |
2940 parameter of the stream upstream server. | |
2941 </tag-desc> | |
2942 <tag-name> | |
2943 <literal>fail_timeout</literal> (<literal>integer</literal>) | |
2944 </tag-name> | |
2945 <tag-desc> | |
2946 Same as the | |
2947 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#fail_timeout">fail_timeout</link> | |
2948 parameter of the stream upstream server. | |
2949 </tag-desc> | |
2950 <tag-name> | |
2951 <literal>slow_start</literal> (<literal>integer</literal>) | |
2952 </tag-name> | |
2953 <tag-desc> | |
2954 Same as the | |
2955 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#slow_start">slow_start</link> | |
2956 parameter of the stream upstream server. | |
2957 </tag-desc> | |
2958 <tag-name> | |
2959 <literal>backup</literal> (<literal>boolean</literal>) | |
2960 </tag-name> | |
2961 <tag-desc> | |
2962 When <literal>true</literal>, adds a | |
2963 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</link> | |
2964 server. | |
2965 This parameter cannot be changed. | |
2966 </tag-desc> | |
2967 <tag-name> | |
2968 <literal>down</literal> (<literal>boolean</literal>) | |
2969 </tag-name> | |
2970 <tag-desc> | |
2971 Same as the | |
2972 <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#down">down</link> | |
2973 parameter of the stream upstream server. | |
2974 </tag-desc> | |
2975 <tag-name> | |
2976 <literal>parent</literal> (<literal>string</literal>) | |
2977 </tag-name> | |
2978 <tag-desc> | |
2979 Parent server ID of the resolved server. | |
2980 The ID is assigned automatically and cannot be changed. | |
2981 </tag-desc> | |
2982 <tag-name> | |
2983 <literal>host</literal> (<literal>string</literal>) | |
2984 </tag-name> | |
2985 <tag-desc> | |
2986 Hostname of the resolved server. | |
2987 The hostname is assigned automatically and cannot be changed. | |
2988 </tag-desc> | |
2989 </list> | |
2990 <para>Example:</para> | |
2991 <example> | |
2992 { | |
2993 "id" : 0, | |
2994 "server" : "10.0.0.1:12348", | |
2995 "weight" : 1, | |
2996 "max_conns" : 0, | |
2997 "max_fails" : 1, | |
2998 "fail_timeout" : "10s", | |
2999 "slow_start" : 0, | |
3000 "backup" : false, | |
3001 "down" : false | |
3002 }</example> | |
3003 </listitem> | |
3004 <listitem id="def_nginx_error"> | |
3005 <para>Error:</para> | |
3006 nginx error object.<list type="tag"> | |
3007 <tag-name> | |
3008 <literal>path</literal> (<literal>string</literal>) | |
3009 </tag-name> | |
3010 <tag-desc> | |
3011 API path. | |
3012 </tag-desc> | |
3013 <tag-name> | |
3014 <literal>method</literal> (<literal>string</literal>) | |
3015 </tag-name> | |
3016 <tag-desc> | |
3017 HTTP method. | |
3018 </tag-desc> | |
3019 <tag-name> | |
3020 <literal>error</literal></tag-name> | |
3021 <tag-desc> | |
3022 <list type="tag"> | |
3023 <tag-name> | |
3024 <literal>status</literal> (<literal>string</literal>) | |
3025 </tag-name> | |
3026 <tag-desc> | |
3027 HTTP error code. | |
3028 </tag-desc> | |
3029 <tag-name> | |
3030 <literal>text</literal> (<literal>string</literal>) | |
3031 </tag-name> | |
3032 <tag-desc> | |
3033 Error description. | |
3034 </tag-desc> | |
3035 <tag-name> | |
3036 <literal>code</literal> (<literal>string</literal>) | |
3037 </tag-name> | |
3038 <tag-desc> | |
3039 Internal nginx error code. | |
3040 </tag-desc> | |
3041 </list> | |
3042 </tag-desc> | |
3043 <tag-name> | |
3044 <literal>request_id</literal> (<literal>string</literal>) | |
3045 </tag-name> | |
3046 <tag-desc> | |
3047 The ID of the request, equals the value of the | |
3048 <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_id">$request_id</link> | |
3049 variable. | |
3050 </tag-desc> | |
3051 <tag-name> | |
3052 <literal>href</literal> (<literal>string</literal>) | |
3053 </tag-name> | |
3054 <tag-desc> | |
3055 Link to reference documentation. | |
3056 </tag-desc> | |
3057 </list> | |
3058 </listitem> | |
3059 </list> | |
3060 </para> | |
3061 </section> | |
3062 | |
3063 </module> |