Introducing Dynamic Modules in NGINX 1.9.11 - NGINX

Recently, we released open source NGINX version 1.9.11, with a new feature that we believe will have a huge impact on how you use NGINX and NGINX Plus: dynamic modules. With dynamic modules, you can optionally load separate shared object files at runtime as modules – both third-party modules and some native NGINX modules. The new implementation maintains backward compatibility with the module API as much as possible.

The next NGINX Plus release (NGINX Plus R9) will build on this dynamic modules feature. We plan to establish a managed modules repository with a range of third-party modules that we have tested and certified against NGINX Plus, making it easier for you to add common extensions to NGINX Plus with confidence. If you would like to have your open source or commercial modules included in our repository, please reach out to us through the Contact Sales link.

Up until now, if you wanted to create a module for NGINX you had to compile it into an NGINX binary along with the NGINX source code. The module was loaded with NGINX every time, whether you wanted it or not. For packagers of operating system distributions, this made it very hard to create custom NGINX binaries for every user.

In the first release of dynamic modules, you still need to compile the optional modules at the same time as the NGINX binary, but you also create a separate shared object for each dynamically loaded module and use a directive in the NGINX configuration file to enable and disable loading of the shared object at runtime.

Dynamically Loading NGINX Modules

In the first release, the following NGINX modules and module bundles can be built dynamically:

• GeoIP (ngx_http_geoip_module)
• Image-Filter (ngx_http_image_filter_module)
• Mail (includes all Mail modules: ngx_mail_{core, auth, imap, pop3, proxy, smtp}_module)
• Stream (includes all Stream modules: ngx_stream_{core, access, limit_conn, proxy, ssl, upstream}_module)
• XSLT (ngx_http_xslt_module)

To generate the dynamically loadable shared objects, append =dynamic to the standard ‑‑with argument:

# ./configure --with-http_geoip_module=dynamic \

              --with-http_image_filter_module=dynamic \

              --with-mail=dynamic \

              --with-stream=dynamic \

              --with-http_xslt_module=dynamic

When you install the NGINX 1.9.11 source code, there is a new subdirectory called modules, and the build process places the binary shared objects there. By default, the path is /usr/local/nginx/modules.

To load a module at runtime, include the new load_module directive in the main context, specifying the path to the shared object file for the module, enclosed in quotation marks. When you reload the configuration or restart NGINX, the module is loaded in. You can specify a path relative to the source directory, as in these examples, or a full path.

load_module "modules/ngx_http_geoip_module.so";

load_module "modules/ngx_stream_module.so";

To dynamically “unload” a module, comment out or remove its load_module directive and reload the NGINX configuration. If any other directives in the file relate to the module you are unloading, remember to comment out or remove them as well.

Converting Third-Party Modules

For developers of many third-party traditional modules, converting to dynamic loading requires very little work. In many cases, you only need to edit the config file for your module source code. Other modules will need a bit more work. The NGINX Wiki includes a Module Conversion Guide and detailed information about the format of the module source config file.

To compile a third-party module that has been converted, use the new --add-dynamic-module argument and specify the path:

# ./configure --add-dynamic-module=/path/to/module/source

As with NGINX modules, a shared object is created and installed in the modules subdirectory, and you add a load_module directive for it to the NGINX configuration. Our developer relations team is available to assist with converting a module. Contact us via the NGINX development mailing list.

The Future of Dynamic Modules

In future releases, we plan to add the ability to compile modules after the NGINX binary has been compiled. We are also in the process of documenting the module API and this documentation will be freely available on the NGINX Wiki when complete.

To try out dynamic modules for yourself, download NGINX 1.9.11.

To try NGINX Plus, start your free 30-day trial today or contact us for a live demo.

This article was written by Andrew Hutchings.