VMware ESXi and vSphere Cluster Management

Nginx Status Monitoring and the stub_status Module

Learn how to enable, secure, access, test, and interpret Nginx stub_status metrics for basic server monitoring.

Nginx can expose a small HTTP status endpoint containing runtime connection states and cumulative request counters. This feature is provided by the ngx_http_stub_status_module and is useful for basic health visibility, traffic observation, load-balancer checks, and monitoring collectors.

The endpoint is intentionally limited. It provides aggregate metrics for the Nginx instance, not per-site, per-upstream, per-client, or detailed latency analytics. Use access and error logs, upstream metrics, operating-system metrics, or a richer monitoring solution when you need that detail.

How the Nginx status module works

ngx_http_stub_status_module is the Nginx HTTP module that provides a compact built-in status page. The stub_status directive enables that output inside a location block.

The module must be included when Nginx is built. It is commonly included in distribution packages, but availability and loading behavior vary by operating system, repository, package, and custom Nginx build.

nginx -V 2>&1 | grep -- '--with-http_stub_status_module'

If the command prints --with-http_stub_status_module, the inspected Nginx binary was built with the module. If it prints nothing, verify that you are checking the same binary used by the running service. A package may provide multiple Nginx binaries or variants.

Configure a protected status location

A status endpoint is an HTTP URL such as /nginx_status or /stub_status. The path is your choice, but a dedicated, predictable path makes monitoring configuration easier. Put the location in the server block that should answer the monitoring request.

Local-only example

This example permits processes using IPv4 or IPv6 loopback and rejects all other clients.

location = /nginx_status {
    stub_status;
    access_log off;
    allow 127.0.0.1;
    allow ::1;
    deny all;
}

The exact-match operator = prevents unrelated paths from selecting this location. access_log off is optional; it avoids filling access logs with frequent polling requests. Keep error logging available so configuration and access problems remain visible.

Permit a monitoring subnet

location = /nginx_status {
    stub_status;
    access_log off;
    allow 127.0.0.1;
    allow ::1;
    allow 10.20.30.0/24;
    deny all;
}

The allow directives identify permitted source addresses or networks. The final deny all makes the policy explicit: anything not permitted is rejected. Access rules must account for the address Nginx actually sees. A reverse proxy can change the apparent source address, so do not add broad networks merely to compensate for an incorrect proxy design.

Choose the right server block

You can place the location on an existing application site, but a dedicated monitoring virtual host is often easier to secure. Such a server can listen only on a private address or management port and allow only the collector network.

server {
    listen 10.20.30.10:8080;
    server_name nginx-monitor.internal;

    location = /nginx_status {
        stub_status;
        access_log off;
        allow 10.20.30.0/24;
        deny all;
    }
}

Do not expose a private listener through public firewall rules. Confirm that the requested host, port, scheme, and path select this server rather than another virtual host.

Secure the endpoint

The status endpoint should not normally be public. Although its output is small, it reveals traffic and capacity information that may help an attacker understand the service.

Loopback-only access — Use when a local agent or script collects metrics. Example: allow 127.0.0.1; and allow ::1;. It is simple and has a small exposure area, but remote collectors cannot connect directly.

IP allowlist — Use when one or more known collectors need access. Permit exact addresses or a narrowly scoped CIDR range, then use deny all;. It is straightforward, but source addresses must remain stable and correctly observed.

Private management network — Use a private interface, VLAN, or internal listener. This reduces public exposure, but routing and network policy still require maintenance.

Firewall restriction — Limit the listener or port to monitoring hosts with host firewalls, security groups, or network firewalls. This adds a network boundary, but should complement Nginx access rules rather than replace them.

TLS or authenticated proxy layer — Place the endpoint behind HTTPS, a mutually authenticated TLS connection, or an authenticated internal proxy. This is useful across less-trusted networks, but introduces certificate, proxy, and identity-management complexity.

IPv4 and IPv6 loopback are different addresses. 127.0.0.1 permits IPv4 localhost requests; ::1 permits IPv6 localhost requests. Include both when local tools may use either protocol.

Validate and apply the configuration safely

Always test syntax before activating a change.

nginx -t

Only after a successful test should you apply a graceful reload.

systemctl reload nginx

A graceful reload lets existing workers finish current work while new workers use the validated configuration. A restart is usually unnecessary for a location change and can interrupt connections.

Access the endpoint

From an authorized local process, use:

curl -s http://127.0.0.1/nginx_status

For a private monitoring listener, use its matching address and port:

curl -s http://nginx-monitor.internal:8080/nginx_status

If the server uses HTTPS, request an https:// URL. Nonstandard listening ports must also appear in the URL. A browser can display the same plain-text response when used from an authorized host.

A successful request normally returns HTTP 200 OK. A rejected source commonly receives 403 Forbidden. A wrong virtual host or path may produce 404 Not Found, while a closed or unreachable listener commonly causes a connection error.

Poll repeatedly during testing

watch -n 2 'curl -s http://127.0.0.1/nginx_status'

Test from both a permitted source and a non-permitted source. Also verify the listener, selected virtual host, endpoint path, and active configuration.

Understand stub_status output

A representative response looks like this:

Active connections: 3
server accepts handled requests
 1200 1200 3560
Reading: 0 Writing: 1 Waiting: 2

Active connections is a point-in-time count of currently active client connections. The three values on the next line are cumulative counters for the running Nginx worker set. They can change or reset when workers are replaced, restarted, or reloaded, so establish a new baseline after deployment events.

Active connections — Gauge — Current client connections — Compare with normal concurrency and configured capacity — Alert on sustained abnormal levels.

accepts — Counter — Client connections accepted by Nginx — A rising value indicates new TCP client connections — Calculate connection-accept rates.

handled — Counter — Client connections successfully handled by Nginx — It commonly tracks accepts closely; a persistent difference requires investigation — Detect capacity or resource problems.

requests — Counter — HTTP requests processed by Nginx — Includes requests served over reused keepalive connections — Calculate request rates and observe traffic trends.

Reading — Gauge — Connections where Nginx is reading client request data, commonly request headers — Sustained elevation can indicate slow clients or incomplete requests — Investigate slow-client behavior and connection pressure.

Writing — Gauge — Connections where Nginx is sending responses — Sustained elevation can reflect large responses, slow clients, or slow upstream work — Correlate with response size, bandwidth, and upstream metrics.

Waiting — Gauge — Idle keepalive connections waiting for another request — A high value may be normal when keepalive is intentionally enabled — Track idle connection usage and keepalive behavior.

Keepalive means reusing an existing client TCP connection for multiple HTTP requests. Therefore, a high Waiting value is not automatically a failure.

Turn counters into useful rates

Single samples are snapshots. Counters and gauges become more useful when collected as a time series and compared with normal workload baselines.

For two samples separated by a known interval, calculate:

request rate = (requests2 - requests1) / seconds
connection-accept rate = (accepts2 - accepts1) / seconds

For example, if requests rises from 3,560 to 4,160 over 60 seconds, the average request rate is (4,160 - 3,560) / 60 = 10 requests/second. Ignore or reset a rate calculation when a worker restart or reload causes the counter baseline to change.

Compare Active connections with worker capacity, the configured worker_connections limit per worker, and operating-system file-descriptor limits. The effective capacity can also be reduced by listening sockets, upstream connections, logging, and other descriptors used by each worker.

A sustained increase in Reading may indicate slow request transmission or clients that open connections without promptly completing requests. A sustained increase in Writing may indicate slow clients, large responses, constrained network bandwidth, or slow upstream responses. A sustained increase in Waiting may be expected with keepalive, but should be compared with idle-connection limits and the normal baseline.

If accepts grows faster than handled, investigate worker connection limits, file descriptors, operating-system resource exhaustion, and Nginx errors. Do not treat a small difference in one sample as proof of failure; look for a persistent trend and correlate it with logs and system metrics.

Use stub_status with monitoring systems

An exporter, agent, or custom script can poll the endpoint, parse its plain-text fields, and transform them into the metric format expected by a monitoring platform. A typical flow is:

A protected Nginx status endpoint exposes aggregate counters and gauges.
An exporter or agent polls the endpoint from an approved address.
A metrics scraper collects the exporter output.
Time-series storage retains samples for rates, trends, dashboards, and alerts.
Dashboards show active connections, request rates, and connection states; alerts compare values with established baselines.

Permit the collector specifically, rather than opening the status URL to the internet. Document the endpoint URL, scheme, port, path, and approved collector addresses.

The open-source stub_status endpoint is not the same as the Nginx Plus API and its advanced monitoring dashboards. Choose richer tooling when you need per-upstream details, granular latency data, or expanded application and proxy metrics.

Common results and troubleshooting

200 OK with status metrics — The expected location and module are working — Run curl -i and inspect the body — Add the endpoint to the authorized collector configuration.

403 Forbidden — The source is not allowed, IPv6 loopback is missing, or a proxy changes the apparent source address — Check logs, source addressing, and allow/deny rules — Add only the required address or correct the trusted proxy architecture.

404 Not Found — Wrong server block, host, port, scheme, URI, or unreloaded configuration — Inspect the active configuration and test the expected Host and listener — Place the location in the intended server block and reload.

Connection refused — Nginx is stopped, not listening on the target address, or the endpoint is loopback-only — Check service state and listening sockets; test locally first — Correct the listener or use local collection if remote access is not intended.

Unknown directive stub_status — The binary lacks ngx_http_stub_status_module, or a different binary is being tested — Inspect nginx -V, the package, and the service binary path — Install or build a package containing the module and reload the intended service.

Unexpected virtual-host response — The request selected another server block — Check the address, port, scheme, and Host header — Use the correct URL or adjust virtual-host and listener configuration.

Deployment checklist

Confirm the installed Nginx build includes ngx_http_stub_status_module.
Choose a dedicated path such as /nginx_status.
Place the location in the intended existing or dedicated monitoring server block.
Restrict access with loopback, a narrow allowlist, a private listener, firewall controls, or an authenticated TLS proxy.
Include both IPv4 and IPv6 loopback rules when local access may use both protocols.
Run nginx -t.
Perform a graceful reload with systemctl reload nginx.
Verify access from an approved collector and rejection from an unauthorized host.
Record the URL and approved monitoring source addresses.
Collect repeated samples and alert from baseline-aware rates and sustained conditions, not isolated values.

Exam-relevant note: stub_status supplies aggregate counters and connection-state gauges. It does not provide detailed per-request latency, per-upstream health, per-client statistics, or full application observability.

For related material, see Nginx Status.