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.
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.
In the first release, the following NGINX modules and module bundles can be built dynamically:
ngx_http_geoip_module
)ngx_http_image_filter_module
)ngx_mail_{core, auth, imap, pop3, proxy, smtp, ssl}_module
)ngx_stream_{core, access, limit_conn, proxy, ssl, upstream}_modul
e)ngx_http_xslt_module
)To generate the dynamically loadable shared objects, append =dynamic
to the standard --with_module
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 dynamic 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.
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.
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.
"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."