ngx_waf

# Installation Guide

Please read the Version Description first to pick the right version.

nginx provides two ways to install modules, namely 'statically linked' and 'dynamically loaded', and the modules installed in each way are called 'static modules' and dynamic modules'.

# Static Modules

NOTE

Compiling and installing the module may require some dependencies, such as gcc, so please work out the dependencies yourself; this article does not provide such information.

WARNING

Compiling and installing a new module requires knowing the parameters of the current nginx's configure script, which you can get by running nginx -V. Here is an example.

nginx version: nginx/1.19.6
built by gcc 9.3.0 (Ubuntu 9.3.0-17ubuntu1~20.04)
built with OpenSSL 1.1.1i  8 Dec 2020
TLS SNI support enabled
configure arguments: --with-mail=dynamic --with-openssl=/usr/local/src/openssl-OpenSSL_1_1_1i --prefix=/usr/local/nginx --user=nginx --group=nginx --with-file-aio --with-http_ssl_module --with-http_geoip_module --with-http_v2_module --with-http_realip_module --with-stream_ssl_preread_module --with-http_addition_module --with-http_xslt_module=dynamic --with-http_image_filter_module=dynamic --with-http_sub_module --with-http_dav_module --with-http_flv_module --with-http_mp4_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_random_index_module --with-http_secure_link_module --with-http_degradation_module --with-http_slice_module --with-http_perl_module --with-http_stub_status_module --with-http_auth_request_module --with-mail=dynamic --with-mail_ssl_module --with-pcre --with-pcre-jit --with-stream=dynamic --with-stream_ssl_module --with-debug --with-cc-opt='-O3 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector-strong --param=ssp-buffer-size=4 -grecord-gcc-switches -m64 -mtune=generic'

Be sure to remember what comes after configure arguments:, which will be replaced by ARG below.

Installing a static module requires recompiling the entire nginx, which takes longer than installing a dynamic module.

First download the corresponding version of nginx, download page (opens new window). The following is an example of nginx-1.20.1.

cd /usr/local/src
wget https://nginx.org/download/nginx-1.20.1.tar.gz
tar -zxf nginx-1.20.1.tar.gz

Then download the source code of this module, the following will use the stable version of the source code

cd /usr/local/src
git clone -b lts https://github.com/ADD-SP/ngx_waf.git

Next you should run the configuration script.

cd /usr/local/src/nginx-1.20.1
./configure ARG --add-module=/usr/local/src/ngx_waf --with-debug
sed -i 's/^\(CFLAGS.*\)/\1 -fstack-protector-strong -Wno-sign-compare/' objs/Makefile

Then start compiling.

# Not using parallel compilation
make

# Use parallel compilation.
make -j$(nproc)

NOTE

Parallel compilation will improve the compilation speed, but there is a chance of strange errors, so you can disable parallel compilation if it goes wrong.

Finally, you should stop nginx and replace the nginx binary. Assume here that the absolute path to the nginx binary is /usr/local/nginx/sbin/nginx.

cp objs/nginx /usr/local/nginx/sbin/nginx

Hot Deployment

If you do not want to not nginx when replacing binaries, you can refer to the official documentation for hot deployment scenarios (opens new window).

# Dynamic Modules

Compiling and installing dynamic modules does not require recompiling the entire nginx, only all modules, which is faster than static modules, which is the recommended way in this document.

The process of downloading nginx source code and module source code is the same as for Static Modules and will not be repeated.

Run the configuration script

./configure --add-dynamic-module=/usr/local/src/ngx_waf --with-compat --with-debug
sed -i 's/^\(CFLAGS.*\)/\1 -fstack-protector-strong -Wno-sign-compare/' objs/Makefile

Then start compiling the dynamic module

make modules

You should then stop nginx and copy the dynamic modules to the modules directory. Assume here that the absolute path to the modules directory is /usr/local/nginx/modules.

cp objs/*.so /usr/local/nginx/modules

Finally, add a line to the top of the nginx configuration file.

load_module "/usr/local/nginx/modules/ngx_http_waf_module.so";

← Configuration Guide →