Stub status module in Nginx - Commands & Configuration

Introduction

Sometimes you want to quickly check how your web server is doing without complex tools. The stub status module in nginx gives you a simple webpage showing basic server stats like active connections and requests.

When you want to see how many users are currently connected to your nginx server.

When you need a quick health check of your nginx server without installing extra software.

When you want to monitor nginx performance metrics like accepted connections and handled requests.

When you want to integrate nginx stats into simple monitoring scripts or dashboards.

When troubleshooting nginx to check if it is receiving and processing requests properly.

Config File - nginx.conf

nginx.conf

events {
    worker_connections 1024;
}

http {
    server {
        listen 8080;

        location /nginx_status {
            stub_status on;
            allow 127.0.0.1;
            deny all;
        }
    }
}

This configuration enables the stub status module on the path /nginx_status on port 8080.

stub_status on; activates the status page.

allow 127.0.0.1; restricts access to localhost for security.

deny all; blocks all other IPs from accessing the status page.

Commands

Check the nginx configuration file syntax to make sure there are no errors before reloading.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload nginx to apply the new configuration without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

Request the stub status page to see nginx server statistics.

Terminal

curl http://127.0.0.1:8080/nginx_status

Expected Output

Active connections: 1 

server accepts handled requests

 10 10 20 

Reading: 0 Writing: 1 Waiting: 0

Key Concept

If you remember nothing else from this pattern, remember: the stub status module provides a simple, lightweight way to see nginx server activity on a special URL.

Common Mistakes

Not restricting access to the /nginx_status URL

Anyone on the internet could see your server stats, which is a security risk.

Use allow and deny directives to limit access to trusted IPs only.

Forgetting to reload nginx after changing the config

Changes won't take effect until nginx reloads the configuration.

Run 'sudo systemctl reload nginx' after editing the config.

Trying to access the status page on the wrong port or URL

You won't get the status page if you use the default port or wrong path.

Use the exact port and path defined in the config, e.g., http://127.0.0.1:8080/nginx_status.

Summary

Enable the stub status module in nginx config under a location block.

Restrict access to the status page using allow and deny directives for security.

Test the config syntax and reload nginx to apply changes.

Use curl to fetch the status page and see live server statistics.