Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_api_module.xml @ 2034:7e7edf832099

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