This check uses data from the NGINX stub status module, fetched by the nginx_status agent plugin.

LAST TESTED ON CHECKMK 2.4.0P22

Table of Contents

Overview

This article explains how to enable the NGINX stub status page and configure the Checkmk nginx_status agent plugin.

The instructions were verified on:

Ubuntu 24
Debian 13

Recompiling NGINX is not required on standard Debian or Ubuntu systems.

Problem

The Checkmk nginx_status plugin requires access to the NGINX stub status page.

In some installations:

The stub status module is not available.
The /nginx_status location is not configured.
The status page is not reachable locally.

Some online guides recommend recompiling NGINX, which is usually unnecessary.

Solution

Verify that the stub status module is available

Run:

root@linux:~$ nginx -V 2>&1 | grep with-http_stub_status_module

If the output contains:

with-http_stub_status_module

the module is available.

If the module is missing

On Ubuntu 24 and Debian 13, the recommended solution is to install the nginx-full package:

root@linux:~$ apt install nginx-full

After installation, verify again:

root@linux:~$ nginx -V 2>&1 | grep with-http_stub_status_module
--with-http_stub_status_module

Recompiling NGINX is not required.

Configure the NGINX status page

You must add a location /nginx_status section to your NGINX configuration.

Example default site configuration: /etc/nginx/sites-enabled/default

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    root /var/www/html;
    server_name _;

    location / {
        try_files $uri $uri/ =404;
    }

    location /nginx_status {
        stub_status on;
        access_log off;

        allow 127.0.0.1;
        deny all;
    }
}

Important:

The stub_status on; directive enables the status page.
Access should normally be restricted to localhost.
You can use a different port if preferred.

After modifying the configuration, restart NGINX:

root@linux:~$ systemctl restart nginx

Verify the status page

Test locally:

root@linux:~$ wget -qO - http://127.0.0.1/nginx_status

Example output:

Active connections: 1
server accepts handled requests
 380 380 380
Reading: 0 Writing: 1 Waiting: 0

If this output is shown, NGINX is correctly serving the required status information.

Install and configure the Checkmk agent plugin

Install the nginx_status plugin into the agent plugins directory (usually /usr/lib/check_mk_agent/plugins/)

The plugin attempts to autodetect running NGINX instances automatically.

Manually configure the plugin if autodetection fails

If autodetection fails, create a configuration file here: /etc/check_mk/nginx_status.cfg

Example configuration:

servers = [
    {
        'address': '127.0.0.1',
        'page': 'nginx_status',
        'port': 80,
        'protocol': 'http'
    }
]

Via the Agent bakery
Click on Setup → Agents → Windows, Linux, Solaris... → Agent rules →NGINX webservers (Linux)

Checkmk will try to autodetect all running NGINX servers if Autodetect instances expect HTTPS on the following ports is selected.

You can specify NGINX instances with Specific list of instances.

Test the plugin manually

To test the plugin manually, run:

root@linux:~$ MK_CONFDIR=/etc/check_mk /usr/lib/check_mk_agent/plugins/nginx_status

If working correctly, the plugin outputs NGINX status data in agent format.

Active connections: 1
server accepts handled requests
 380 380 380
Reading: 0 Writing: 1 Waiting: 0

After service discovery in Checkmk, one service will be created per detected NGINX instance.

Debugging

Check if Nginx is running

Check the service status:

root@linux:~$ systemctl status nginx
● nginx.service - A high performance web server and a reverse proxy server
     Loaded: loaded (/lib/systemd/system/nginx.service; enabled; preset: enabled)
     Active: active (running) since Wed 2026-02-12 09:41:22 CET; 1h 15min ago
       Docs: man:nginx(8)
    Process: 1234 ExecStartPre=/usr/sbin/nginx -t -q -g daemon on; master_process on; (code=exited, status=0/SUCCESS)
    Process: 1235 ExecStart=/usr/sbin/nginx -g daemon on; master_process on; (code=exited, status=0/SUCCESS)
   Main PID: 1236 (nginx)
      Tasks: 3 (limit: 4915)
     Memory: 5.8M
        CPU: 120ms
     CGroup: /system.slice/nginx.service
             ├─1236 nginx: master process /usr/sbin/nginx -g daemon on; master_process on;
             ├─1237 nginx: worker process
             └─1238 nginx: worker process

Ensure the service state is active (running). If not, review the error messages or check logs with journalctl -u nginx.

Check if Nginx is listening

Check whether NGINX is listening on the configured port:

root@linux:~$ netstat -tulpen | grep 8081 tcp 0 0 0.0.0.0:8081 0.0.0.0:* LISTEN 0 43044 1353/nginx: master tcp6 0 0 :::8081 :::* LISTEN 0 43045 1353/nginx: master
tcp 0 0 0.0.0.0:8081 0.0.0.0:* LISTEN 0 43044 1353/nginx: master
tcp6 0 0 :::8081 :::* LISTEN 0 43045 1353/nginx: master

If no output is returned, confirm the listen directive and validate the configuration using nginx -t.

Verify stub status module

Run:

root@linux:~$ nginx -V 2>&1 | grep with-http_stub_status_module
--with-http_stub_status_module

If no output is shown, install the nginx-full package and verify again.

Test the status page directly