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.

Practice

1. What is the main purpose of the stub_status module in nginx?

easy

A. To provide basic server statistics like active connections and requests

B. To enable SSL encryption for secure connections

C. To serve static files faster

D. To balance load between multiple servers

Solution

1. Step 1: Understand the stub status module role

   The stub status module is designed to show simple server stats such as active connections and request counts.

2. Step 2: Compare with other options

   SSL encryption, static file serving, and load balancing are handled by other nginx modules, not stub status.

3. Final Answer:

   To provide basic server statistics like active connections and requests -> Option A

4. Quick Check:

   Stub status = server stats [OK]

Hint: Stub status shows server stats, not security or file serving [OK]

Common Mistakes:

• Confusing stub_status with SSL or load balancing modules
• Thinking stub_status serves files
• Assuming stub_status handles security

2. Which of the following is the correct way to enable the stub status module inside an nginx configuration location block?

easy

A. location /status { stub_status; }

B. location /status { stub_status on; }

C. location /status { status_stub; }

D. location /status { enable_stub_status; }

Solution

1. Step 1: Recall stub status syntax

   The stub status module is enabled simply by adding stub_status; inside a location block without extra keywords.

2. Step 2: Check each option

   location /status { stub_status on; } uses incorrect syntax with stub_status on;. Options C and D use invalid directives.

3. Final Answer:

   location /status { stub_status; } -> Option A

4. Quick Check:

   Enable stub_status with just 'stub_status;' [OK]

Hint: Use exactly 'stub_status;' inside location block [OK]

Common Mistakes:

• Adding 'on' or other keywords after stub_status
• Using wrong directive names
• Placing stub_status outside location block

3. Given this nginx configuration snippet:

location /nginx_status {
    stub_status;
    allow 192.168.1.0/24;
    deny all;
}

What will happen if a client from IP 192.168.1.15 accesses /nginx_status?

medium

A. The client will download the nginx configuration file

B. The client will see nginx server statistics

C. The client will be redirected to the homepage

D. The client will get a 403 Forbidden error

Solution

1. Step 1: Analyze IP access rules

   The configuration allows IPs in 192.168.1.0/24 and denies all others. IP 192.168.1.15 is inside this range, so access is allowed.

2. Step 2: Understand stub_status output

   With access allowed, the client will see the nginx server statistics page generated by stub_status.

3. Final Answer:

   The client will see nginx server statistics -> Option B

4. Quick Check:

   Allowed IP + stub_status = stats page [OK]

Hint: Allowed IPs see stats; others get denied [OK]

Common Mistakes:

• Ignoring IP allow/deny order
• Assuming all IPs can access stub_status
• Thinking stub_status redirects or downloads files

4. You configured nginx with:

location /status {
    stub_status;
}

But when you visit /status, you get a 403 Forbidden error. What is the most likely cause?

medium

A. The stub_status directive is misspelled

B. Nginx does not support stub_status on this version

C. The location block is missing a root directive

D. Access is not restricted by allow/deny rules, so default deny applies

Solution

1. Step 1: Understand default access behavior

   By default, nginx denies access if no allow/deny rules are set and the stub_status is enabled, causing 403 errors.

2. Step 2: Check other options

   The stub_status directive is correct, root is not required for stub_status, and most nginx versions support stub_status.

3. Final Answer:

   Access is not restricted by allow/deny rules, so default deny applies -> Option D

4. Quick Check:

   No allow/deny means deny by default [OK]

Hint: Always add allow/deny rules to permit stub_status access [OK]

Common Mistakes:

• Forgetting to add allow rules for trusted IPs
• Assuming stub_status needs root directive
• Blaming nginx version without checking

5. You want to monitor nginx server stats securely using stub status. Which configuration snippet correctly enables stub status at /status and restricts access only to localhost?

hard

A. location /status {
stub_status;
deny 127.0.0.1;
allow all;
}

B. location /status {
stub_status on;
allow all;
}

C. location /status {
stub_status;
allow 127.0.0.1;
deny all;
}

D. location /status {
stub_status;
allow 0.0.0.0/0;
}

Solution

1. Step 1: Enable stub_status correctly

   Use stub_status; inside the location block without extra keywords.

2. Step 2: Restrict access to localhost

   Allow only 127.0.0.1 and deny all others to secure access.

3. Step 3: Evaluate options

   location /status { stub_status; allow 127.0.0.1; deny all; } correctly enables stub_status and restricts access. location /status { stub_status on; allow all; } wrongly uses 'stub_status on;' and allows all. location /status { stub_status; deny 127.0.0.1; allow all; } denies localhost but allows all others, which is insecure. location /status { stub_status; allow 0.0.0.0/0; } allows all IPs.

4. Final Answer:

   location /status { stub_status; allow 127.0.0.1; deny all; } -> Option C

5. Quick Check:

   Stub_status + allow localhost + deny others = secure [OK]

Hint: Allow localhost and deny all others for secure stub_status [OK]

Common Mistakes:

• Using 'stub_status on;' instead of 'stub_status;'
• Allowing all IPs instead of restricting
• Denying localhost but allowing others