Dynamic nginx modules allow you to extend the functionality of nginx without having to recompile the entire suite. However, compiling these modules is not exactly trivial.
First of all, you’ll want to pull the source code of the module to the target machine. For this example, I’ll be using the
ngx_http_ipset_blacklist module, available here. The following commands will be run as root.
cd /opt git clone https://github.com/Vasfed/nginx_ipset_blacklist.git
In case the module is static, you’ll want to convert its configuration to a dynamic one. You can figure out if a module is static by looking inside its
config file, present inside the root of the module. If this file contains a call to
auto/module, then it’s dynamic. Otherwise you’ll need to convert it.
config file of the
nginx_ipset_blacklist project looks like this:
ngx_addon_name=ngx_http_ipset_blacklist HTTP_MODULES="$HTTP_MODULES ngx_http_ipset_blacklist" NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_ipset_blacklist.c" NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ipset_read.c"
It’s quite easy to convert it to a dynamic module by changing the file to:
ngx_addon_name=ngx_http_ipset_blacklist if test -n "$ngx_module_link"; then ngx_module_type=HTTP ngx_module_name=ngx_http_ipset_blacklist ngx_module_srcs="$ngx_addon_dir/ngx_http_ipset_blacklist.c $ngx_addon_dir/ipset_read.c" . auto/module else HTTP_MODULES="$HTTP_MODULES ngx_http_ipset_blacklist" NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_ipset_blacklist.c" NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ipset_read.c" fi
You can read more about converting static modules to dynamic modules here.
In order to compile the module, you’ll need the nginx source code of the very same version that’s running on the target machine. You can figure out the version by calling:
It is highly recommended that you use or upgrade to nginx 1.11.5 or higher. This version introduced the
--with-compat option. It facilitates compiling additional dynamic modules with minimal effort assuming that nginx was originally compiled
--with-compat as well. For earlier versions, a world of pain and missing dependencies awaits you.
For this example, I’m using nginx 1.12.2. Let’s download and unpack the source code:
cd /opt wget http://nginx.org/download/nginx-1.12.2.tar.gz tar -xzvf nginx-1.12.2.tar.gz
Assuming your module lives under
/opt/nginx_ipset_blacklist, run the following:
cd /opt/nginx-1.12.2 ./configure --with-compat --add-dynamic-module=/opt/nginx_ipset_blacklist/ --with-cc-opt=-Wno-error
The last option
--with-cc-opt=Wno-error is optional and prevents converting warnings to errors. It was required in the case of the
nginx_ipset_blacklist module, but you might not need it.
./configure call succeeded, you can run:
This will build your module and place it inside the
objs/ folder. The compiled module bears the
.so extension. The final step is copying it over to the
cp objs/ngx_http_ipset_blacklist.so /etc/nginx/modules
In case something broke during the previous steps, you can always clean up the build directory, by calling:
…and starting again from the
The final step is actually using the module. Open your
/etc/nginx/nginx.conf and add the following line towards the beginning of the file:
…and restart nginx:
service nginx restart