API#
Implements an HTTP RESTful interface for obtaining basic information about the web server in JSON format, as well as statistics on client connections, shared memory zones, DNS queries, HTTP requests, HTTP response cache, Stream module sessions, and zones of the HTTP Limit Conn, Stream Limit Conn, Limit Req, and HTTP Upstream modules, as well as information about certificates specified in the configuration and obtained by ACME clients.
The Console Light panel queries this module's HTTP
interface; the Prometheus module reads the same
/status/ tree inside Angie and needs no api location.
Machine-readable OpenAPI 3.1 specifications of this interface are available for Angie and Angie PRO.
Note
Explore a live example of the API output at https://console.angie.software/api/.
Apart from the dynamic configuration section in Angie PRO,
the API accepts only the GET and HEAD HTTP methods. A failed request returns a
JSON object with an error code and its description; a request with another
method fails with the 405 status code:
{
"error": "MethodNotAllowed",
"description": "The POST method is not allowed for the requested API entity \"/\"."
}
A request for a path that does not exist fails with the 404 status code and
the PathNotFound error code.
In Angie PRO, this interface includes a dynamic configuration section that allows changing settings without reloading the configuration or restarting; currently, configuration of individual servers within upstream is available.
When building from the source code, the module is built by
default; it can be disabled with the build option
--without-http_api_module.
In packages and images from our repositories, the module is included in the build.
Related guides
Console Light Web Panel: reads this module's
/status/tree.First Steps: enables a local-only
/status/location.Configuring OIDC: puts
/status/behind an OIDC login.Custom Metrics: custom zones appear in the
metric_zonesbranch.Grafana Dashboard: its metrics come from
/status/.
Directives#
api#
Enables the HTTP RESTful interface in location.
The path parameter is mandatory. Similar to the alias directive, it sets the path for replacing the one specified in location, but over the API tree rather than the filesystem.
If specified in a prefix location:
location /stats/ {
api /status/http/server_zones/;
}
the part of the request URI matching the prefix /stats/ will be replaced with the path specified in the path parameter: /status/http/server_zones/. For example, a request to /stats/foo/ will access the API element /status/http/server_zones/foo/.
Variables are allowed: api /status/$module/server_zones/$name/ and usage inside regex location:
location ~^/api/([^/]+)/(.*)$ {
api /status/http/$1_zones/$2;
}
Here the path parameter defines the full path to the API element;
thus, from a request to /api/location/data/ the following variables will be extracted:
$1 = "location"
$2 = "data/"
And the final request will be /status/http/location_zones/data/.
Note
In Angie PRO, you can separate the dynamic configuration API and the immutable status API that reflects the current state:
location /config/ {
api /config/;
}
location /status/ {
api /status/;
}
The path parameter also allows controlling API access:
location /status/ {
api /status/;
allow 127.0.0.1;
deny all;
}
Or:
location /blog/requests/ {
api /status/http/server_zones/blog/requests/;
auth_basic "blog";
auth_basic_user_file conf/htpasswd;
}
Note
If api is placed in a location with a trailing slash in the prefix
(for example, location /name/),
and the auto_redirect directive is set to default,
requests without a trailing slash will be redirected (/name -> /name/).
api_config_files#
Enables or disables adding the config_files object,
which lists the contents of all Angie configuration files
currently loaded by the server instance,
to the /status/angie/ API section.
For example, with this configuration:
location /status/ {
api /status/;
api_config_files on;
}
A request to /status/angie/ returns approximately the following:
{
"version":"1.12.4",
"address":"192.168.16.5",
"generation":1,
"load_time":"2026-10-16T12:58:39.789Z",
"config_files": {
"/etc/angie/angie.conf": "...",
"/etc/angie/mime.types": "..."
}
}
By default, output is disabled because configuration files may contain particularly sensitive, confidential information.
Metrics#
Angie publishes usage statistics in the /status/ API section; you can
open access to it by setting the appropriate location. Full access:
location /status/ {
api /status/;
}
Example of partial access, already shown above:
location /stats/ {
api /status/http/server_zones/;
}
Example configuration#
With a configuration including location /status/, resolver, http in
upstream, http server, location, cache, limit_conn in
http and limit_req zones:
http {
resolver 127.0.0.53 status_zone=resolver_zone;
proxy_cache_path /var/cache/angie/cache keys_zone=cache_zone:2m;
limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;
upstream upstream {
zone upstream 256k;
server backend.example.com service=_example._tcp resolve max_conns=5;
keepalive 4;
}
server {
server_name www.example.com;
listen 443 ssl;
status_zone http_server_zone;
proxy_cache cache_zone;
proxy_cache_valid 200 10m;
access_log /var/log/access.log main;
location / {
root /usr/share/angie/html;
status_zone location_zone;
limit_conn limit_conn_zone 1;
limit_req zone=limit_req_zone burst=5;
}
location /status/ {
api /status/;
allow 127.0.0.1;
deny all;
}
}
}
In response to the request curl https://www.example.com/status/, Angie returns:JSON tree
{
"angie": {
"version":"1.12.4",
"address":"192.168.16.5",
"generation":1,
"load_time":"2026-10-16T12:58:39.789Z"
},
"connections": {
"accepted":2257,
"dropped":0,
"active":3,
"idle":1
},
"slabs": {
"cache_zone": {
"pages": {
"used":2,
"free":506
},
"slots": {
"64": {
"used":1,
"free":63,
"reqs":1,
"fails":0
},
"512": {
"used":1,
"free":7,
"reqs":1,
"fails":0
}
}
},
"limit_conn_zone": {
"pages": {
"used":2,
"free":2542
},
"slots": {
"64": {
"used":1,
"free":63,
"reqs":74,
"fails":0
},
"128": {
"used":1,
"free":31,
"reqs":1,
"fails":0
}
}
},
"limit_req_zone": {
"pages": {
"used":2,
"free":2542
},
"slots": {
"64": {
"used":1,
"free":63,
"reqs":1,
"fails":0
},
"128": {
"used":2,
"free":30,
"reqs":3,
"fails":0
}
}
}
},
"http": {
"server_zones": {
"http_server_zone": {
"ssl": {
"handshaked":4174,
"reuses":0,
"timedout":0,
"failed":0
},
"requests": {
"total":4327,
"processing":0,
"discarded":8
},
"responses": {
"200":4305,
"302":12,
"404":4
},
"data": {
"received":733955,
"sent":59207757
}
}
},
"location_zones": {
"location_zone": {
"requests": {
"total":4158,
"discarded":0
},
"responses": {
"200":4157,
"304":1
},
"data": {
"received":538200,
"sent":177606236
}
}
},
"caches": {
"cache_zone": {
"size":0,
"cold":false,
"hit": {
"responses":0,
"bytes":0
},
"stale": {
"responses":0,
"bytes":0
},
"updating": {
"responses":0,
"bytes":0
},
"revalidated": {
"responses":0,
"bytes":0
},
"miss": {
"responses":0,
"bytes":0,
"responses_written":0,
"bytes_written":0
},
"expired": {
"responses":0,
"bytes":0,
"responses_written":0,
"bytes_written":0
},
"bypass": {
"responses":0,
"bytes":0,
"responses_written":0,
"bytes_written":0
}
}
},
"limit_conns": {
"limit_conn_zone": {
"passed":73,
"skipped":0,
"rejected":0,
"exhausted":0
}
},
"limit_reqs": {
"limit_req_zone": {
"passed":54816,
"skipped":0,
"delayed":65,
"rejected":26,
"exhausted":0
}
},
"upstreams": {
"upstream": {
"peers": {
"192.168.16.4:80": {
"server":"backend.example.com",
"service":"_example._tcp",
"backup":false,
"weight":5,
"state":"up",
"selected": {
"current":2,
"total":232
},
"max_conns":5,
"responses": {
"200":222,
"302":12
},
"data": {
"sent":543866,
"received":27349934
},
"health": {
"fails":0,
"unavailable":0,
"downtime":0,
"header_time":21,
"response_time":42
},
"sid":"<server_id>"
}
},
"keepalive":2
}
}
},
"resolvers": {
"resolver_zone": {
"queries": {
"name":442,
"srv":2,
"addr":0
},
"responses": {
"success":440,
"timedout":1,
"format_error":0,
"server_failure":1,
"not_found":1,
"unimplemented":0,
"refused":1,
"other":0
}
}
}
}
A set of metrics can be requested by individual JSON branch by constructing the appropriate request. For example:
$ curl https://www.example.com/status/angie
$ curl https://www.example.com/status/connections
$ curl https://www.example.com/status/slabs
$ curl https://www.example.com/status/slabs/<zone>/slots
$ curl https://www.example.com/status/slabs/<zone>/slots/64
$ curl https://www.example.com/status/http/
$ curl https://www.example.com/status/http/acme_clients
$ curl https://www.example.com/status/http/acme_clients/<client>
$ curl https://www.example.com/status/http/metric_zones
$ curl https://www.example.com/status/http/metric_zones/<zone>/metrics
$ curl https://www.example.com/status/http/server_zones
$ curl https://www.example.com/status/http/server_zones/<http_server_zone>
$ curl https://www.example.com/status/http/server_zones/<http_server_zone>/ssl
Query arguments#
The following query-string arguments modify the API's JSON responses:
prettyBy default, the API formats JSON responses with indentation and line breaks. To get compact, single-line output, add
pretty=offto the query string:$ curl https://www.example.com/status/connections?pretty=off {"accepted":2257,"dropped":0,"active":3,"idle":1}
dateBy default, the module uses ISO 8601 format strings for dates; to use the integer UNIX epoch format instead, add
date=epochto the query string:$ curl https://www.example.com/status/angie/load_time "2024-03-31T23:59:59Z" $ curl https://www.example.com/status/angie/load_time?date=epoch 1711929599
The string form is always UTC and carries milliseconds only when they are non-zero. The epoch form is a whole number of seconds; milliseconds are never part of it.
defaults(PRO)A
GETrequest to the dynamic configuration section omits the fields that keep their default values; to include them, adddefaults=onto the query string:$ curl http://127.0.0.1/config/http/upstreams/backend/servers?defaults=on
{ "backend.example.com": { "weight": 1, "max_conns": 5, "max_fails": 1, "fail_timeout": 10, "slow_start": 0, "backup": false, "down": false, "sid": "" } }
connection_drop(PRO)When a request to the dynamic configuration section removes an upstream server, this argument sets what happens to the active connections to that server:
oncloses them immediately,offleaves them open, and a time value closes them after that timeout. The argument overrides proxy_connection_drop, grpc_connection_drop, fastcgi_connection_drop, scgi_connection_drop, and uwsgi_connection_drop in HTTP and proxy_connection_drop in stream; an invalid value is ignored, and the directive's setting applies:$ curl -X DELETE \ http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com?connection_drop=off $ curl -X DELETE \ http://127.0.0.1/config/http/upstreams/backend/servers/backend2.example.com?connection_drop=on $ curl -X DELETE \ http://127.0.0.1/config/http/upstreams/backend/servers/backend3.example.com?connection_drop=10s
Server status#
/status/angie#
{
"version": "1.12.4",
"build_time": "2026-10-16T16:05:43.805Z",
"address": "192.168.16.5",
"generation": 1,
"load_time": "2026-10-16T16:15:43.805Z",
"config_files": {
"/etc/angie/angie.conf": "...",
"/etc/angie/mime.types": "..."
}
}
| String; version of the running Angie web server |
| String; particular build name if specified during compilation |
| String or number; the build time of the Angie executable in the date format |
| String; the address of the server that accepted the API request |
| Number; the generation of the currently loaded configuration, counted from the last start of Angie |
| String or number; time of the last configuration reload in the date format |
| Object; its members are absolute pathnames of all Angie configuration files that are currently loaded by the server instance, and their values are string representations of the files' contents, for example: {
"/etc/angie/angie.conf": "server {\n listen 80;\n # ...\n\n}\n"
}
Warning The |
/status/angie/license (PRO)#
Added in version 1.11.0: PRO
{
"path": "/etc/angie/license.pem",
"status": "valid",
"owner": "CN=Example Corp",
"days_left": 30,
"since": "Jan 1 00:00:00 2026 GMT",
"until": "Jan 1 00:00:00 2027 GMT",
"limits": {
"worker_processes": 16,
"worker_connections": 65535
}
}
| String; full path to the license file |
| String; license status: |
| String; license owner: the subject of the license certificate as an RFC 2253 distinguished name |
| Number; days until the license changes state. A negative value means the license has expired, and the value is the number of days since expiration |
| String; license validity start, in the OpenSSL time format,
for example |
| String; license validity end, in the same format as |
| Object; licensed limits for the current instance |
| Number; the largest worker_processes value the license allows; 0 means no limit |
| Number; the largest worker_connections value the license allows; 0 means no limit |
Connections#
/status/connections#
{
"accepted": 2257,
"dropped": 0,
"active": 3,
"idle": 1
}
| Number; the total number of accepted client connections |
| Number; the total number of dropped client connections |
| Number; the current number of active client connections |
| Number; the current number of idle client connections |
DNS queries to resolver#
/status/resolvers/<zone>#
To collect resolver statistics,
the resolver directive must set the status_zone parameter
(HTTP or Stream):
resolver 127.0.0.53 status_zone=resolver_zone;
The specified shared memory zone will collect the following statistics:
| Object; queries statistics |
| Number; the number of queries to resolve names to addresses (A and AAAA queries) |
| Number; the number of queries to resolve services to addresses (SRV queries) |
| Number; the number of queries to resolve addresses to names (PTR queries) |
| Object; responses statistics |
| Number; the number of successful responses |
| Number; the number of timed out queries |
| Number; the number of responses with code 1 (Format Error) |
| Number; the number of responses with code 2 (Server Failure) |
| Number; the number of responses with code 3 (Name Error) |
| Number; the number of responses with code 4 (Not Implemented) |
| Number; the number of responses with code 5 (Refused) |
| Number; the number of queries completed with other non-zero code |
| Object; sent DNS queries statistics |
| Number; the number of A type queries |
| Number; the number of AAAA type queries |
| Number; the number of PTR type queries |
| Number; the number of SRV type queries |
Note
queries and responses count every resolution request
Angie makes internally, including those served from the TTL cache.
sent counts packets actually dispatched to the name server;
the gap between the two reflects cache hits.
The response codes are described in RFC 1035, section 4.1.1.
Various DNS record types are detailed in RFC 1035, RFC 2782, and RFC 3596.
Example:
{
"queries": {
"name": 442,
"srv": 2,
"addr": 0
},
"responses": {
"success": 440,
"timedout": 1,
"format_error": 0,
"server_failure": 1,
"not_found": 1,
"unimplemented": 0,
"refused": 1,
"other": 0
},
"sent": {
"a": 185,
"aaaa": 245,
"srv": 2,
"ptr": 12
}
}
HTTP server and location#
/status/http/server_zones/<zone>#
To collect the server metrics,
set the status_zone directive in the server context:
server {
...
status_zone server_zone;
}
To group the metrics by a custom value, use the alternative syntax. Here, the metrics are aggregated by $host, with each group reported as a standalone zone:
status_zone $host zone=server_host_zone:5;
The number after the zone name is a limit on groups, not a memory size (see status_zone); metrics for values beyond the limit are reported under the zone name itself.
A request counted in a server zone is also counted in a location zone if the location where its processing ends has one; see Server and location zones.
The specified shared memory zone will collect the following statistics:
| Object; SSL statistics.
Present if |
| Number; the total number of successful SSL handshakes |
| Number; the total number of session reuses during SSL handshake |
| Number; the total number of timed out SSL handshakes |
| Number; the total number of failed SSL handshakes |
| Object; requests statistics |
| Number; the total number of client requests |
| Number; the number of currently being processed client requests |
| Number; the total number of client requests completed without sending a response |
| Object; responses statistics |
| Number; a non-zero number of responses with status <code> (100-599) |
| Number; a non-zero number of responses with other status codes |
| Object; data statistics |
| Number; the total number of bytes received from clients |
| Number; the total number of bytes sent to clients |
Note
The responses counters track only real responses that were actually
sent to the client. A request whose processing finished without sending a
response is counted in discarded and does not increment the
responses counters. In particular, 499 is not a response but
an internal service code, recorded only in the access log, that marks a
request whose processing ended without a response being sent; such requests
are reflected in discarded, never in responses.
Example:
{
"ssl":{
"handshaked":4174,
"reuses":0,
"timedout":0,
"failed":0
},
"requests":{
"total":4327,
"processing":0,
"discarded":0
},
"responses":{
"200":4305,
"302":6,
"304":12,
"404":4
},
"data":{
"received":733955,
"sent":59207757
}
}
/status/http/location_zones/<zone>#
To collect the location metrics, set the status_zone directive
in the context of location or if in location:
location / {
root /usr/share/angie/html;
status_zone location_zone;
if ($request_uri ~* "^/condition") {
# ...
status_zone if_location_zone;
}
}
To group the metrics by a custom value, use the alternative syntax. Here, the metrics are aggregated by $host, with each group reported as a standalone zone:
status_zone $host zone=location_host_zone:5;
The number after the zone name is a limit on groups, not a memory size (see status_zone); metrics for values beyond the limit are reported under the zone name itself.
A request counted in a location zone is also counted in a server zone if its server has one; see Server and location zones.
The specified shared memory zone will collect the following statistics:
| Object; requests statistics |
| Number; the total number of client requests |
| Number; the total number of client requests completed without sending a response |
| Object; responses statistics |
| Number; a non-zero number of responses with status <code> (100-599) |
| Number; a non-zero number of responses with other status codes |
| Object; data statistics |
| Number; the total number of bytes received from clients |
| Number; the total number of bytes sent to clients |
Note
The responses counters track only real responses that were actually
sent to the client. A request whose processing finished without sending a
response is counted in discarded and does not increment the
responses counters. In particular, 499 is not a response but
an internal service code, recorded only in the access log, that marks a
request whose processing ended without a response being sent; such requests
are reflected in discarded, never in responses.
Example:
{
"requests": {
"total": 4158,
"discarded": 0
},
"responses": {
"200": 4157,
"304": 1
},
"data": {
"received": 538200,
"sent": 177606236
}
}
/status/http/metric_zones/<zone>#
Custom metrics defined by metric_zone or metric_complex_zone
in the http context. Metrics are updated with the metric
directive or the module variables.
| Number; the number of metric entries discarded because the zone ran out of memory. |
| Object; metrics per key. For single-metric zones, values are numbers. For complex zones, values are objects with metric names. For histogram mode, values are objects with bucket names. |
If discard_key is set and some entries have been expired,
their aggregated metrics are exposed under this key.
Example:
{
"discarded": 3,
"metrics": {
"example.com": {
"count": 42,
"max": 8
},
"expired": {
"count": 10,
"max": 3.2
}
}
}
Stream server#
/status/stream/server_zones/<zone>#
To collect the server metrics,
set the status_zone directive in the server context:
server {
...
status_zone server_zone;
}
To group the metrics by a custom value, use the alternative syntax. Here, the metrics are aggregated by $server_addr, with each group reported as a standalone zone:
status_zone $server_addr zone=server_zone:5;
The specified shared memory zone will collect the following statistics:
| Object; SSL statistics.
Present if |
| Number; the total number of successful SSL handshakes |
| Number; the total number of session reuses during SSL handshake |
| Number; the total number of timed out SSL handshakes |
| Number; the total number of failed SSL handshakes |
| Object; connections statistics |
| Number; the total number of client connections |
| Number; the number of currently being processed client connections |
| Number; the total number of client connections completed without creating a session |
| Number; the total number of client connections
relayed to another listening port with |
| Object; sessions statistics |
| Number; the number of sessions completed with code 200, which means successful completion |
| Number; the number of sessions completed with code 400, which happens when client data could not be parsed, e.g. the PROXY protocol header |
| Number; the number of sessions completed with code 403, when access was forbidden, for example, when access is limited for certain client addresses |
| Number; the number of sessions completed with code 500, the internal server error |
| Number; the number of sessions completed with code 502, bad gateway, for example, if an upstream server could not be selected or reached |
| Number; the number of sessions completed with code 503, service unavailable, for example, when access is limited by the number of connections |
| Object; data statistics |
| Number; the total number of bytes received from clients |
| Number; the total number of bytes sent to clients |
Example:
{
"ssl": {
"handshaked": 24,
"reuses": 0,
"timedout": 0,
"failed": 0
},
"connections": {
"total": 24,
"processing": 1,
"discarded": 0,
"passed": 2
},
"sessions": {
"success": 24,
"invalid": 0,
"forbidden": 0,
"internal_error": 0,
"bad_gateway": 0,
"service_unavailable": 0
},
"data": {
"received": 2762947,
"sent": 53495723
}
}
/status/stream/metric_zones/<zone>#
Custom metrics defined by metric_zone or
metric_complex_zone in the stream
context. Metrics are updated with the metric directive or
the module variables.
| Number; the number of metric entries discarded because the zone ran out of memory. |
| Object; metrics per key. For single-metric zones, values are numbers. For complex zones, values are objects with metric names. For histogram mode, values are objects with bucket names. |
If discard_key is set and some entries have been expired,
their aggregated metrics are exposed under this key.
Example:
{
"discarded": 3,
"metrics": {
"127.0.0.1": {
"count": 42,
"max": 8
},
"expired": {
"count": 10,
"max": 3.2
}
}
}
HTTP caches#
proxy_cache cache_zone;
proxy_cache_valid 200 10m;
/status/http/caches/<cache>#
For each zone configured with proxy_cache, the following data is stored:
{
"name_zone": {
"size": 0,
"cold": false,
"hit": {
"responses": 0,
"bytes": 0
},
"stale": {
"responses": 0,
"bytes": 0
},
"updating": {
"responses": 0,
"bytes": 0
},
"revalidated": {
"responses": 0,
"bytes": 0
},
"miss": {
"responses": 0,
"bytes": 0,
"responses_written": 0,
"bytes_written": 0
},
"expired": {
"responses": 0,
"bytes": 0,
"responses_written": 0,
"bytes_written": 0
},
"bypass": {
"responses": 0,
"bytes": 0,
"responses_written": 0,
"bytes_written": 0
}
}
}
| Number; the space the cache currently occupies on disk, in bytes. Each cached entry is counted as the whole filesystem blocks its file occupies, so this value always exceeds the total size of the cached response bodies |
| Number; the configured limit on the cache size, in bytes; omitted if no limit is set |
| Boolean; |
| Object; statistics of valid cached responses (proxy_cache_valid) |
| Number; the total number of responses read from the cache |
| Number; the total number of bytes read from the cache |
| Object; statistics of stale responses taken from the cache (proxy_cache_use_stale) |
| Number; the total number of responses read from the cache |
| Number; the total number of bytes read from the cache |
| Object; statistics of stale responses taken from the cache while responses were being updated (proxy_cache_use_stale updating) |
| Number; the total number of responses read from the cache |
| Number; the total number of bytes read from the cache |
| Object; statistics of expired and revalidated responses taken from the cache (proxy_cache_revalidate) |
| Number; the total number of responses read from the cache |
| Number; the total number of bytes read from the cache |
| Object; statistics of responses not found in the cache |
| Number; the total number of corresponding responses |
| Number; the total number of bytes read from the proxied server |
| Number; the total number of responses written to the cache |
| Number; the total number of bytes written to the cache |
| Object; statistics of expired responses not taken from the cache |
| Number; the total number of corresponding responses |
| Number; the total number of bytes read from the proxied server |
| Number; the total number of responses written to the cache |
| Number; the total number of bytes written to the cache |
| Object; statistics of responses not looked up in the cache (proxy_cache_bypass) |
| Number; the total number of corresponding responses |
| Number; the total number of bytes read from the proxied server |
| Number; the total number of responses written to the cache |
| Number; the total number of bytes written to the cache |
In Angie PRO, if cache sharding is enabled with proxy_cache_path directives,
individual shards are exposed as object members of a shards object;
size, max_size, and cold are then reported for each
shard separately and are absent at the zone level:
| Object; lists individual shards as members |
| Object; represents an individual shard with its cache path for name |
| Number; the space the shard currently occupies on disk, in bytes; each cached entry is counted as the whole filesystem blocks its file occupies |
| Number; the configured limit on the shard size, in bytes; omitted if no limit is set |
| Boolean; |
{
"name_zone": {
"shards": {
"/path/to/shard1": {
"size": 0,
"cold": false
},
"/path/to/shard2": {
"size": 0,
"cold": false
}
}
}
}
ACME clients#
/status/http/acme_clients/<client>#
For each configured acme_client in the http block, returns the
current client and certificate status:
{
"state": "ready",
"certificate": "valid",
"details": "The client is ready to request a certificate.",
"next_run": "2026-10-16T16:15:43.805Z"
}
| String; ACME client state. Possible values: |
| String; certificate status. Possible values: |
| String; short status details from the last ACME operation. |
| String or number; next scheduled attempt to request or renew the
certificate, formatted as a date.
Not returned when |
limit_conn#
limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
/status/http/limit_conns/<zone>, /status/stream/limit_conns/<zone>#
Objects for each zone defined by limit_conn_zone in http or limit_conn_zone in stream, with the following fields:
{
"passed": 73,
"skipped": 0,
"rejected": 0,
"exhausted": 0
}
| Number; the total number of connections checked against the zone and not limited |
| Number; the total number of connections not checked against the zone because the key was empty or longer than 255 bytes (counted only if no zone rejected the connection) |
| Number; the total number of connections exceeding the configured limit |
| Number; the total number of connections rejected due to exhaustion of zone storage |
With limit_conn_dry_run in http or
limit_conn_dry_run in stream enabled,
rejected and exhausted count the connections that would have
been rejected.
limit_req#
limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;
/status/http/limit_reqs/<zone>#
Objects for each zone defined by limit_req_zone, with the following fields:
{
"passed": 54816,
"skipped": 0,
"delayed": 65,
"rejected": 26,
"exhausted": 0
}
| Number; the total number of requests checked against the zone and neither delayed nor rejected |
| Number; the total number of requests not checked against the zone because the key was empty or longer than 65535 bytes (counted only if another zone checked the request without rejecting it) |
| Number; the total number of delayed requests |
| Number; the total number of rejected requests |
| Number; the total number of requests rejected due to exhaustion of zone storage |
With limit_req_dry_run enabled, delayed, rejected, and
exhausted count the requests that would have been delayed or rejected.
HTTP upstream#
To enable collection of the following metrics, set the zone directive in the upstream context, for instance:
upstream upstream {
zone upstream 256k;
server backend.example.com service=_example._tcp resolve max_conns=5;
keepalive 4;
}
The memory usage of this shared memory zone is reported by the
/status/slabs/ API section, keyed by the
zone's name. where <upstream> is the name of any upstream specified with the zone directive Object; contains the metrics of the upstream's peers as subobjects
whose names are canonical representations of the peers' addresses.
Members of each subobject: String; the parameter of the server directive String; name of service as it's specified in server directive, if configured Boolean; Number; configured weight String; the current state of the peer and what requests are sent to it: Additional states in Angie PRO: Object; peer selection statistics Number; the current number of connections to the peer Number; total number of requests forwarded to the peer String or number; time when the peer was last selected,
formatted as a date Number; the configured maximum number of simultaneous active connections to the peer, if specified Object; response statistics Number; a non-zero number of responses with status <code> (100-599) Number; a non-zero number of responses with other status codes Object; data statistics Number; the total number of bytes received from the peer Number; the total number of bytes sent to the peer Object; health statistics Number; the total number of unsuccessful attempts to communicate with the peer Number; how many times the peer became Number; the total time (in milliseconds) when the peer was String or number; time when the peer became Number; average time (in milliseconds)
to receive the response headers from the server;
see response_time_factor Number; average time (in milliseconds)
to receive the entire response from the server;
see response_time_factor String; the server's ID in the upstream group, set by
Number; the current average feedback value used
by the feedback load balancing method,
present only when this method is used Number; the current number of cached connections Object; contains the current state of the active backup logic,
present if backup_switch (PRO) is configured for the upstream Number; the level of the active group
that is currently used for load balancing requests.
If the active group is the primary one, the value is 0 Number; remaining wait time in milliseconds,
after which the balancer will re-check for healthy nodes
in groups with lower levels, starting from the primary group,
while groups with higher levels are not checked;
not displayed for the primary group (level 0) If the upstream has upstream_probe (PRO) probes configured,
the The Counters in Number; total probes for this server Number; total failed probes String or number; last probe time,
formatted as a date If a request queue is configured for the upstream,
the upstream object also contains a nested Counter values are summed across all worker processes: Number; total number of requests that entered the queue Number; current number of requests in the queue Number; total number of requests removed from the queue
because the client prematurely closed the connection Number; total number of requests removed from the queue due to timeout Number; total number of queue overflow occurrences/status/http/upstreams/<upstream>#{
"peers": {
"192.168.16.4:80": {
"server": "backend.example.com",
"service": "_example._tcp",
"backup": false,
"weight": 5,
"state": "up",
"selected": {
"current": 2,
"total": 232
},
"max_conns": 5,
"responses": {
"200": 222,
"302": 12
},
"data": {
"sent": 543866,
"received": 27349934
},
"health": {
"fails": 0,
"unavailable": 0,
"downtime": 0,
"header_time": 21,
"response_time": 42
},
"sid": "<server_id>"
}
},
"keepalive": 2
}
peersserverservicebackuptrue for backup serversweightstatebusy: indicates that the number of requests to the server
has reached the limit set by max_conns,
and no new requests are sent to it;down: manually disabled, no requests are sent;draining: similar to down,
but requests from previously bound sessions
(via sticky) are still sent;recovering: recovering after a failure
according to slow_start,
more and more requests are sent over time;unavailable: reached the max_fails limit,
only trial client requests are sent
at intervals defined by fail_timeout;up: operational, requests are sent as usual;checking: configured as essential and being checked,
only probe requests are sent;unhealthy: non-operational,
only probe requests are sent.selectedcurrenttotallastmax_connsresponses<code>xxxdatareceivedsenthealthfailsunavailableunavailable due to reaching the max_fails limitdowntimeunavailable for selectiondownstartunavailable,
formatted as a date.
This field is present only while the peer is in the unavailable
state; otherwise it is absentheader_timeresponse_timesidsid= or generated from the peer addressfeedback
(PRO)keepalivebackup_switch
(PRO)activetimeouthealth/probes (PRO)#health object also has a probes subobject
that stores the server's health probe counters,
while state, apart from the values listed in the table above,
can also be checking and unhealthy:{
"192.168.16.4:80": {
"state": "unhealthy",
"...": "...",
"health": {
"...": "...",
"probes": {
"count": 10,
"fails": 10,
"last": "2026-10-16T09:56:07Z"
}
}
}
}
checking value of state isn't counted as downtime
and means that the server, which has a probe configured as essential,
hasn't been checked yet;
the unhealthy value means that the server is malfunctioning.
Both states also imply that the server isn't included in load balancing.
For details of health probes, see upstream_probe.probes:countfailslastqueue (PRO)#queue object
with request queue counters:{
"queue": {
"queued": 20112,
"waiting": 1011,
"dropped": 6031,
"timedout": 560,
"overflows": 13
}
}
queuedwaitingdroppedtimedoutoverflows
Stream upstream#
To enable collection of the following metrics, set the zone directive in the upstream context, for instance:
upstream upstream {
zone upstream 256k;
server backend.example.com service=_example._tcp resolve max_conns=5;
keepalive 4;
}
The memory usage of this shared memory zone is reported by the
/status/slabs/ API section, keyed by the
zone's name. Here, <upstream> is the name of an upstream that is
configured with a zone directive. Object; contains the metrics of the upstream's peers as subobjects
whose names are canonical representations of the peers' addresses.
Members of each subobject: String; address set by the server directive String; service name, if set by the server directive Boolean; Number; the weight set for the peer String; the current state of the peer and what requests are sent to it: Additional states in Angie PRO: Object; statistics on selecting this peer for connections Number; current number of connections to the peer Number; total number of connections forwarded to the peer String or number; time when the peer was last selected,
formatted as a date Number;
maximum
number of simultaneous active connections to the peer, if set Object; data transfer statistics Number; total bytes received from the peer Number; total bytes sent to the peer Object; peer health statistics Number; total failed attempts to reach the peer Number; total number of times the peer became Number; total time (in milliseconds) that the peer was
String or number; time when the peer last became Number; average time (in milliseconds)
to establish a connection with the server;
see the response_time_factor directive Number; average time (in milliseconds)
to receive the first byte of the response from the server;
see the response_time_factor directive Number; average time (in milliseconds)
to receive the complete response from the server;
see the response_time_factor directive String; the server's ID in the upstream group, set by
Number; the current average feedback value used
by the feedback load balancing method,
present only when this method is used Object; contains the current state of active backup logic,
present if backup_switch (PRO) is configured for the upstream Number; level of the active group
currently used for load balancing.
If the active group is the primary group, the value is 0 Number; remaining wait time in milliseconds
after which the load balancer will recheck for healthy nodes
in groups with lower levels, starting from the primary group,
while groups with higher levels are not checked;
not displayed for the primary group (level 0) If the upstream has upstream_probe (PRO) probes configured,
the The Counters in Number; total number of probes for this server Number; number of failed probes String or number; time of the last probe,
formatted as a date/status/stream/upstreams/<upstream>#{
"peers": {
"192.168.16.4:1935": {
"server": "backend.example.com",
"service": "_example._tcp",
"backup": false,
"weight": 5,
"state": "up",
"selected": {
"current": 2,
"total": 232
},
"max_conns": 5,
"data": {
"sent": 543866,
"received": 27349934
},
"health": {
"fails": 0,
"unavailable": 0,
"downtime": 0,
"connect_time": 3,
"first_byte_time": 21,
"last_byte_time": 42
}
}
}
}
peersserverservicebackuptrue for backup serversweightstatebusy: indicates that the number of requests to the server
has reached the limit set by max_conns,
and no new requests are sent to itdown: manually disabled, no requests are sentdraining: similar to down,
but requests from previously bound sessions
(via sticky) are still sentrecovering: recovering after a failure
according to slow_start,
more and more requests are sent over timeunavailable: reached the max_fails limit,
only trial client requests are sent
at intervals defined by fail_timeoutup: operational, requests are sent as usualchecking: configured as essential and being checked,
only probe requests are sentunhealthy: non-operational,
only probe requests are sentselectedcurrenttotallastmax_connsdatareceivedsenthealthfailsunavailableunavailable due to
reaching the max_fails valuedowntimeunavailable (unavailable for selection)downstartunavailable,
formatted as a date.
This field is present only while the peer is in the unavailable
state; otherwise it is absentconnect_timefirst_byte_timelast_byte_timesidsid= or generated from the peer addressfeedback
(PRO)backup_switch
(PRO)activetimeouthealth/probes (PRO)#health object also has a probes subobject
that stores the server's health probe counters,
while state, in addition to the values from the table above,
can also be checking and unhealthy:{
"192.168.16.4:80": {
"state": "unhealthy",
"...": "...",
"health": {
"...": "...",
"probes": {
"count": 2,
"fails": 2,
"last": "2026-10-16T11:03:54Z"
}
}
}
}
checking value of state means that the server,
which has a probe configured with the essential parameter,
hasn't been checked yet;
the unhealthy value means that the server is non-operational.
Both states also mean that the server isn't included in load balancing.
For details of health probes, see upstream_probe.probes:countfailslast
Certificates#
/certificates/#
A top-level object of the API, separate from the /status/ statistics tree, that reports the TLS certificates Angie has loaded.
A certificate isn't listed under static if its certificate or key file
name contains a variable — including one supplied by an ACME client through
the $acme_cert_<name> variable. A certificate
shared by several servers is listed once.
The following example loads a static certificate and obtains another certificate with an ACME client. The ACME client requires a configured resolver to resolve the directory hostname:
http {
resolver 127.0.0.53;
acme_client example https://acme.example.com/directory;
server {
listen 443 ssl;
server_name www.example.com;
ssl_certificate example.com.crt;
ssl_certificate_key example.com.key;
location /certificates/ {
api /certificates/;
}
}
server {
listen 443 ssl;
server_name acme.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
}
}
In response to the request
curl https://www.example.com/certificates/, Angie returns:
{
"static": {
"/etc/angie/example.com.crt": {
"key": "RSA (2048 bits)",
"chain": [
{
"subject": {
"common_name": "example.com",
"alt_names": [
"example.com",
"www.example.com"
],
"organization": "Example, Inc."
},
"issuer": {
"common_name": "Example Root CA",
"country": "US",
"organization": "Example, Inc."
},
"validity": {
"since": "Sep 18 19:46:19 2022 GMT",
"until": "Jun 15 19:46:19 2025 GMT"
}
}
]
}
},
"acme_clients": {
"example": {
"key": "EC (prime256v1)",
"chain": [
{
"subject": {
"common_name": "acme.example.com"
},
"issuer": {
"common_name": "Example ACME CA"
},
"validity": {
"since": "Sep 18 19:46:19 2022 GMT",
"until": "Dec 17 19:46:19 2022 GMT"
}
}
]
}
}
}
| Object; server certificates set with ssl_certificate in HTTP,
ssl_certificate in Stream, or ssl_certificate in
Mail, each keyed by the absolute path of the certificate file (a
relative name is resolved against the configuration prefix). In builds with
|
| Object; available when Angie is built with the HTTP ACME module, which is also required by the Stream ACME module. Contains certificates obtained by ACME clients for HTTP and Stream servers. Each entry is keyed by the acme_client name. Only clients that have already obtained a certificate are listed |
static/<path>, acme_clients/<client>#
Each entry of static and acme_clients describes a single
certificate bundle:
| String; private key type and size (or curve), for example
|
| Array; the certificates of the bundle, starting with the leaf (server) certificate followed by any intermediate certificates, toward the root. Each element is an object describing one certificate: |
| Object; the subject distinguished name |
| String; Common Name ( |
| Array of strings; the DNS names and IP addresses from the Subject Alternative Name extension |
| String; Country ( |
| String; State or Province Name ( |
| String; Organization ( |
| Object; the issuer distinguished name, with the same fields as
|
| Object; the certificate validity period |
| String; start of the validity period ( |
| String; end of the validity period ( |
The fields of subject and issuer appear only when present in the
certificate.
Dynamic Configuration API (PRO)#
The API includes a Currently, configuration of individual servers within upstreams is available
in the Enables configuring individual upstream servers,
including deleting existing servers or adding new ones. URI path parameters: Name of the upstream; to be configurable via The server's name within the upstream, defined as
For example, the following configuration: Allows the following server names: This API subsection sets the following fields of a server, matching the
parameters of the server directive: Number; server weight, at least 1; the default is 1 Number; maximum number of simultaneous active connections to the
server; the default, 0, means no limit Number; number of unsuccessful attempts that make the server
unavailable, see max_fails; the default is 1,
and 0 disables attempt accounting Number; the fail_timeout period in seconds;
a request can also set it as a time string
in seconds or larger units (no Number; the slow_start period in seconds; a request can
also set it as a time string with millisecond
precision, which a Boolean; Boolean or string; String; server ID, at most 32 bytes; without
Only the fields that the upstream's load balancing method supports are present
and can be set: Example: Setting a field that the method doesn't support fails; for example, for an
existing server of an upstream with the For the same reason, an upstream that uses the Enables configuring individual upstream servers,
including deleting existing servers or adding new ones. URI path parameters: Name of the The server's name within the upstream, defined as
For example, the following configuration: Allows the following server names: This API subsection sets the following fields of a server, matching the
parameters of the server directive: Number; server weight, at least 1; the default is 1 Number; maximum number of simultaneous active connections to the
server; the default, 0, means no limit Number; number of unsuccessful attempts that make the server
unavailable, see max_fails; the default is 1,
and 0 disables attempt accounting Number; the fail_timeout period in seconds;
a request can also set it as a time string
in seconds or larger units (no Number; the slow_start period in seconds; a request can
also set it as a time string with millisecond
precision, which a Boolean; Boolean or string; String; server ID, at most 32 bytes; without
Only the fields that the upstream's load balancing method supports are present
and can be set: Example: Setting a field that the method doesn't support fails; for example, for an
existing server of an upstream with the For the same reason, an upstream that uses the Let's consider the semantics of each HTTP method applicable to this section
using the following upstream configuration as an example: The For example, the
You can obtain default parameter values with the The For example, to add the Verify the changes: The For example, to delete the previously modified Verify the changes using the The The The method operates as follows: if the entities from the new definition
exist in the configuration, they are overwritten; otherwise, they are added. For example, to change the Verify the changes: Note that the JSON object supplied with the The Note Deleting a field with For example, to delete the Verify the changes: The A successful change returns an object with the 200; 200; 200; 201; 400; the HTTP request is invalid 400; a 400; the body isn't valid JSON, a zero-length body
( 400; the body has a field that the entity doesn't have or that the
upstream's load balancing method doesn't support 400; a value has a JSON type that the field doesn't accept 400; the server name isn't a valid address, or it combines a service
name with an IP address or a port 400; the service name before 400; the server name is a domain name, and the upstream has no DNS
server to resolve it, as with 400; the server name has no port, and the stream upstream requires one 400; the server name has a port, and the stream upstream's servers
have none 400; a service name is set for a stream upstream whose servers have no
ports 400; 400; 400; 400; 400; 400; 400; 400; 400; 404; the requested entity doesn't exist 405; the entity doesn't accept the method; for example, a write request
for a path outside servers and their fields, or 413; the body is larger than client_body_buffer_size 500; the request failed for another reason; the error log has the
details 500; the upstream's shared memory zone (zone in HTTP,
zone in stream) has no room for the change/config section that enables dynamic updates
to Angie's configuration in JSON format
with PUT, PATCH, and DELETE HTTP requests.
All updates are atomic: new settings are applied as a whole,
or none are applied at all.
On error, Angie reports the reason; see Responses.Subsections of
/config#/config section for the HTTP and stream modules; the number of settings
eligible for dynamic configuration is steadily increasing./config/http/upstreams/<upstream>/servers/<name>#<upstream>/config, it must
have a zone directive configured, defining a shared
memory zone.<name><service>@<host>, where:<service>@ is an optional service name, used for
SRV record resolution.<host> is the domain name of the service (if resolve
is present) or its IP; an optional port can be defined here. A
server given by a domain name without resolve is listed
under each address it resolves to.upstream backend {
server backend.example.com service=_http._tcp resolve;
server 127.0.0.1;
zone backend 1m;
}
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/_http._tcp@backend.example.com/
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/127.0.0.1:80/
weightmax_connsmax_failsfail_timeoutms), such as "30s";
the default is 10slow_startGET request reports rounded to whole seconds;
the default is 0, which turns slow start offbackuptrue for a backup server (a request can also send 1 or
0); the default is falsedowntrue marks the server as unavailable, and
the string "drain" puts it into drain mode, where it
receives only the requests of sessions bound to it by
sticky; the default is falsesidsid=, the ID is the hexadecimal MD5 hash of the server's address
and port. A server with the resolve parameter has an empty ID
here; each address it resolves to gets its own hash under
/status/weight, slow_start, and backup depend on
the method, as the method table shows, while the other
fields apply to every method.$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on
{
"weight": 1,
"max_conns": 0,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": true,
"down": false,
"sid": ""
}
random method:upstream backend {
zone backend 256k;
server backend.example.com resolve max_conns=5;
random;
}
$ curl -X PATCH -d '{ "backup": true }' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
{
"error": "FormatError",
"description": "The \"backup\" field is unknown."
}
hash, ip_hash, random, or
least_time
method doesn't accept new servers through the API, and PUT can't replace
a whole server object there: adding a server with any method, like such a
PUT, sets every omitted field to its default, including the
fields that the method doesn't support. To change an existing server of such an
upstream, use PATCH or PUT a single field./config/stream/upstreams/<upstream>/servers/<name>#<upstream>upstream block;
to be configurable via /config,
it must have a zone directive configured,
defining a shared memory zone.<name><service>@<host>, where:<service>@ is an optional service name, used for
SRV record resolution.<host> is the domain name of the service (if resolve
is present) or its IP; an optional port can be defined here. A
server given by a domain name without resolve is listed
under each address it resolves to.upstream backend {
server backend.example.com:8080 service=_example._tcp resolve;
server 127.0.0.1:12345;
zone backend 1m;
}
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/_example._tcp@backend.example.com:8080/
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/127.0.0.1:12345/
weightmax_connsmax_failsfail_timeoutms), such as "30s";
the default is 10slow_startGET request reports rounded to whole seconds;
the default is 0, which turns slow start offbackuptrue for a backup server (a request can also send 1 or
0); the default is falsedowntrue marks the server as unavailable, and
the string "drain" puts it into drain mode, where it
receives only the requests of sessions bound to it by
sticky; the default is falsesidsid=, the ID is the hexadecimal MD5 hash of the server's address
and port. A server with the resolve parameter has an empty ID
here; each address it resolves to gets its own hash under
/status/weight, slow_start, and backup depend on
the method, as the method table shows, while the other
fields apply to every method.$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com?defaults=on
{
"weight": 1,
"max_conns": 0,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": true,
"down": false,
"sid": ""
}
random method:upstream backend {
zone backend 256k;
server backend.example.com resolve max_conns=5;
random;
}
$ curl -X PATCH -d '{ "backup": true }' \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com
{
"error": "FormatError",
"description": "The \"backup\" field is unknown."
}
hash, random, or least_time
method doesn't accept new servers through the API, and PUT can't replace
a whole server object there: adding a server with any method, like such a
PUT, sets every omitted field to its default, including the
fields that the method doesn't support. To change an existing server of such an
upstream, use PATCH or PUT a single field.HTTP Methods#
http {
# ...
upstream backend {
zone upstream 256k;
server backend.example.com resolve max_conns=5;
# ...
}
server {
# ...
location /config/ {
api /config/;
allow 127.0.0.1;
deny all;
}
}
}
GET#
GET HTTP method queries an entity at any existing path within
/config, just as it does for other API sections./config/http/upstreams/backend/servers/
upstream server branch enables these queries:$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_conns
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
$ curl http://127.0.0.1/config/http/upstreams/backend/servers
$ # ...
$ curl http://127.0.0.1/config
defaults=on query
argument; see Query arguments.PUT#
PUT HTTP method creates a new JSON entity at the specified path
or entirely replaces an existing one: for a server object, every field the
request omits returns to its default value. A request that adds a server
returns the 201 status code with the Created value; a null
body removes the server, as DELETE does.max_fails parameter, not specified earlier,
to the backend.example.com server within the backend upstream:$ curl -X PUT -d '2' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
{
"success": "Updated",
"description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was updated with replacing."
}
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
{
"max_conns": 5,
"max_fails": 2
}
DELETE#
DELETE HTTP method deletes previously defined settings at the specified path;
in doing so, it restores the default values if there are any.
Applied to a server, it removes the server from the upstream; the
connection_drop argument controls the active
connections to that server.max_fails parameter
of the backend.example.com server within the backend upstream:$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
{
"success": "Reset",
"description": "Configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was reset to default."
}
defaults=on argument:$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on
{
"weight": 1,
"max_conns": 5,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": false,
"down": false,
"sid": ""
}
max_fails parameter has returned to its default value.PATCH#
PATCH HTTP method creates a new entity at the specified path
or partially replaces or complements an existing one
(RFC 7396)
by supplying a JSON definition in its payload.down parameter of the
backend.example.com server within the backend upstream,
leaving the rest intact:$ curl -X PATCH -d '{ "down": true }' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
{
"success": "Updated",
"description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
{
"max_conns": 5,
"down": true
}
PATCH request was merged with the
existing one instead of replacing it entirely, as would be the case with PUT.null values are a special case; they are used to delete
specific configuration items during such a merge.null is identical to DELETE on that
field; in particular, it restores the field's default value. A null
body removes the server itself.down parameter added earlier
and simultaneously update max_conns:$ curl -X PATCH -d '{ "down": null, "max_conns": 6 }' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
{
"success": "Updated",
"description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
{
"max_conns": 6
}
down parameter, for which a null value was supplied, was deleted;
the max_conns value was updated.Responses#
success value and its
description; a failed request returns an object with the error code and
its description, as in the examples above. In the tables below, the number
before the semicolon is the HTTP status code of the response.Success values#
UpdatedPUT or PATCH changed an existing entityResetDELETE returned a field to its default valueDeletedDELETE or a null body removed a serverCreatedPUT or PATCH added a serverError codes#
BadRequestEmptyBodyPUT or PATCH request has no body at all (neither
Content-Length nor Transfer-Encoding)JSONErrorContent-Length: 0) included; the description says what the
parser expectedFormatErrorValueWrongTypeUpstreamBadAddressUpstreamBadService@ is emptyUpstreamConfNoResolverresolver off; (resolver in
HTTP, resolver in stream)UpstreamPortRequiredUpstreamNoPortNeededUpstreamSrvNotAllowedUpstreamBadWeightweight isn't greater than 0UpstreamBadMaxConnsmax_conns is negativeUpstreamBadMaxFailsmax_fails is negativeUpstreamBadFailTimeoutfail_timeout is negative or isn't a valid timeUpstreamBadSlowStartslow_start is negative or isn't a valid timeUpstreamBackupInvalidbackup is a number greater than 1UpstreamBadBackupbackup is a stringUpstreamBadDowndown has a value other than a boolean or "drain"UpstreamBadSIDsid is longer than 32 bytesPathNotFoundMethodNotAllowedPUT for a field
that doesn't existTooLargeBodyInternalErrorUpstreamOutOfMemory
Content