Introducing Dynamic Modules in NGINX 1.9.11

Andrew Hutchings

Today 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.

Editor – In NGINX 1.11.5 and later (and NGINX Plus R11 and later), you can compile dynamic modules without also compiling the full NGINX binary. For instructions see Compiling Dynamic Modules for NGINX Plus.

The next NGINX Plus release (NGINX Plus R9) will build on this dynamic modules feature. We plan to establish a managed NGINX 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.

Static modules are compiled into the NGINX executable

In the first release of dynamic modules, you still need to compile the optional NGINX 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.

Dynamic modules are compiled into a separate binary module shared object

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, ssl}_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_module argument:

[@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop

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 dynamic module is loaded in. You can specify a path relative to the source directory, as in these examples, or a full path.

[@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop

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:

[@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop

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 to discuss your use cases.

About the Author

Andrew Hutchings

More blogs by Andrew Hutchings