+ +

+ + +The ngx_http_api_module module (1.13.3) provides REST API +for accessing various status information, +configuring upstream server groups on-the-fly, and managing +key-value pairs +without the need of reconfiguring nginx. + + + + +The module supersedes the +ngx_http_status_module and +ngx_http_upstream_conf_module +modules. + + + + + +This module is available as part of our +commercial subscription. + + + +

+ + +

+ + + +http { + upstream backend { + zone http_backend 64k; + + server backend1.example.com weight=5; + server backend2.example.com; + } + + proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m; + + server { + server_name backend.example.com; + + location / { + proxy_pass http://backend; + proxy_cache cache_backend; + + health_check; + } + + status_zone server_backend; + } + + keyval_zone zone=one:32k state=one.keyval; + keyval $arg_text $text zone=one; + + server { + listen 127.0.0.1; + + location /api { + api write=on; + allow 127.0.0.1; + deny all; + } + } +} + +stream { + upstream backend { + zone stream_backend 64k; + + server backend1.example.com:12345 weight=5; + server backend2.example.com:12345; + } + + server { + listen 127.0.0.1:12345; + proxy_pass backend; + status_zone server_backend; + health_check; + } +} + +All API requests include a supported API version in the URI. +Examples of API requests with this configuration: + +http://127.0.0.1/api/1/ +http://127.0.0.1/api/1/nginx +http://127.0.0.1/api/1/connections +http://127.0.0.1/api/1/http/requests +http://127.0.0.1/api/1/http/server_zones/server_backend +http://127.0.0.1/api/1/http/caches/cache_backend +http://127.0.0.1/api/1/http/upstreams/backend +http://127.0.0.1/api/1/http/upstreams/backend/servers/ +http://127.0.0.1/api/1/http/upstreams/backend/servers/1 +http://127.0.0.1/api/1/http/keyvals/one?key=arg1 +http://127.0.0.1/api/1/stream/ +http://127.0.0.1/api/1/stream/server_zones/server_backend +http://127.0.0.1/api/1/stream/upstreams/ +http://127.0.0.1/api/1/stream/upstreams/backend +http://127.0.0.1/api/1/stream/upstreams/backend/servers/1 + + + +

+ + +

+ + + +[write=on|off] + +location + + +Turns on the REST API interface in the surrounding location. +Access to this location should be +limited. + + + +The write parameter determines whether the API +is read-only or read-write. +By default, the API is read-only. + + + +All API requests should contain a supported API version in the URI. +If the request URI equals the location prefix, +the list of supported API versions is returned. +The current and the only API version is “1”. + + + +The optional “fields” argument in the request line +specifies which fields of the requested objects will be output: + +http://127.0.0.1/api/1/nginx?fields=version,build + + + + + +

+ + + +/ + + +Supported methods: + + +GET - Return list of root endpoints + +Returns a list of root endpoints. + +Possible responses: + + +200 - Success, returns an array of strings + + + + + +/nginx + + +Supported methods: + + +GET - Return status of nginx running instance + +Returns nginx version, build name, address, +number of configuration reloads, IDs of master and worker processes. + +Request parameters: + +fields +(string, optional) + +Limits which fields of nginx running instance will be output. + + + +Possible responses: + + +200 - Success, returns nginx + + + + + +/processes + + +Supported methods: + + +GET - Return nginx processes status + +Returns the number of abnormally terminated +and respawned child processes. + +Possible responses: + + +200 - Success, returns Processes + + + +DELETE - Reset nginx processes statistics + +Resets counters of abnormally terminated and respawned +child processes. + +Possible responses: + + +204 - Success + + + + + +/connections + + +Supported methods: + + +GET - Return client connections statistics + +Returns statistics of client connections. + +Request parameters: + +fields +(string, optional) + +Limits which fields of the connections statistics will be output. + + + +Possible responses: + + +200 - Success, returns Connections + + + +DELETE - Reset client connections statistics + +Resets statistics of accepted and dropped +client connections. + +Possible responses: + + +204 - Success + + + + + +/ssl + + +Supported methods: + + +GET - Return SSL statistics + +Returns SSL statistics. + +Request parameters: + +fields +(string, optional) + +Limits which fields of SSL statistics will be output. + + + +Possible responses: + + +200 - Success, returns SSL + + + +DELETE - Reset SSL statistics + +Resets counters of SSL handshakes and session reuses. + +Possible responses: + + +204 - Success + + + + + +/slabs/ + + +Supported methods: + + +GET - Return status of all slabs + +Returns status of slabs +for each shared memory zone with slab allocator. + +Request parameters: + +fields +(string, optional) + +Limits which fields of slab zones will be output. +If the “fields” value is empty, +then only zone names are output. + + + +Possible responses: + + +200 - Success, returns a collection of "Shared memory zone with slab allocator" objects for all slabs + + + + + +/slabs/{slabZoneName} + + +Parameters common for all methods: + +slabZoneName +(string, required) + +The name of the shared memory zone with slab allocator. + +Supported methods: + + +GET - Return status of a slab + +Returns status of slabs for a particular shared memory zone +with slab allocator. + +Request parameters: + +fields +(string, optional) + +Limits which fields of the slab zone will be output. + + + +Possible responses: + + +200 - Success, returns Shared memory zone with slab allocator +404 - Slab not found (SlabNotFound), returns Error + + + +DELETE - Reset slab statistics + +Resets the “reqs” and “fails” +metrics for each memory slot. + +Possible responses: + + +204 - Success +404 - Slab not found (SlabNotFound), returns Error + + + + + +/http/ + + +Supported methods: + + +GET - Return list of HTTP-related endpoints + +Returns a list of first level HTTP endpoints. + +Possible responses: + + +200 - Success, returns an array of strings + + + + + +/http/requests + + +Supported methods: + + +GET - Return HTTP requests statistics + +Returns status of client HTTP requests. + +Request parameters: + +fields +(string, optional) + +Limits which fields of client HTTP requests statistics +will be output. + + + +Possible responses: + + +200 - Success, returns HTTP Requests + + + +DELETE - Reset HTTP requests statistics + +Resets the number of total client HTTP requests. + +Possible responses: + + +204 - Success + + + + + +/http/server_zones/ + + +Supported methods: + + +GET - Return status of all HTTP server zones + +Returns status information for each HTTP +server zone. + +Request parameters: + +fields +(string, optional) + +Limits which fields of server zones will be output. +If the “fields” value is empty, +then only server zone names are output. + + + +Possible responses: + + +200 - Success, returns a collection of "HTTP Server Zone" objects for all http server zones + + + + + +/http/server_zones/{httpServerZoneName} + + +Parameters common for all methods: + +httpServerZoneName +(string, required) + +The name of an HTTP server zone. + +Supported methods: + + +GET - Return status of an HTTP server zone + +Returns status of a particular HTTP server zone. + +Request parameters: + +fields +(string, optional) + +Limits which fields of the server zone will be output. + + + +Possible responses: + + +200 - Success, returns HTTP Server Zone +404 - Server zone not found (ServerZoneNotFound), returns Error + + + +DELETE - Reset statistics for an HTTP server zone + +Resets statistics of accepted and discarded requests, responses, +received and sent bytes in a particular HTTP server zone. + +Possible responses: + + +204 - Success +404 - Server zone not found (ServerZoneNotFound), returns Error + + + + + +/http/caches/ + + +Supported methods: + + +GET - Return status of all caches + +Returns status of each cache configured by +proxy_cache_path +and other “*_cache_path” directives. + +Request parameters: + +fields +(string, optional) + +Limits which fields of cache zones will be output. +If the “fields” value is empty, +then only names of cache zones are output. + + + +Possible responses: + + +200 - Success, returns a collection of "HTTP Cache" objects for all http caches + + + + + +/http/caches/{httpCacheZoneName} + + +Parameters common for all methods: + +httpCacheZoneName +(string, required) + +The name of the cache zone. + +Supported methods: + + +GET - Return status of a cache + +Returns status of a particular cache. + +Request parameters: + +fields +(string, optional) + +Limits which fields of the cache zone will be output. + + + +Possible responses: + + +200 - Success, returns HTTP Cache +404 - Cache not found (CacheNotFound), returns Error + + + +DELETE - Reset cache statistics + +Resets statistics of cache hits/misses in a particular cache zone. + +Possible responses: + + +204 - Success +404 - Cache not found (CacheNotFound), returns Error + + + + + +/http/upstreams/ + + +Supported methods: + + +GET - Return status of all HTTP upstream server groups + +Returns status of each HTTP upstream server group +and its servers. + +Request parameters: + +fields +(string, optional) + +Limits which fields of upstream server groups will be output. +If the “fields” value is empty, +only names of upstreams are output. + + + +Possible responses: + + +200 - Success, returns a collection of "HTTP Upstream" objects for all http upstreams + + + + + +/http/upstreams/{httpUpstreamName}/ + + +Parameters common for all methods: + +httpUpstreamName +(string, required) + +The name of an HTTP upstream server group. + +Supported methods: + + +GET - Return status of an HTTP upstream server group + +Returns status of a particular HTTP upstream server group +and its servers. + +Request parameters: + +fields +(string, optional) + +Limits which fields of the upstream server group will be output. + + + +Possible responses: + + +200 - Success, returns HTTP Upstream +400 - Upstream is static (UpstreamStatic), returns Error +404 - Upstream not found (UpstreamNotFound), returns Error + + + +DELETE - Reset statistics of an HTTP upstream server group + +Resets the statistics for each upstream server +in an upstream server group and queue statistics. + +Possible responses: + + +204 - Success +400 - Upstream is static (UpstreamStatic), returns Error +404 - Upstream not found (UpstreamNotFound), returns Error + + + + + +/http/upstreams/{httpUpstreamName}/servers/ + + +Parameters common for all methods: + +httpUpstreamName +(string, required) + +The name of an upstream server group. + +Supported methods: + + +GET - Return configuration of all servers in an HTTP upstream server group + +Returns configuration of each server +in a particular HTTP upstream server group. + +Possible responses: + + +200 - Success, returns an array of HTTP Upstream Servers +400 - Upstream is static (UpstreamStatic), returns Error +404 - Upstream not found (UpstreamNotFound), returns Error + + + +POST - Add a server to an HTTP upstream server group + +Adds a new server to an HTTP upstream server group. +Server parameters are specified in the JSON format. + +Request parameters: + +postHttpUpstreamServer +(HTTP Upstream Server, required) + +Address of a new server and other optional parameters +in the JSON format. +The “ID”, “backup”, and “service” parameters +cannot be changed. + + + +Possible responses: + + +201 - Created, returns HTTP Upstream Server +400 - Upstream is static (UpstreamStatic), +invalid “parameter” value (UpstreamConfFormatError), +missing “server” argument (UpstreamConfFormatError), +unknown parameter “name” (UpstreamConfFormatError), +nested object or list (UpstreamConfFormatError), +“error” while parsing (UpstreamBadAddress), +service upstream “host” may not have port (UpstreamBadAddress), +service upstream “host” requires domain name (UpstreamBadAddress), +invalid “weight” (UpstreamBadWeight), +invalid “max_conns” (UpstreamBadMaxConns), +invalid “max_fails” (UpstreamBadMaxFails), +invalid “fail_timeout” (UpstreamBadFailTimeout), +invalid “slow_start” (UpstreamBadSlowStart), +route is too long (UpstreamBadRoute), +“service” is empty (UpstreamBadService), +no resolver defined to resolve (UpstreamConfNoResolver), +upstream “name” has no backup (UpstreamNoBackup), +upstream “name” memory exhausted (UpstreamOutOfMemory), returns Error +404 - Upstream not found (UpstreamNotFound), returns Error +415 - JSON error (JsonError), returns Error + + + + + +/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId} + + +Parameters common for all methods: + +httpUpstreamName +(string, required) + +The name of the upstream server group. +httpUpstreamServerId +(string, required) + +The ID of the server. + +Supported methods: + + +GET - Return configuration of a server in an HTTP upstream server group + +Returns configuration of a particular server +in the HTTP upstream server group. + +Possible responses: + + +200 - Success, returns HTTP Upstream Server +400 - Upstream is static (UpstreamStatic), +invalid server ID (UpstreamBadServerId), returns Error +404 - Upstream not found (UpstreamNotFound), +server with ID “id” does not exist (UpstreamServerNotFound), returns Error + + + +PATCH - Modify a server in an HTTP upstream server group + +Modifies settings of a particular server +in an HTTP upstream server group. +Server parameters are specified in the JSON format. + +Request parameters: + +patchHttpUpstreamServer +(HTTP Upstream Server, required) + +Server parameters, specified in the JSON format. +The “ID”, “backup”, and “service” parameters +cannot be changed. + + + +Possible responses: + + +200 - Success, returns HTTP Upstream Server +400 - Upstream is static (UpstreamStatic), +invalid “parameter” value (UpstreamConfFormatError), +unknown parameter “name” (UpstreamConfFormatError), +nested object or list (UpstreamConfFormatError), +“error” while parsing (UpstreamBadAddress), +invalid “server” argument (UpstreamBadAddress), +invalid server ID (UpstreamBadServerId), +invalid “weight” (UpstreamBadWeight), +invalid “max_conns” (UpstreamBadMaxConns), +invalid “max_fails” (UpstreamBadMaxFails), +invalid “fail_timeout” (UpstreamBadFailTimeout), +invalid “slow_start” (UpstreamBadSlowStart), +route is too long (UpstreamBadRoute), +“service” is empty (UpstreamBadService), +server “ID” address is immutable (UpstreamServerImmutable), +server “ID” weight is immutable (UpstreamServerWeightImmutable), +upstream “name” memory exhausted (UpstreamOutOfMemory), returns Error +404 - Upstream not found (UpstreamNotFound), +server with ID “id” does not exist (UpstreamServerNotFound), returns Error +415 - JSON error (JsonError), returns Error + + + +DELETE - Remove a server from an HTTP upstream server group + +Removes a server from an HTTP upstream server group. + +Possible responses: + + +200 - Success, returns an array of HTTP Upstream Servers +400 - Upstream is static (UpstreamStatic), +invalid server ID (UpstreamBadServerId), +server “id” not removable (UpstreamServerImmutable), returns Error +404 - Upstream not found (UpstreamNotFound), +server with ID “id” does not exist (UpstreamServerNotFound), returns Error + + + + + +/http/keyvals/ + + +Supported methods: + + +GET - Return key-value pairs from all keyval zones + +Returns key-value pairs for each keyval shared memory +zone. + +Request parameters: + +fields +(string, optional) + +If the “fields” value is empty, +then only keyval zone names are output. + + + +Possible responses: + + +200 - Success, returns a collection of "Keyval Shared Memory Zone" objects for all http keyvals + + + + + +/http/keyvals/{httpKeyvalZoneName} + + +Parameters common for all methods: + +httpKeyvalZoneName +(string, required) + +The name of a keyval shared memory zone. + +Supported methods: + + +GET - Return key-value pairs from a keyval zone + +Returns key-value pairs stored in a particular keyval shared memory +zone. + +Request parameters: + +key +(string, optional) + +Get a particular key-value pair from the keyval zone. + + + +Possible responses: + + +200 - Success, returns Keyval Shared Memory Zone +404 - Keyval not found (KeyvalNotFound), +keyval key not found (KeyvalKeyNotFound), returns Error + + + +POST - Add a key-value pair to the keyval zone + +Adds a new key-value pair to the keyval shared memory +zone. +Several key-value pairs can be entered +if the keyval shared memory zone is empty. + +Request parameters: + +Key-value +(Keyval Shared Memory Zone, required) + +A key-value pair is specified in the JSON format. +Several key-value pairs can be entered +if the keyval shared memory zone is empty. + + + +Possible responses: + + +201 - Created +400 - Key required (KeyvalFormatError), +only one key can be added (KeyvalFormatError), +nested object or list (KeyvalFormatError), returns Error +404 - Keyval not found (KeyvalNotFound), returns Error +409 - Key already exists (KeyvalKeyExists), returns Error +415 - JSON error (JsonError), returns Error + + + +PATCH - Modify a key-value or delete a key + +Changes the value of the selected key in the key-value pair +or deletes a key by setting the key value to null. + +Request parameters: + +httpKeyvalZoneKeyValue +(Keyval Shared Memory Zone, required) + +A new value for the key is specified in the JSON format. + + + +Possible responses: + + +204 - Success +400 - Key required (KeyvalFormatError), +only one key can be updated (KeyvalFormatError), +nested object or list (KeyvalFormatError), returns Error +404 - Keyval not found (KeyvalNotFound), +keyval key not found (KeyvalKeyNotFound), returns Error +415 - JSON error (JsonError), returns Error + + + +DELETE - Empty the keyval zone + +Deletes all key-value pairs from the keyval shared memory +zone. + +Possible responses: + + +204 - Success +404 - Keyval not found (KeyvalNotFound), returns Error + + + + + +/stream/ + + +Supported methods: + + +GET - Return list of stream-related endpoints + +Returns a list of first level stream endpoints. + +Possible responses: + + +200 - Success, returns an array of strings + + + + + +/stream/server_zones/ + + +Supported methods: + + +GET - Return status of all stream server zones + +Returns status information for each stream +server zone. + +Request parameters: + +fields +(string, optional) + +Limits which fields of server zones will be output. +If the “fields” value is empty, +then only server zone names are output. + + + +Possible responses: + + +200 - Success, returns a collection of "Stream Server Zone" objects for all stream server zones +404 - stream +not configured (StreamNotConfigured), returns Error + + + + + +/stream/server_zones/{streamServerZoneName} + + +Parameters common for all methods: + +streamServerZoneName +(string, required) + +The name of a stream server zone. + +Supported methods: + + +GET - Return status of a stream server zone + +Returns status of a particular stream server zone. + +Request parameters: + +fields +(string, optional) + +Limits which fields of the server zone will be output. + + + +Possible responses: + + +200 - Success, returns Stream Server Zone +404 - Server zone not found (ServerZoneNotFound), +stream +not configured (StreamNotConfigured), returns Error + + + +DELETE - Reset statistics for a stream server zone + +Resets statistics of accepted and discarded connections, sessions, +received and sent bytes in a particular stream server zone. + +Possible responses: + + +204 - Success +404 - Server zone not found (ServerZoneNotFound), +stream +not configured (StreamNotConfigured), returns Error + + + + + +/stream/upstreams/ + + +Supported methods: + + +GET - Return status of all stream upstream server groups + +Returns status of each stream upstream server group +and its servers. + +Request parameters: + +fields +(string, optional) + +Limits which fields of upstream server groups will be output. +If the “fields” value is empty, +only names of upstreams are output. + + + +Possible responses: + + +200 - Success, returns a collection of "Stream Upstream" objects for all stream upstreams +404 - stream +not configured (StreamNotConfigured), returns Error + + + + + +/stream/upstreams/{streamUpstreamName}/ + + +Parameters common for all methods: + +streamUpstreamName +(string, required) + +The name of a stream upstream server group. + +Supported methods: + + +GET - Return status of a stream upstream server group + +Returns status of a particular stream upstream server group +and its servers. + +Request parameters: + +fields +(string, optional) + +Limits which fields of the upstream server group will be output. + + + +Possible responses: + + +200 - Success, returns Stream Upstream +400 - Upstream is static (UpstreamStatic), returns Error +404 - Upstream not found (UpstreamNotFound), +stream +not configured (StreamNotConfigured), returns Error + + + +DELETE - Reset statistics of a stream upstream server group + +Resets the statistics for each upstream server +in an upstream server group. + +Possible responses: + + +204 - Success +400 - Upstream is static (UpstreamStatic), returns Error +404 - Upstream not found (UpstreamNotFound), +stream +not configured (StreamNotConfigured), returns Error + + + + + +/stream/upstreams/{streamUpstreamName}/servers/ + + +Parameters common for all methods: + +streamUpstreamName +(string, required) + +The name of an upstream server group. + +Supported methods: + + +GET - Return configuration of all servers in a stream upstream server group + +Returns configuration of each server +in a particular stream upstream server group. + +Possible responses: + + +200 - Success, returns an array of Stream Upstream Servers +400 - Upstream is static (UpstreamStatic), returns Error +404 - Upstream not found (UpstreamNotFound), +stream +not configured (StreamNotConfigured), returns Error + + + +POST - Add a server to a stream upstream server group + +Adds a new server to a stream upstream server group. +Server parameters are specified in the JSON format. + +Request parameters: + +postStreamUpstreamServer +(Stream Upstream Server, required) + +Address of a new server and other optional parameters +in the JSON format. +The “ID”, “backup”, and “service” parameters +cannot be changed. + + + +Possible responses: + + +201 - Created, returns Stream Upstream Server +400 - Upstream is static (UpstreamStatic), +invalid “parameter” value (UpstreamConfFormatError), +missing “server” argument (UpstreamConfFormatError), +unknown parameter “name” (UpstreamConfFormatError), +nested object or list (UpstreamConfFormatError), +“error” while parsing (UpstreamBadAddress), +no port in server “host” (UpstreamBadAddress), +service upstream “host” may not have port (UpstreamBadAddress), +service upstream “host” requires domain name (UpstreamBadAddress), +invalid “weight” (UpstreamBadWeight), +invalid “max_conns” (UpstreamBadMaxConns), +invalid “max_fails” (UpstreamBadMaxFails), +invalid “fail_timeout” (UpstreamBadFailTimeout), +invalid “slow_start” (UpstreamBadSlowStart), +“service” is empty (UpstreamBadService), +no resolver defined to resolve (UpstreamConfNoResolver), +upstream “name” has no backup (UpstreamNoBackup), +upstream “name” memory exhausted (UpstreamOutOfMemory), returns Error +404 - Upstream not found (UpstreamNotFound), +stream +not configured (StreamNotConfigured), returns Error +415 - JSON error (JsonError), returns Error + + + + + +/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId} + + +Parameters common for all methods: + +streamUpstreamName +(string, required) + +The name of the upstream server group. +streamUpstreamServerId +(string, required) + +The ID of the server. + +Supported methods: + + +GET - Return configuration of a server in a stream upstream server group + +Returns configuration of a particular server +in the stream upstream server group. + +Possible responses: + + +200 - Success, returns Stream Upstream Server +400 - Upstream is static (UpstreamStatic), +invalid server ID (UpstreamBadServerId), returns Error +404 - Upstream not found (UpstreamNotFound), +server with ID “id” does not exist (UpstreamServerNotFound), +stream +not configured (StreamNotConfigured), returns Error + + + +PATCH - Modify a server in a stream upstream server group + +Modifies settings of a particular server +in a stream upstream server group. +Server parameters are specified in the JSON format. + +Request parameters: + +patchStreamUpstreamServer +(Stream Upstream Server, required) + +Server parameters, specified in the JSON format. +The “ID”, “backup”, and “service” parameters +cannot be changed. + + + +Possible responses: + + +200 - Success, returns Stream Upstream Server +400 - Upstream is static (UpstreamStatic), +invalid “parameter” value (UpstreamConfFormatError), +unknown parameter “name” (UpstreamConfFormatError), +nested object or list (UpstreamConfFormatError), +“error” while parsing (UpstreamBadAddress), +invalid “server” argument (UpstreamBadAddress), +no port in server “host” (UpstreamBadAddress), +invalid server ID (UpstreamBadServerId), +invalid “weight” (UpstreamBadWeight), +invalid “max_conns” (UpstreamBadMaxConns), +invalid “max_fails” (UpstreamBadMaxFails), +invalid “fail_timeout” (UpstreamBadFailTimeout), +invalid “slow_start” (UpstreamBadSlowStart), +“service” is empty (UpstreamBadService), +server “ID” address is immutable (UpstreamServerImmutable), +server “ID” weight is immutable (UpstreamServerWeightImmutable), +upstream “name” memory exhausted (UpstreamOutOfMemory), returns Error +404 - Upstream not found (UpstreamNotFound), +server with ID “id” does not exist (UpstreamServerNotFound), +stream +not configured (StreamNotConfigured), returns Error +415 - JSON error (JsonError), returns Error + + + +DELETE - Remove a server from a stream upstream server group + +Removes a server from a stream server group. + +Possible responses: + + +200 - Success, returns an array of Stream Upstream Servers +400 - Upstream is static (UpstreamStatic), +invalid server ID (UpstreamBadServerId), +server “id” not removable (UpstreamServerImmutable), returns Error +404 - Upstream not found (UpstreamNotFound), +server with ID “id” does not exist (UpstreamServerNotFound), +stream +not configured (StreamNotConfigured), returns Error + + + + + + +

+ + + +nginx: +General information about nginx: + +version (string) + + +Version of nginx. + + +build (string) + + +Name of nginx build. + + +address (string) + + +The address of the server that accepted status request. + + +generation (integer) + + +The total number of configuration +reloads. + + +load_timestamp (string) + + +Time of the last reload of configuration, +in milliseconds since Epoch. + + +timestamp (string) + + +Current time in milliseconds since Epoch. + + +pid (integer) + + +The ID of the worker process that handled status request. + + +ppid (integer) + + +The ID of the master process that started the +worker process. + + +Example: + +{ + "nginx" : { + "version" : "1.13.3", + "build" : "nginx-plus-r12-p3", + "address" : "206.251.255.64", + "generation" : 2, + "load_timestamp" : "2017-07-07T11:09:21.594Z", + "timestamp" : "2017-07-11T09:31:13.477Z", + "pid" : 32212, + "ppid" : 32210 + } +} + + +Processes: + + +respawned (integer) + + +The total number of abnormally terminated +and respawned child processes. + + +Example: + +{ + "respawned" : 0 +} + + +Connections: +The number of accepted, dropped, active, and idle connections. + +accepted (integer) + + +The total number of accepted client connections. + + +dropped (integer) + + +The total number of dropped client connections. + + +active (integer) + + +The current number of active client connections. + + +idle (integer) + + +The current number of idle client connections. + + +Example: + +{ + "accepted" : 4968119, + "dropped" : 0, + "active" : 5, + "idle" : 117 +} + + +SSL: + + +handshakes (integer) + + +The total number of successful SSL handshakes. + + +handshakes_failed (integer) + + +The total number of failed SSL handshakes. + + +session_reuses (integer) + + +The total number of session reuses during SSL handshake. + + +Example: + +{ + "handshakes" : 79572, + "handshakes_failed" : 21025, + "session_reuses" : 15762 +} + + +Shared memory zone with slab allocator: + + +pages + +The number of free and used memory pages. + +used (integer) + + +The current number of used memory pages. + + +free (integer) + + +The current number of free memory pages. + + + + +slots + +Status data for memory slots (8, 16, 32, 64, 128, etc.)A collection of "Memory Slot" objects + + +Example: + +{ + "pages" : { + "used" : 1143, + "free" : 2928 + }, + "slots" : { + "8" : { + "used" : 0, + "free" : 0, + "reqs" : 0, + "fails" : 0 + }, + "16" : { + "used" : 0, + "free" : 0, + "reqs" : 0, + "fails" : 0 + }, + "32" : { + "used" : 0, + "free" : 0, + "reqs" : 0, + "fails" : 0 + }, + "64" : { + "used" : 1, + "free" : 63, + "reqs" : 1, + "fails" : 0 + }, + "128" : { + "used" : 0, + "free" : 0, + "reqs" : 0, + "fails" : 0 + }, + "256" : { + "used" : 18078, + "free" : 178, + "reqs" : 1635736, + "fails" : 0 + } + } +} + + +Memory Slot: + + +used (integer) + + +The current number of used memory slots. + + +free (integer) + + +The current number of free memory slots. + + +reqs (integer) + + +The total number of attempts +to allocate memory of specified size. + + +fails (integer) + + +The number of unsuccessful attempts +to allocate memory of specified size. + + + + +HTTP Requests: + + +total (integer) + + +The total number of client requests. + + +current (integer) + + +The current number of client requests. + + +Example: + +{ + "total" : 10624511, + "current" : 4 +} + + +HTTP Server Zone: + + +processing (integer) + + +The number of client requests +that are currently being processed. + + +requests (integer) + + +The total number of client requests received from clients. + + +responses + +The total number of responses sent to clients and the +number of responses with status codes +“1xx”, “2xx”, “3xx”, +“4xx”, and “5xx”. + +1xx (integer) + + +The number of responses with “1xx” status codes. + + +2xx (integer) + + +The number of responses with “2xx” status codes. + + +3xx (integer) + + +The number of responses with “3xx” status codes. + + +4xx (integer) + + +The number of responses with “4xx” status codes. + + +5xx (integer) + + +The number of responses with “5xx” status codes. + + +total (integer) + + +The total number of responses sent to clients. + + + + +discarded (integer) + + +The total number of +requests completed without sending a response. + + +received (integer) + + +The total number of bytes received from clients. + + +sent (integer) + + +The total number of bytes sent to clients. + + +Example: + +{ + "processing" : 1, + "requests" : 706690, + "responses" : { + "1xx" : 0, + "2xx" : 699482, + "3xx" : 4522, + "4xx" : 907, + "5xx" : 266, + "total" : 705177 + }, + "discarded" : 1513, + "received" : 172711587, + "sent" : 19415530115 +} + + +HTTP Cache: + + +size (integer) + + +The current size of the cache. + + +max_size (integer) + + +The limit on the maximum size of the cache +specified in the configuration. + + +cold (boolean) + + +A boolean value indicating whether the “cache loader” process +is still loading data from disk into the cache. + + +hit + + + +responses (integer) + + +The total number of +valid + responses read from the cache. + + +bytes (integer) + + +The total number of bytes read from the cache. + + + + +stale + + + +responses (integer) + + +The total number of expired responses read from the cache (see +proxy_cache_use_stale +and other “*_cache_use_stale” directives). + + +bytes (integer) + + +The total number of bytes read from the cache. + + + + +updating + + + +responses (integer) + + +The total number of expired responses read from the cache +while responses were being updated (see +proxy_cache_use_stale +and other “*_cache_use_stale” directives). + + +bytes (integer) + + +The total number of bytes read from the cache. + + + + +revalidated + + + +responses (integer) + + +The total number of expired and revalidated responses +read from the cache (see +proxy_cache_revalidate +and other “*_cache_revalidate” directives. + + +bytes (integer) + + +The total number of bytes read from the cache. + + + + +miss + + + +responses (integer) + + +The total number of responses not found in the cache. + + +bytes (integer) + + +The total number of bytes read from the proxied server. + + +responses_written (integer) + + +The total number of responses written to the cache. + + +bytes_written (integer) + + +The total number of bytes written to the cache. + + + + +expired + + + +responses (integer) + + +The total number of expired responses not taken from the cache. + + +bytes (integer) + + +The total number of bytes read from the proxied server. + + +responses_written (integer) + + +The total number of responses written to the cache. + + +bytes_written (integer) + + +The total number of bytes written to the cache. + + + + +bypass + + + +responses (integer) + + +The total number of responses not looked up in the cache due to the +proxy_cache_bypass +and other “*_cache_bypass” directives. + + +bytes (integer) + + +The total number of bytes read from the proxied server. + + +responses_written (integer) + + +The total number of responses written to the cache. + + +bytes_written (integer) + + +The total number of bytes written to the cache. + + + + +Example: + +{ + "size" : 530915328, + "max_size" : 536870912, + "cold" : false, + "hit" : { + "responses" : 254032, + "bytes" : 6685627875 + }, + "stale" : { + "responses" : 0, + "bytes" : 0 + }, + "updating" : { + "responses" : 0, + "bytes" : 0 + }, + "revalidated" : { + "responses" : 0, + "bytes" : 0 + }, + "miss" : { + "responses" : 1619201, + "bytes" : 53841943822 + }, + "expired" : { + "responses" : 45859, + "bytes" : 1656847080, + "responses_written" : 44992, + "bytes_written" : 1641825173 + }, + "bypass" : { + "responses" : 200187, + "bytes" : 5510647548, + "responses_written" : 200173, + "bytes_written" : 44992 + } +} + + +HTTP Upstream: + + +peers + +An array of: + +id (integer) + + +The ID of the server. + + +server (string) + + +An address +of the server. + + +service (string) + + +The +service +parameter value of the +server +directive. + + +name (string) + + +The name of the server specified in the +server +directive. + + +backup (boolean) + + +A boolean value indicating whether the server is a +backup +server. + + +weight (integer) + + +Weight +of the server. + + +state (string) + + +Current state, which may be one of +“up”, “draining”, “down”, +“unavail”, “checking”, +and “unhealthy”. + + +active (integer) + + +The current number of active connections. + + +max_conns (integer) + + +The +max_conns +limit for the server. + + +requests (integer) + + +The total number of client requests forwarded to this server. + + +responses + + + +1xx (integer) + + +The number of responses with “1xx” status codes. + + +2xx (integer) + + +The number of responses with “2xx” status codes. + + +3xx (integer) + + +The number of responses with “3xx” status codes. + + +4xx (integer) + + +The number of responses with “4xx” status codes. + + +5xx (integer) + + +The number of responses with “5xx” status codes. + + +total (integer) + + +The total number of responses obtained from this server. + + + + +sent (integer) + + +The total number of bytes sent to this server. + + +received (integer) + + +The total number of bytes received from this server. + + +fails (integer) + + +The total number of unsuccessful attempts +to communicate with the server. + + +unavail (integer) + + +How many times the server became unavailable for client requests +(state “unavail”) due to the number of unsuccessful +attempts reaching the +max_fails +threshold. + + +health_checks + + + +checks (integer) + + +The total number of +health check +requests made. + + +fails (integer) + + +The number of failed health checks. + + +unhealthy (integer) + + +How many times the server became unhealthy +(state “unhealthy”). + + +last_passed (boolean) + + +Boolean indicating if the last health check request was successful +and passed +tests. + + + + +downtime (integer) + + +Total time the server was in the “unavail”, +“checking”, and “unhealthy” states. + + +downstart (string) + + +The time (in milliseconds since Epoch) when the server became +“unavail”, “checking”, +or “unhealthy”. + + +selected (string) + + +The time (in milliseconds since Epoch) +when the server was last selected to process a request. + + +header_time (integer) + + +The average time to get the +response header +from the server. + + +response_time (integer) + + +The average time to get the +full response +from the server. + + + + +keepalive (integer) + + +The current number of idle +keepalive +connections. + + +zombies (integer) + + +The current number of servers removed +from the group but still processing active client requests. + + +zone (string) + + +The name of the shared memory +zone +that keeps the group’s configuration and run-time state. + + +queue + +For the requests +queue, +the following data are provided: + +size (integer) + + +The current number of requests in the queue. + + +max_size (integer) + + +The maximum number of requests that can be in the queue +at the same time. + + +overflows (integer) + + +The total number of requests rejected due to the queue overflow. + + + + +Example: + +{ + "upstream_backend" : { + "peers" : [ + { + "id" : 0, + "server" : "10.0.0.1:8088", + "name" : "10.0.0.1:8088", + "backup" : false, + "weight" : 5, + "state" : "up", + "active" : 0, + "max_conns" : 20, + "requests" : 667231, + "header_time" : 20, + "response_time" : 36, + "responses" : { + "1xx" : 0, + "2xx" : 666310, + "3xx" : 0, + "4xx" : 915, + "5xx" : 6, + "total" : 667231 + }, + "sent" : 251946292, + "received" : 19222475454, + "fails" : 0, + "unavail" : 0, + "health_checks" : { + "checks" : 26214, + "fails" : 0, + "unhealthy" : 0, + "last_passed" : true + }, + "downtime" : 0, + "downstart" : "2017-07-07T11:09:21.602Z", + "selected" : "2017-07-17T15:01:25.000Z" + }, + { + "id" : 1, + "server" : "10.0.0.1:8089", + "name" : "10.0.0.1:8089", + "backup" : true, + "weight" : 1, + "state" : "unhealthy", + "active" : 0, + "max_conns" : 20, + "requests" : 0, + "responses" : { + "1xx" : 0, + "2xx" : 0, + "3xx" : 0, + "4xx" : 0, + "5xx" : 0, + "total" : 0 + }, + "sent" : 0, + "received" : 0, + "fails" : 0, + "unavail" : 0, + "health_checks" : { + "checks" : 26284, + "fails" : 26284, + "unhealthy" : 1, + "last_passed" : false + }, + "downtime" : 262925617, + "downstart" : "2017-07-07T11:09:21.602Z", + "selected" : "2017-07-17T15:01:25.000Z" + } + ], + "keepalive" : 0, + "zombies" : 0, + "zone" : "upstream_backend" + } +} + + +HTTP Upstream Server: +Dynamically configurable parameters of an HTTP upstream +server: + +id (integer) + + +The ID of the HTTP upstream server. +The ID is assigned automatically and cannot be changed. + + +server (string) + + +Same as the +address +parameter of the HTTP upstream server. +When adding a server, it is possible to specify it as a domain name. +In this case, changes of the IP addresses +that correspond to a domain name will be monitored and automatically +applied to the upstream configuration +without the need of restarting nginx. +This requires the +resolver +directive in the “http” block. +See also the +resolve +parameter of the HTTP upstream server. + + +service (string) + + +Same as the +service +parameter of the HTTP upstream server. +This parameter cannot be changed. + + +weight (integer) + + +Same as the +weight +parameter of the HTTP upstream server. + + +max_conns (integer) + + +Same as the +max_conns +parameter of the HTTP upstream server. + + +max_fails (integer) + + +Same as the +max_fails +parameter of the HTTP upstream server. + + +fail_timeout (integer) + + +Same as the +fail_timeout +parameter of the HTTP upstream server. + + +slow_start (integer) + + +Same as the +slow_start +parameter of the HTTP upstream server. + + +route (string) + + +Same as the +route +parameter of the HTTP upstream server. + + +backup (boolean) + + +When true, adds a +backup +server. +This parameter cannot be changed. + + +down (boolean) + + +Same as the +down +parameter of the HTTP upstream server. + + +parent (string) + + +Parent server ID of the resolved server. +The ID is assigned automatically and cannot be changed. + + +host (string) + + +Hostname of the resolved server. +The hostname is assigned automatically and cannot be changed. + + +drain (string) + + +Puts the HTTP upstream server into the “draining” mode. +In this mode, only requests +bound +to the server will be proxied to it. +The parameter cannot be initially set, +it can only be changed with the PATCH method. + + +Example: + +{ + "id" : 1, + "server" : "10.0.0.1:8089", + "weight" : 4, + "max_conns" : 0, + "max_fails" : 0, + "fail_timeout" : "10s", + "slow_start" : "10s", + "route" : "", + "backup" : true, + "down" : true +} + + +Keyval Shared Memory Zone: +Contents of a keyval shared memory zone.Example: + +{ + "key1" : "value1", + "key2" : "value2", + "key3" : "value3" +} + + +Stream Server Zone: + + +processing (integer) + + +The number of client connections +that are currently being processed. + + +connections (integer) + + +The total number of connections accepted from clients. + + +sessions + +Total number of completed sessions, +and the number of sessions completed with status codes +“2xx”, “4xx”, or “5xx”. + +2xx (integer) + + +The total number of sessions completed with +status codes +“2xx”. + + +4xx (integer) + + +The total number of sessions completed with +status codes +“4xx”. + + +5xx (integer) + + +The total number of sessions completed with +status codes +“5xx”. + + +total (integer) + + +The total number of completed client sessions. + + + + +discarded (integer) + + +The total number of +connections completed without creating a session. + + +received (integer) + + +The total number of bytes received from clients. + + +sent (integer) + + +The total number of bytes sent to clients. + + +Example: + +{ + "dns" : { + "processing" : 1, + "connections" : 155569, + "sessions" : { + "2xx" : 155564, + "4xx" : 0, + "5xx" : 0, + "total" : 155569 + }, + "discarded" : 0, + "received" : 4200363, + "sent" : 20489184 + } +} + + +Stream Upstream: + + +peers + +An array of: + +id (integer) + + +The ID of the server. + + +server (string) + + +An +address +of the server. + + +service (string) + + +The +service +parameter value of the +server +directive. + + +name (string) + + +The name of the server specified in the +server +directive. + + +backup (boolean) + + +A boolean value indicating whether the server is a +backup +server. + + +weight (integer) + + +Weight +of the server. + + +state (string) + + +Current state, which may be one of +“up”, “down”, “unavail”, +“checking”, or “unhealthy”. + + +active (integer) + + +The current number of connections. + + +max_conns (integer) + + +The +max_conns +limit for the server. + + +connections (integer) + + +The total number of client connections forwarded to this server. + + +connect_time (integer) + + +The average time to connect to the upstream server. + + +first_byte_time (integer) + + +The average time to receive the first byte of data. + + +response_time (integer) + + +The average time to receive the last byte of data. + + +sent (integer) + + +The total number of bytes sent to this server. + + +received (integer) + + +The total number of bytes received from this server. + + +fails (integer) + + +The total number of unsuccessful attempts +to communicate with the server. + + +unavail (integer) + + +How many times the server became unavailable for client connections +(state “unavail”) due to the number of unsuccessful +attempts reaching the +max_fails +threshold. + + +health_checks + + + +checks (integer) + + +The total number of +health check +requests made. + + +fails (integer) + + +The number of failed health checks. + + +unhealthy (integer) + + +How many times the server became unhealthy +(state “unhealthy”). + + +last_passed (boolean) + + +Boolean indicating whether the last health check request +was successful and passed +tests. + + + + +downtime (integer) + + +Total time the server was in the +“unavail”, “checking”, +and “unhealthy” states. + + +downstart (string) + + +The time (in milliseconds since Epoch) when the server became +“unavail”, “checking”, +or “unhealthy”. + + +selected (string) + + +The time (in milliseconds since Epoch) +when the server was last selected to process a connection. + + + + +zombies (integer) + + +The current number of servers removed from the group +but still processing active client connections. + + +zone (string) + + +The name of the shared memory +zone +that keeps the group’s configuration and run-time state. + + +Example: + +{ + "dns" : { + "peers" : [ + { + "id" : 0, + "server" : "10.0.0.1:12347", + "name" : "10.0.0.1:12347", + "backup" : false, + "weight" : 5, + "state" : "up", + "active" : 0, + "max_conns" : 50, + "connections" : 667231, + "sent" : 251946292, + "received" : 19222475454, + "fails" : 0, + "unavail" : 0, + "health_checks" : { + "checks" : 26214, + "fails" : 0, + "unhealthy" : 0, + "last_passed" : true + }, + "downtime" : 0, + "downstart" : "2017-07-07T11:09:21.602Z", + "selected" : "2017-07-17T15:01:25.000Z" + }, + { + "id" : 1, + "server" : "10.0.0.1:12348", + "name" : "10.0.0.1:12348", + "backup" : true, + "weight" : 1, + "state" : "unhealthy", + "active" : 0, + "max_conns" : 50, + "connections" : 0, + "sent" : 0, + "received" : 0, + "fails" : 0, + "unavail" : 0, + "health_checks" : { + "checks" : 26284, + "fails" : 26284, + "unhealthy" : 1, + "last_passed" : false + }, + "downtime" : 262925617, + "downstart" : "2017-07-07T11:09:21.602Z", + "selected" : "2017-07-17T15:01:25.000Z" + } + ], + "zombies" : 0, + "zone" : "dns" + } +} + + +Stream Upstream Server: +Dynamically configurable parameters of a stream upstream +server: + +id (integer) + + +The ID of the stream upstream server. +The ID is assigned automatically and cannot be changed. + + +server (string) + + +Same as the +address +parameter of the stream upstream server. +When adding a server, it is possible to specify it as a domain name. +In this case, changes of the IP addresses +that correspond to a domain name will be monitored and automatically +applied to the upstream configuration +without the need of restarting nginx. +This requires the +resolver +directive in the “stream” block. +See also the +resolve +parameter of the stream upstream server. + + +service (string) + + +Same as the +service +parameter of the stream upstream server. +This parameter cannot be changed. + + +weight (integer) + + +Same as the +weight +parameter of the stream upstream server. + + +max_conns (integer) + + +Same as the +max_conns +parameter of the stream upstream server. + + +max_fails (integer) + + +Same as the +max_fails +parameter of the stream upstream server. + + +fail_timeout (integer) + + +Same as the +fail_timeout +parameter of the stream upstream server. + + +slow_start (integer) + + +Same as the +slow_start +parameter of the stream upstream server. + + +backup (boolean) + + +When true, adds a +backup +server. +This parameter cannot be changed. + + +down (boolean) + + +Same as the +down +parameter of the stream upstream server. + + +parent (string) + + +Parent server ID of the resolved server. +The ID is assigned automatically and cannot be changed. + + +host (string) + + +Hostname of the resolved server. +The hostname is assigned automatically and cannot be changed. + + +Example: + +{ + "id" : 0, + "server" : "10.0.0.1:12348", + "weight" : 1, + "max_conns" : 0, + "max_fails" : 1, + "fail_timeout" : "10s", + "slow_start" : 0, + "backup" : false, + "down" : false +} + + +Error: +nginx error object. + +path (string) + + +API path. + + +method (string) + + +HTTP method. + + +error + + + +status (string) + + +HTTP error code. + + +text (string) + + +Error description. + + +code (string) + + +Internal nginx error code. + + + + +request_id (string) + + +The ID of the request, equals the value of the +$request_id +variable. + + +href (string) + + +Link to reference documentation. + + + + + +

+ +