This article is going to show how to compile and install the Nginx module – ngx_http_vhost_traffic_status.

The module gathers traffic information per the server blocks and upstream servers and shows information for Nginx proxy cache like used space.

In addition, the module shows the type of the Response – 1xx, 2xx, 3xx, 4xx, 5xx and total. So when if problems occur in a server block or an upstream server
This module nginx-module-vts offers really extended status information for your Nginx.
Here is one the status page of our web servers with 18 virtual hosts:

The status page shows all virtual hosts in section “Server zones” and all upstream servers for the FastCGI PHP backend servers.

Traffic, requests, and status codes are available. All data is available in JSON, too.

• Requests – Total, Requests/s, Time
• Responses – 1xx, 2xx, 3xx, 4xx, 5xx, Total
• Traffic – Sent, Received, Sent/s, Received/s
• Cache – Miss, Bypass, Expired, Stale, Updating, Revalidated, Hit, Scarce, Total

In addition to the information above there are State, Response Time, Weight, MaxFails and FileTimeout for all the upstream servers. And for the Nginx proxy cache there are Size, Capacity (live information!) and all information above per zone – there is an additional article here Live status information like used space and more for nginx proxy cache.

Building the module

We are going to build an Nginx dynamic module. The module must be loaded in the configuration and if you do not want to use it you could always remove the load directive.

Using dynamically loaded modules in Nginx no need to replace the original Nginx binary, which comes from the packaging system of your Linux distribution. Of course, you are going to need the GNU GCC to build this module, so install it accordingly to your Linux distribution.

STEP 1) Download the module

Download the module from the official place in Github – https://github.com/vozlt/nginx-module-vts You could use git to clone the code locally from the master with:

git clone https://github.com/vozlt/nginx-module-vts

Or you can click on the “releases” page https://github.com/vozlt/nginx-module-vts/releases and download the latest archive. Probably this is better, because the files in “releases” include more stable code than the master branch.
At present the latest release is “v0.1.18” – https://github.com/vozlt/nginx-module-vts/archive/v0.1.18.tar.gz

STEP 2) Build the source as an Nginx dynamically link module

Here is a very important thing, if you want to build this module as an Nginx dynamically linked you may do it only for specific Nginx version and build. The build options should be the same as the original binary and you need the same version of the Nginx source. So execute Nginx binary with the option “-V” to get the “configure arguments” of your currently installed Nginx binary and the exact Nginx version. Download the same exact version of Nginx source from the official Nginx download page: https://nginx.org/en/download.html (if the version you are trying to download does not have link in the page you can always try to manually replace the version string in the url https://nginx.org/download/nginx-1.17.2.tar.gz, if you need 1.15.4 replace 1.17.2 with 1.15.4 like https://nginx.org/download/nginx-1.15.4.tar.gz)

[myuser@srv ~]# nginx -V
nginx version: nginx/1.17.2
built by gcc 4.8.5 20150623 (Red Hat 4.8.5-36) (GCC) 
built with OpenSSL 1.0.2k-fips  26 Jan 2017
TLS SNI support enabled
configure arguments: --prefix=/etc/nginx --sbin-path=/usr/sbin/nginx --modules-path=/usr/lib64/nginx/modules --conf-path=/etc/nginx/nginx.conf --error-log-path=/var/log/nginx/error.log --http-log-path=/var/log/nginx/access.log --pid-path=/var/run/nginx.pid --lock-path=/var/run/nginx.lock --http-client-body-temp-path=/var/cache/nginx/client_temp --http-proxy-temp-path=/var/cache/nginx/proxy_temp --http-fastcgi-temp-path=/var/cache/nginx/fastcgi_temp --http-uwsgi-temp-path=/var/cache/nginx/uwsgi_temp --http-scgi-temp-path=/var/cache/nginx/scgi_temp --user=nginx --group=nginx --with-compat --with-file-aio --with-threads --with-http_addition_module --with-http_auth_request_module --with-http_dav_module --with-http_flv_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_mp4_module --with-http_random_index_module --with-http_realip_module --with-http_secure_link_module --with-http_slice_module --with-http_ssl_module --with-http_stub_status_module --with-http_sub_module --with-http_v2_module --with-mail --with-mail_ssl_module --with-stream --with-stream_realip_module --with-stream_ssl_module --with-stream_ssl_preread_module --with-cc-opt='-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector-strong --param=ssp-buffer-size=4 -grecord-gcc-switches -m64 -mtune=generic -fPIC' --with-ld-opt='-Wl,-z,relro -Wl,-z,now -pie'
[myuser@srv ~]# wget https://nginx.org/download/nginx-1.17.2.tar.gz
[myuser@srv ~]# tar xf nginx-1.17.2
[myuser@srv ~]# ls -al nginx-1.17.2
total 756
drwxr-xr-x. 8 1001 1001    158 Jul 23 12:01 .
drwxr-xr-x. 4 root root     79 Aug 14 07:36 ..
drwxr-xr-x. 6 1001 1001   4096 Aug 14 07:29 auto
-rw-r--r--. 1 1001 1001 298273 Jul 23 12:01 CHANGES
-rw-r--r--. 1 1001 1001 455092 Jul 23 12:01 CHANGES.ru
drwxr-xr-x. 2 1001 1001    168 Aug 14 07:29 conf
-rwxr-xr-x. 1 1001 1001   2502 Jul 23 12:01 configure
drwxr-xr-x. 4 1001 1001     72 Aug 14 07:29 contrib
drwxr-xr-x. 2 1001 1001     40 Aug 14 07:29 html
-rw-r--r--. 1 1001 1001   1397 Jul 23 12:01 LICENSE
drwxr-xr-x. 2 1001 1001     21 Aug 14 07:29 man
-rw-r--r--. 1 1001 1001     49 Jul 23 12:01 README
drwxr-xr-x. 9 1001 1001     91 Aug 14 07:29 src
[myuser@srv ~]# wget https://github.com/vozlt/nginx-module-vts/archive/v0.1.18.tar.gz
[myuser@srv ~]# tar xf v0.1.18.tar.gz
[myuser@srv ~]# ls -al nginx-module-vts-0.1.18/
total 84
drwxrwxr-x. 6 root root   112 Jun 22  2018 .
drwxr-xr-x. 4 root root    79 Aug 14 07:36 ..
-rw-rw-r--. 1 root root  7333 Jun 22  2018 Changes
-rw-rw-r--. 1 root root  2954 Jun 22  2018 config
-rw-rw-r--. 1 root root  1312 Jun 22  2018 LICENSE
-rw-rw-r--. 1 root root 57573 Jun 22  2018 README.md
drwxrwxr-x. 2 root root    62 Jun 22  2018 share
drwxrwxr-x. 2 root root  4096 Jun 22  2018 src
drwxrwxr-x. 2 root root  4096 Jun 22  2018 t
drwxrwxr-x. 2 root root    70 Jun 22  2018 util
[myuser@srv ~]# cd nginx-1.17.2
[myuser@srv nginx-1.17.2]# 

Execute the same build script with the same configure arguments as shown after “nginx -V” and add at the end the option to build a dynamically linked module with the directory where it is situated (–add-dynamic-module=../nginx-module-vts-0.1.18/). Your “configure arguments” might be different do not copy the ones below just use the ones from your “nginx -V”.

[myuser@srv nginx-1.17.2]# ./configure --prefix=/etc/nginx --sbin-path=/usr/sbin/nginx --modules-path=/usr/lib64/nginx/modules --conf-path=/etc/nginx/nginx.conf --error-log-path=/var/log/nginx/error.log --http-log-path=/var/log/nginx/access.log --pid-path=/var/run/nginx.pid --lock-path=/var/run/nginx.lock --http-client-body-temp-path=/var/cache/nginx/client_temp --http-proxy-temp-path=/var/cache/nginx/proxy_temp --http-fastcgi-temp-path=/var/cache/nginx/fastcgi_temp --http-uwsgi-temp-path=/var/cache/nginx/uwsgi_temp --http-scgi-temp-path=/var/cache/nginx/scgi_temp --user=nginx --group=nginx --with-compat --with-file-aio --with-threads --with-http_addition_module --with-http_auth_request_module --with-http_dav_module --with-http_flv_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_mp4_module --with-http_random_index_module --with-http_realip_module --with-http_secure_link_module --with-http_slice_module --with-http_ssl_module --with-http_stub_status_module --with-http_sub_module --with-http_v2_module --with-mail --with-mail_ssl_module --with-stream --with-stream_realip_module --with-stream_ssl_module --with-stream_ssl_preread_module --with-cc-opt='-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector-strong --param=ssp-buffer-size=4 -grecord-gcc-switches -m64 -mtune=generic -fPIC' --with-ld-opt='-Wl,-z,relro -Wl,-z,now -pie' --add-dynamic-module=../nginx-module-vts-0.1.18/
checking for OS
 + Linux 3.10.0-957.1.3.el7.x86_64 x86_64
checking for C compiler ... found
 + using GNU C compiler
 + gcc version: 4.8.5 20150623 (Red Hat 4.8.5-36) (GCC) 
checking for gcc -pipe switch ... found
checking for --with-ld-opt="-Wl,-z,relro -Wl,-z,now -pie" ... found
checking for -Wl,-E switch ... found
checking for gcc builtin atomic operations ... found
.....
.....
checking for OpenSSL library ... found
checking for zlib library ... found
creating objs/Makefile

Configuration summary
  + using threads
  + using system PCRE library
  + using system OpenSSL library
  + using system zlib library

  nginx path prefix: "/etc/nginx"
  nginx binary file: "/usr/sbin/nginx"
  nginx modules path: "/usr/lib64/nginx/modules"
  nginx configuration prefix: "/etc/nginx"
  nginx configuration file: "/etc/nginx/nginx.conf"
  nginx pid file: "/var/run/nginx.pid"
  nginx error log file: "/var/log/nginx/error.log"
  nginx http access log file: "/var/log/nginx/access.log"
  nginx http client request body temporary files: "/var/cache/nginx/client_temp"
  nginx http proxy temporary files: "/var/cache/nginx/proxy_temp"
  nginx http fastcgi temporary files: "/var/cache/nginx/fastcgi_temp"
  nginx http uwsgi temporary files: "/var/cache/nginx/uwsgi_temp"
  nginx http scgi temporary files: "/var/cache/nginx/scgi_temp"

[myuser@srv nginx-1.17.2]# make -j 4
make -f objs/Makefile
make[1]: Entering directory `/root/ttt/nginx-1.17.2'
cc -c -pipe  -O -W -Wall -Wpointer-arith -Wno-unused-parameter -Werror -g -O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector-strong --param=ssp-buffer-size=4 -grecord-gcc-switches -m64 -mtune=generic -fPIC -I src/core -I src/event -I src/event/modules -I src/os/unix -I objs \
        -o objs/src/core/nginx.o \
        src/core/nginx.c
.....
.....
objs/src/stream/ngx_stream_ssl_preread_module.o \
objs/ngx_modules.o \
-Wl,-z,relro -Wl,-z,now -pie -ldl -lpthread -lpthread -lcrypt -lpcre -lssl -lcrypto -ldl -lpthread -lz \
-Wl,-E
cc -o objs/ngx_http_vhost_traffic_status_module.so \
objs/addon/src/ngx_http_vhost_traffic_status_module.o \
objs/addon/src/ngx_http_vhost_traffic_status_variables.o \
objs/addon/src/ngx_http_vhost_traffic_status_string.o \
objs/addon/src/ngx_http_vhost_traffic_status_shm.o \
objs/addon/src/ngx_http_vhost_traffic_status_node.o \
objs/addon/src/ngx_http_vhost_traffic_status_filter.o \
objs/addon/src/ngx_http_vhost_traffic_status_control.o \
objs/addon/src/ngx_http_vhost_traffic_status_limit.o \
objs/addon/src/ngx_http_vhost_traffic_status_display.o \
objs/addon/src/ngx_http_vhost_traffic_status_display_json.o \
objs/addon/src/ngx_http_vhost_traffic_status_display_prometheus.o \
objs/addon/src/ngx_http_vhost_traffic_status_set.o \
objs/addon/src/ngx_http_vhost_traffic_status_dump.o \
objs/ngx_http_vhost_traffic_status_module_modules.o \
-Wl,-z,relro -Wl,-z,now -pie \
-shared
make[1]: Leaving directory `/home/myuser/nginx-1.17.2'

The module (and the Nginx binary, which we are not going to use it, but it is there) is built successfully. Just copy only the module (do not execute “make install”, because it will overwrite your original Nginx binary and multiple additional files) in “/etc/nginx/modules/”:

[myuser@srv nginx-1.17.2]# sudo cp objs/ngx_http_vhost_traffic_status_module.so /etc/nginx/modules/

And you are ready to use it.

STEP 3) Use the module

To have the same output as the image we showed at the begining of this article you should include tthree options in your Nginx configuration file:

1. Load the module. Global option.
2. Initialize the module. In the http block.
3. Activate the status page under Nginx location directive. Use limit directives to have security. In server block.

Here part of our Nginx configuration:

user nginx nginx;
worker_processes auto;
pid /run/nginx.pid;
worker_rlimit_nofile 100000;

error_log /var/log/nginx/error_log info;

#load modules
load_module modules/ngx_http_vhost_traffic_status_module.so;

events {
        worker_connections 81920;
        use epoll;
}
.....
.....
http {
        #extended status
        vhost_traffic_status_zone;
.....
.....
        server{
                listen          192.168.0.101;
.....
                location /status {
                        vhost_traffic_status_display;
                        vhost_traffic_status_display_format html;
                        allow           10.10.10.10;
                        allow           127.0.0.1;
                        deny            all;
                }
.....
}

This is not a complete and valid Nginx configuration file, we included only important parts and all of the vhost_traffic_status module directive to show how you can use the module. It is good to block updating your Nginx packages because if you change the version the module won’t work and you must build it against the new version.