Skip to main content

NGINX Configuration

For the plugin to obtain the statistics, NGINX must expose the stub_status endpoint. Enabling it is done by editing the NGINX configuration file (by default at /etc/nginx/nginx.conf or /etc/nginx/sites-available/default).

The ngx_http_stub_status_module module is not included in every NGINX build. To verify whether it is available, run nginx -V 2>&1 | grep stub_status. Most Linux distributions include it by default.

Minimal configuration (no authentication, no SSL)

Add a dedicated location for the status inside your server:

server {
    listen 80;
    server_name _;

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 192.168.1.50;   # Pandora FMS server IP
        deny all;
    }
}

With this configuration the plugin will consume the URL:

http://<SERVER_IP>/nginx_status

Configuration with basic authentication

To protect the endpoint with username and password, define auth_basic and auth_basic_user_file in the status location:

server {
    listen 80;
    server_name _;

    location /nginx_status {
        stub_status on;
        access_log off;
        auth_basic "NGINX Status";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}

Generate the .htpasswd file with htpasswd or openssl:

htpasswd -c /etc/nginx/.htpasswd admin
# or
openssl passwd -apr1 mypassword > /etc/nginx/.htpasswd

The same username and password must be provided to the plugin through --user / --password (or the username / password fields of the configuration file).

Configuration with SSL/TLS

To serve the statistics over HTTPS configure the certificate in the server:

server {
    listen 443 ssl;
    server_name _;

    ssl_certificate     /etc/nginx/certs/status.pem;
    ssl_certificate_key /etc/nginx/certs/status.key;

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 192.168.1.50;
        deny all;
    }
}

Generate a self-signed test certificate with:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/nginx/certs/status.key \
  -out /etc/nginx/certs/status.crt \
  -subj "/CN=localhost"
cat /etc/nginx/certs/status.crt /etc/nginx/certs/status.key > /etc/nginx/certs/status.pem

In the plugin the URL will be indicated with the https:// scheme and the --ssl parameter (or verify_ssl) depending on whether the certificate should be validated:

  • verify_ssl = true → for valid certificates in production.
  • verify_ssl = false → for self-signed certificates or test environments.

Full configuration (SSL + authentication)

server {
    listen 443 ssl;
    server_name _;

    ssl_certificate     /etc/nginx/certs/status.pem;
    ssl_certificate_key /etc/nginx/certs/status.key;

    location /nginx_status {
        stub_status on;
        access_log off;
        auth_basic "NGINX Status";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}

server {
    listen 80;
    server_name _;
    return 301 https://$host$request_uri;
}

After modifying the NGINX configuration, reload the service to apply the changes:

sudo systemctl reload nginx

Verification

To verify that the endpoint responds correctly, you can make a manual request to the status page:

curl -u admin:mypassword http://192.168.0.10/nginx_status

The output must be plain text with the following format:

Active connections: 291
server accepts handled requests
 16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106
  • Active connections: total number of active connections (includes waiting ones).
  • accepts: total connections accepted since NGINX started.
  • handled: total connections handled since NGINX started.
  • requests: total client requests processed since NGINX started.
  • Reading: connections reading request headers from the client.
  • Writing: connections writing a response to the client or processing a request.
  • Waiting: idle keep-alive connections waiting for the next request.
Back to top