Editor – The blog post announcing the original release of dynamic module support (in NGINX Open Source 1.9.11, February 2016) redirects here. The build process described in that post is deprecated.
This post is part of a two‑part series on using third‑party dynamic modules with NGINX Open Source and NGINX Plus.
NGINX Open Source 1.11.5 and NGINX Plus Release R11 introduced binary compatibility for dynamic modules. This article explains how to compile third‑party modules for use with NGINX Open Source and NGINX Plus in a development environment. For instructions on building, deploying, and upgrading third‑party dynamic modules in a production environment, see Creating Installable Packages for Dynamic Modules.
For the sake of brevity, the remainder of this post refers to NGINX Plus only, except when the difference between it and NGINX Open Source is relevant. Except as noted, all statements about NGINX Plus also apply to NGINX Open Source.
Modules that can be loaded into NGINX Plus are written in C and conform to the API described in Extending NGINX on the NGINX Wiki. There is a large ecosystem of third‑party modules, ranging from language interpreters to security solutions, and some of these are included and supported in NGINX Plus.
Other third‑party modules, and modules that you have created yourself, need to be compiled independently and dynamically loaded into NGINX Plus at runtime. You can compile these modules for use with NGINX Plus by building them against NGINX Open Source as illustrated in the two examples below:
--with-compat
argument to the configure
commandThis example uses a simple Hello World module to show how to update the source for a module and load it into NGINX Plus. The “Hello World” module implements a simple directive (hello_world
) that responds to requests with a simple message.
Determine the NGINX Open Source version that corresponds to your NGINX Plus installation. In this example, it’s NGINX 1.11.5.
$ nginx -vnginx version: nginx/1.11.5 (nginx-plus-r11)
Download the corresponding NGINX Open Source package at nginx.org/download:
$ wget https://nginx.org/download/nginx-1.11.5.tar.gz$ tar -xzvf nginx-1.11.5.tar.gz
Obtain the source for the ‘Hello World’ NGINX module from GitHub:
$ git clone https://github.com/perusio/nginx-hello-world-module.git
The config shell file for a module defines how it is built, and its format is different for dynamic modules than for modules being built statically into an NGINX Open Source binary.
Modify the file nginx-hello-world-module/config to contain the following:
ngx_addon_name=ngx_http_hello_world_module
if test -n "$ngx_module_link"; then
ngx_module_type=HTTP
ngx_module_name=ngx_http_hello_world_module
ngx_module_srcs="$ngx_addon_dir/ngx_http_hello_world_module.c"
. auto/module
else
HTTP_MODULES="$HTTP_MODULES ngx_http_hello_world_module"
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_hello_world_module.c"
fi
For detailed information about compiling dynamic modules, including instructions on updating a module’s config file from the old format, see the NGINX Wiki.
Compile the module by first running the configure
script with the --with-compat
argument, which creates a standard build environment supported by both NGINX Open Source and NGINX Plus. Then run make
modules
to build the module:
$ cd nginx-1.11.5/$ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module
$ make modules
Copy the module library (.so file) to /etc/nginx/modules:
$ sudo cp objs/ngx_http_hello_world_module.so /etc/nginx/modules/
To load the module into NGINX Plus, add the load_module
directive in the top‑level (main) context of your nginx.conf configuration file (not within the http
or stream
context):
load_module modules/ngx_http_hello_world_module.so;
In the http
context, add a location
block with the hello_world
directive provided by the Hello World module. Requests to the location return the response hello
world
.
server { listen 80;
location / {
hello_world;
}
}
Reload your NGINX Plus configuration and test it with a simple request:
$ nginx -s reload$ curl http://localhost/
hello world
NAXSI is an easy‑to‑use, high‑performance web application firewall (WAF) that uses heuristics and a scoring system to identify suspicious requests such as XSS and SQL Injection attacks.
The NAXSI source has been updated to comply with the new format for the config shell file, so building a dynamic module for NGINX Plus is straightforward. The process is based on the NAXSI installation instructions:
$ git clone https://github.com/nbs-system/naxsi.git$ cd nginx-1.11.5/
$ ./configure --with-compat --add-dynamic-module=../naxsi/naxsi_src
$ make modules
$ sudo cp objs/ngx_http_naxsi_module.so /etc/nginx/modules
Load the module into the NGINX Plus core by adding the load_module
directive to the main context in your nginx.conf file:
load_module modules/ngx_http_naxsi_module.so;
NAXSI configuration is described in detail in the project documentation. The following NGINX configuration illustrates the module in action:
# Edit this 'include' directive to point to your naxsi_core.rules file
include /home/owen/src/naxsi/naxsi_config/naxsi_core.rules;
server {
listen 80;
location / {
root /usr/share/nginx/html;
# Enable NAXSI
SecRulesEnabled;
# Define where blocked requests go
DeniedUrl "/50x.html";
# CheckRules, determining when NAXSI needs to take action
CheckRule "$SQL >= 8" BLOCK;
CheckRule "$RFI >= 8" BLOCK;
CheckRule "$TRAVERSAL >= 4" BLOCK;
CheckRule "$EVADE >= 4" BLOCK;
CheckRule "$XSS >= 8" BLOCK;
# Don’t forget the error_log, where blocked requests are logged
error_log /tmp/naxsi.log;
}
error_page 500 502 503 504 /50x.html;
}
You can verify the correct operation of NAXSI with a pair of simple HTTP requests:
curl
http://localhost/
returns the standard NGINX Plus index page stored in /usr/share/nginx/html.curl
"http://localhost/?a=<>"
triggers NAXSI’s XSS detection and blocks the request, returning the standard 50x.html error page from /usr/share/nginx/html. It also logs a message to the error_log
.For production deployments, you can also download signed NAXSI releases at https://github.com/nbs-system/naxsi/tags and compile them in a similar fashion.
Note: The information in this section applies to NGINX Plus only. The set of dynamic modules that ships with prebuilt NGINX Open Source packages might differ from the ones shipped with NGINX Plus. Dynamic modules used with NGINX Open Source are supported in the same way as the NGINX source code and prebuilt binaries.
NGINX Plus ships with a number of dynamic modules that you can also download directly from our modules repository. For a list, see the Dynamic Modules page. These modules are of two types:
In addition, NGINX certifies modules from commercial vendors who participate in our NGINX Plus Certified Modules program. These modules are distributed and supported by their vendors. For a list, filter by author Certified Partner on the Dynamic Modules page.
NGINX does not test or support modules that you compile yourself (other community modules, modules provided by third‑party vendors that are not part of the NGINX Plus Certified Modules program, and custom modules). If you seek technical support for a problem, the NGINX support team may ask you to remove an unsupported module and reproduce the fault as part of our technical support process, so that they can verify whether or not the fault is caused by the unsupported module.
The dynamic modules build process for NGINX Plus allows you to take advantage of the broad ecosystem of NGINX Open Source modules, running them on the rich and fully supported NGINX Plus core.
If you are currently using NGINX Open Source with third‑party extensions, these extensions can most likely be compiled and loaded into NGINX Plus.
If you develop commercial or community modules, the new build process means your users can deploy your modules with NGINX Plus. To learn about certifying a commercial module, see NGINX Plus Certified Modules.
If you need assistance in developing a module or updating its config shell file, please check out the following resources:
The NGINX Developers mailing list is the go‑to place for community assistance, and our Professional Services team is also happy to assist.
To try dynamic modules with NGINX Plus yourself, start a free 30-day trial today or contact us to discuss your use cases.
"This blog post may reference products that are no longer available and/or no longer supported. For the most current information about available F5 NGINX products and solutions, explore our NGINX product family. NGINX is now part of F5. All previous NGINX.com links will redirect to similar NGINX content on F5.com."