NGINX.COM
Web Server Load Balancing with NGINX Plus


[Editor – This post has been updated to use the NGINX Plus API, which replaces and deprecates the separate extended Status module discussed in the original version of the post.

Introduced in NGINX Plus R13, the NGINX Plus API supports other features in addition to live activity monitoring, including dynamic configuration of upstream server groups (replacing the separate Upstream Conf module originally used for that purpose) and key‑value stores. The NGINX Plus dashboard was updated to use the API in NGINX Plus R14.

Because configuring the API enables several features, we have changed the name of the sample configuration file to nginx-plus-api.conf. We are also now distributing sample configuration files as GitHub gists instead of downloads from nginx.com.]

One of the most popular features in NGINX Plus is live activity monitoring, also known as extended status reporting. The live activity monitor reports real‑time statistics for your NGINX Plus installation, which is essential for troubleshooting, error reporting, monitoring new installations and updates to a production environment, and cache management.

We often get questions from DevOps engineers – experienced and new to NGINX Plus alike – about the best way to configure live activity monitoring. In this post, we’ll describe a sample configuration file that will have you viewing real‑time statistics on the NGINX Plus dashboard in just a few minutes.

The sample configuration file for the NGINX Plus API makes it even easier to set up many of NGINX Plus’ advanced features in your environment.

Note: These instructions assume that you use the conventional NGINX Plus configuration scheme (in which configuration files are stored in the /etc/nginx/conf.d directory), which is set up automatically when you install an NGINX Plus package. If you use a different scheme, adjust the commands accordingly.

Installing the Sample Configuration File

The commands do not include prompts or other extraneous characters, so you can cut and paste them directly into your terminal window.

  1. Download the sample configuration file.

    cd /etc/nginx/conf.d/
    wget https://gist.githubusercontent.com/nginx-gists/a51341a11ff1cf4e94ac359b67f1c4ae/raw/bf9b68cca20c87f303004913a6a9e9032f24d143/nginx-plus-api.conf

    You can also navigate in a browser to the Gist repo and either click the Download ZIP button, or click the Raw button in the title bar for the nginx-plus-api.conf file and copy the file contents.

  2. Customize your configuration files as instructed in Customizing the Configuration.

  3. Test the configuration file for syntactic validity and reload NGINX Plus.

    nginx -t && nginx -s reload

The NGINX Plus dashboard is available immediately at http://nginx-plus-server-address:8080/ (or the alternate port number you configure in Changing the Port for the Dashboard).

Customizing the Configuration

To get the most out of live activity monitoring, make the changes described in this section to both nginx-plus-api.conf and your existing configuration files. Equivalent instructions are included as comments in nginx-plus-api.conf.

Monitoring Servers and Upstream Server Groups

For statistics about virtual servers and upstream groups to appear on the dashboard, you must enable a shared memory zone in the configuration block for each server and group. The shared memory is used to store configuration and run‑time state information across all of the NGINX Plus worker processes.

If you don’t configure shared memory, the built‑in NGINX Plus dashboard reports only basic information about the number of connections and requests.

In existing configuration files where you define virtual servers, add the status_zone directive to the server configuration block for each server you want to appear on the dashboard. (You can specify the same zone name in multiple server blocks, in which case the statistics for those servers are aggregated together in the dashboard.)

server {
    listen 80;
    status_zone my_frontend;
    location / {
        proxy_pass http://backend;
    }
}

Similarly, in existing configuration files where you define upstream groups, add the zone directive to the upstream configuration block for each group you want to appear on the dashboard. The following example allocates 64 KB of shared memory to store the statistics of the servers in the my_backend upstream group. The zone name for each upstream group must be unique.

upstream backend {
    zone my_backend 64k;
    server 10.2.3.5;
    server 10.2.3.6;
}

Restricting Access to the NGINX Plus API

The default settings in the sample configuration file allow anyone on any network to access the dashboard. We strongly recommend that you configure at least one of the following security measures in nginx-plus-api.conf:

  1. Firewall. Configure your firewall to disallow outside access to the port for the dashboard (8080 on line 63 in the sample configuration file).

  2. Client certificates, which are part of a complete configuration of SSL or TLS. For more information, see the NGINX Plus Admin Guide.

  3. HTTP basic authentication. In the sample configuration file, uncomment the auth_basic and auth_basic_user_file directives (lines 66–67). Add the appropriate user entries to the /etc/nginx/users file (for example, by using an htpasswd generator). You can also reuse an existing htpasswd file (from an Apache HTTP Server deployment, for example).

    auth_basic "NGINX Plus API";
    auth_basic_user_file /etc/nginx/users;
  4. IP address‑based access control lists (ACLs). In the sample configuration file, uncomment the allow and deny directives (lines 70–71), and substitute the address of your administrative network for 10.0.0.0/8. Only users on the specified network can access the NGINX Plus API and dashboard.

    allow 10.0.0.0/8;
    deny all;

You can create further restrictions on write operations, to distinguish between users with read permission and those who can change configuration. Uncomment the sample limit_except block (lines 79–82) in the location api block. As detailed in the reference documentation, several authentication schemes are supported in addition to the HTTP Basic authentication used in the example.

limit_except GET {
        auth_basic "NGINX Plus API";
        auth_basic_user_file /etc/nginx/admins;
    }

Changing the Port for the Dashboard

To set the port number for the dashboard to a value other than 8080, edit the following listen directive (line 63) in the sample configuration file.

listen 8080;

Limiting the Monitored IP Addresses

If your NGINX Plus server is multi‑homed (has several IP addresses) and you want the NGINX Plus API and dashboard to be exposed on only one of them, edit the listen directive (line 63) so that it specifies its IP address and port, as in the following example.

listen 10.2.3.4:8080;

Demo NGINX Plus Dashboard

To preview all the features of the NGINX Plus dashboard, check out the live demo at demo.nginx.com.

Further Reading

To try NGINX Plus, start your free 30-day trial today or contact us to discuss your use cases.

Hero image
Free O'Reilly eBook: The Complete NGINX Cookbook

Updated for 2024 – Your guide to everything NGINX



About The Author

Nick Shadrin

Software Architect

About F5 NGINX

F5, Inc. is the company behind NGINX, the popular open source project. We offer a suite of technologies for developing and delivering modern applications. Together with F5, our combined solution bridges the gap between NetOps and DevOps, with multi-cloud application services that span from code to customer.

Learn more at nginx.com or join the conversation by following @nginx on Twitter.