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.
Server zones information
- 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:
- Load the module. Global option.
- Initialize the module. In the http block.
- 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.