W3cubDocs

/nginx

Module ngx_http_api_module

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.

Example Configuration

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/2/
http://127.0.0.1/api/2/nginx
http://127.0.0.1/api/2/connections
http://127.0.0.1/api/2/http/requests
http://127.0.0.1/api/2/http/server_zones/server_backend
http://127.0.0.1/api/2/http/caches/cache_backend
http://127.0.0.1/api/2/http/upstreams/backend
http://127.0.0.1/api/2/http/upstreams/backend/servers/
http://127.0.0.1/api/2/http/upstreams/backend/servers/1
http://127.0.0.1/api/2/http/keyvals/one?key=arg1
http://127.0.0.1/api/2/stream/
http://127.0.0.1/api/2/stream/server_zones/server_backend
http://127.0.0.1/api/2/stream/upstreams/
http://127.0.0.1/api/2/stream/upstreams/backend
http://127.0.0.1/api/2/stream/upstreams/backend/servers/1

Directives

Syntax: api [write=on|off];
Default:
Context: 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 API version is “2”.

The optional “fields” argument in the request line specifies which fields of the requested objects will be output:

http://127.0.0.1/api/2/nginx?fields=version,build

Compatibility

Endpoints

/

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:

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

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

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

  • 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
    • 405 - Method disabled (MethodDisabled), 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:

  • DELETE - Reset HTTP requests statistics

    Resets the number of total client HTTP requests.

    Possible responses:

    • 204 - Success
    • 405 - Method disabled (MethodDisabled), returns Error
/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
    • 405 - Method disabled (MethodDisabled), 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
    • 405 - Method disabled (MethodDisabled), 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
    • 405 - Method disabled (MethodDisabled), 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
    • 405 - Method disabled (MethodDisabled), 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
    • 405 - Method disabled (MethodDisabled), 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
    • 405 - Method disabled (MethodDisabled), returns Error
/http/keyvals/

Supported methods:

  • GET - Return key-value pairs from all HTTP keyval zones

    Returns key-value pairs for each HTTP keyval shared memory zone.

    Request parameters:

    fields (string, optional)
    If the “fields” value is empty, then only HTTP keyval zone names are output.

    Possible responses:

/http/keyvals/{httpKeyvalZoneName}
Parameters common for all methods:
httpKeyvalZoneName (string, required)
The name of an HTTP keyval shared memory zone.

Supported methods:

  • GET - Return key-value pairs from an HTTP keyval zone

    Returns key-value pairs stored in a particular HTTP keyval shared memory zone.

    Request parameters:

    key (string, optional)
    Get a particular key-value pair from the HTTP keyval zone.

    Possible responses:

  • POST - Add a key-value pair to the HTTP keyval zone

    Adds a new key-value pair to the HTTP keyval shared memory zone. Several key-value pairs can be entered if the HTTP keyval shared memory zone is empty.

    Request parameters:

    Key-value (HTTP Keyval Shared Memory Zone, required)
    A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the HTTP 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
    • 405 - Method disabled (MethodDisabled), 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 (HTTP 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
    • 405 - Method disabled (MethodDisabled), returns Error
    • 415 - JSON error (JsonError), returns Error
  • DELETE - Empty the HTTP keyval zone

    Deletes all key-value pairs from the HTTP keyval shared memory zone.

    Possible responses:

    • 204 - Success
    • 404 - Keyval not found (KeyvalNotFound), returns Error
    • 405 - Method disabled (MethodDisabled), 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
    • 405 - Method disabled (MethodDisabled), 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
    • 405 - Method disabled (MethodDisabled), 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
    • 405 - Method disabled (MethodDisabled), 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
    • 405 - Method disabled (MethodDisabled), 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
    • 405 - Method disabled (MethodDisabled), returns Error
/stream/keyvals/

Supported methods:

  • GET - Return key-value pairs from all stream keyval zones

    Returns key-value pairs for each stream keyval shared memory zone.

    Request parameters:

    fields (string, optional)
    If the “fields” value is empty, then only stream keyval zone names are output.

    Possible responses:

/stream/keyvals/{streamKeyvalZoneName}
Parameters common for all methods:
streamKeyvalZoneName (string, required)
The name of a stream keyval shared memory zone.

Supported methods:

  • GET - Return key-value pairs from a stream keyval zone

    Returns key-value pairs stored in a particular stream keyval shared memory zone.

    Request parameters:

    key (string, optional)
    Get a particular key-value pair from the stream keyval zone.

    Possible responses:

  • POST - Add a key-value pair to the stream keyval zone

    Adds a new key-value pair to the stream keyval shared memory zone. Several key-value pairs can be entered if the stream keyval shared memory zone is empty.

    Request parameters:

    Key-value (Stream Keyval Shared Memory Zone, required)
    A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the stream 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), stream not configured (StreamNotConfigured), returns Error
    • 405 - Method disabled (MethodDisabled), 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:

    streamKeyvalZoneKeyValue (Stream 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), stream not configured (StreamNotConfigured), returns Error
    • 405 - Method disabled (MethodDisabled), returns Error
    • 415 - JSON error (JsonError), returns Error
  • DELETE - Empty the stream keyval zone

    Deletes all key-value pairs from the stream keyval shared memory zone.

    Possible responses:

    • 204 - Success
    • 404 - Keyval not found (KeyvalNotFound), stream not configured (StreamNotConfigured), returns Error
    • 405 - Method disabled (MethodDisabled), returns Error

Response Objects

  • 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.
    drain (boolean)
    Same as the drain 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.

    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
    }
  • HTTP Keyval Shared Memory Zone:

    Contents of an HTTP 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
    The 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 codes2xx”.
    4xx (integer)
    The total number of sessions completed with status codes4xx”.
    5xx (integer)
    The total number of sessions completed with status codes5xx”.
    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
    }
  • Stream Keyval Shared Memory Zone:

    Contents of a stream keyval shared memory zone.

    Example:

    {
      "key1" : "value1",
      "key2" : "value2",
      "key3" : "value3"
    }
  • 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.

© 2002-2017 Igor Sysoev
© 2011-2017 Nginx, Inc.
Licensed under the BSD License.
https://nginx.org/en/docs/http/ngx_http_api_module.html