Nginx 1.9.11 released with support for dynamic modules

On February 9, the release of nginx 1.91.11 took place with the long-awaited support of dynamic modules , which was announced by nginx developers at Habré in April 2015 .



List of changes

• Addendum: now resolver supports TCP.
• Addendum: dynamic modules .
• Correction: when using HTTP / 2, the $ request_length variable did not take into account the size of the request headers.
• Bugfix: in the ngx_http_v2_module module.

Dynamic modules are compiled as separate .so files and loaded during the operation of nginx, at any time. No need to recompile nginx every time you add a module.
')
The documentation states that not every static module can be converted to dynamic. Do not do such a conversion for the modules that patch the source code of nginx, they will not work. And recommend using only those API calls that are directly intended for modules.

In addition, if the modules were to be installed in a specific order, then for dynamic modules you will need to specify the value ngx_module_order .

APIs are the same for both original static modules and dynamic ones.

Compiling a dynamic module

There was a new option in the config to add a module as a dynamic. Instead of using --add-module we write --add-dynamic-module . For example:

 $ ./configure --add-dynamic-module=/opt/source/ngx_my_module/ 

After compilation, a binary module will be created in the .so (Shared Object) file. This file is then transferred to the modules subdirectory in the nginx installation folder.

Loading a dynamic module

Modules can be loaded into nginx using the new load_module directive. For example:

 load_module modules/ngx_my_module.so; 

By default, the maximum limit is set to 128 concurrently loaded dynamic modules. This value can be changed in the NGX_MAX_DYNAMIC_MODULES variable in the nginx source code.

Configuration File Conversion

Below is an old-style config example for the third-party module ngx_http_response_module :

 ngx_addon_name=ngx_http_response_module HTTP_MODULES="$HTTP_MODULES ngx_http_response_module" NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_response_module.c" 

Now, to configure many things, the auto/module build script is used, so new configs are suitable for both static and dynamic modules. For the same ngx_http_response_module will look like this:

 ngx_addon_name=ngx_http_response_module if test -n "$ngx_module_link"; then ngx_module_type=HTTP ngx_module_name=ngx_http_response_module ngx_module_incs= ngx_module_deps= ngx_module_srcs="$ngx_addon_dir/ngx_http_response_module.c" ngx_module_libs= . auto/module else HTTP_MODULES="$HTTP_MODULES ngx_http_response_module" NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_response_module.c" fi 

As you can see, it includes the old config file, so old versions of nginx will be compatible with this module.

In more detail about a new format of a config see here .

An example of a complex module

Finally, the nginx documentation provides an example of a complex module that actually accommodates several modules in one package. They are a bit more difficult to convert. Such modules will have to be split into several modules when compiled as static modules, but you can leave a single .so file when compiled as dynamic modules. Here is an example of the ngx_rtmp_module module, which contains the CORE and HTTP modules.

The result of the conversion is as follows:

 ngx_addon_name="ngx_rtmp_module" RTMP_CORE_MODULES=" \ ngx_rtmp_module \ ngx_rtmp_core_module \ ngx_rtmp_cmd_module \ ngx_rtmp_codec_module \ ngx_rtmp_access_module \ ngx_rtmp_record_module \ ngx_rtmp_live_module \ ngx_rtmp_play_module \ ngx_rtmp_flv_module \ ngx_rtmp_mp4_module \ ngx_rtmp_netcall_module \ ngx_rtmp_relay_module \ ngx_rtmp_exec_module \ ngx_rtmp_auto_push_module \ ngx_rtmp_notify_module \ ngx_rtmp_log_module \ ngx_rtmp_limit_module \ ngx_rtmp_hls_module \ ngx_rtmp_dash_module \ " RTMP_HTTP_MODULES=" \ ngx_rtmp_stat_module \ ngx_rtmp_control_module \ " RTMP_DEPS=" \ $ngx_addon_dir/ngx_rtmp_amf.h \ $ngx_addon_dir/ngx_rtmp_bandwidth.h \ $ngx_addon_dir/ngx_rtmp_cmd_module.h \ $ngx_addon_dir/ngx_rtmp_codec_module.h \ $ngx_addon_dir/ngx_rtmp_eval.h \ $ngx_addon_dir/ngx_rtmp.h \ $ngx_addon_dir/ngx_rtmp_version.h \ $ngx_addon_dir/ngx_rtmp_live_module.h \ $ngx_addon_dir/ngx_rtmp_netcall_module.h \ $ngx_addon_dir/ngx_rtmp_play_module.h \ $ngx_addon_dir/ngx_rtmp_record_module.h \ $ngx_addon_dir/ngx_rtmp_relay_module.h \ $ngx_addon_dir/ngx_rtmp_streams.h \ $ngx_addon_dir/ngx_rtmp_bitop.h \ $ngx_addon_dir/ngx_rtmp_proxy_protocol.h \ $ngx_addon_dir/hls/ngx_rtmp_mpegts.h \ $ngx_addon_dir/dash/ngx_rtmp_mp4.h \ " RTMP_CORE_SRCS=" \ $ngx_addon_dir/ngx_rtmp.c \ $ngx_addon_dir/ngx_rtmp_init.c \ $ngx_addon_dir/ngx_rtmp_handshake.c \ $ngx_addon_dir/ngx_rtmp_handler.c \ $ngx_addon_dir/ngx_rtmp_amf.c \ $ngx_addon_dir/ngx_rtmp_send.c \ $ngx_addon_dir/ngx_rtmp_shared.c \ $ngx_addon_dir/ngx_rtmp_eval.c \ $ngx_addon_dir/ngx_rtmp_receive.c \ $ngx_addon_dir/ngx_rtmp_core_module.c \ $ngx_addon_dir/ngx_rtmp_cmd_module.c \ $ngx_addon_dir/ngx_rtmp_codec_module.c \ $ngx_addon_dir/ngx_rtmp_access_module.c \ $ngx_addon_dir/ngx_rtmp_record_module.c \ $ngx_addon_dir/ngx_rtmp_live_module.c \ $ngx_addon_dir/ngx_rtmp_play_module.c \ $ngx_addon_dir/ngx_rtmp_flv_module.c \ $ngx_addon_dir/ngx_rtmp_mp4_module.c \ $ngx_addon_dir/ngx_rtmp_netcall_module.c \ $ngx_addon_dir/ngx_rtmp_relay_module.c \ $ngx_addon_dir/ngx_rtmp_bandwidth.c \ $ngx_addon_dir/ngx_rtmp_exec_module.c \ $ngx_addon_dir/ngx_rtmp_auto_push_module.c \ $ngx_addon_dir/ngx_rtmp_notify_module.c \ $ngx_addon_dir/ngx_rtmp_log_module.c \ $ngx_addon_dir/ngx_rtmp_limit_module.c \ $ngx_addon_dir/ngx_rtmp_bitop.c \ $ngx_addon_dir/ngx_rtmp_proxy_protocol.c \ $ngx_addon_dir/hls/ngx_rtmp_hls_module.c \ $ngx_addon_dir/dash/ngx_rtmp_dash_module.c \ $ngx_addon_dir/hls/ngx_rtmp_mpegts.c \ $ngx_addon_dir/dash/ngx_rtmp_mp4.c \ " RTMP_HTTP_SRCS=" \ $ngx_addon_dir/ngx_rtmp_stat_module.c \ $ngx_addon_dir/ngx_rtmp_control_module.c \ " ngx_module_incs=$ngx_addon_dir ngx_module_deps=$RTMP_DEPS ngx_module_libs= if [ $ngx_module_link = DYNAMIC ] ; then ngx_module_name="$RTMP_CORE_MODULES $RTMP_HTTP_MODULES" ngx_module_srcs="$RTMP_CORE_SRCS $RTMP_HTTP_SRCS" . auto/module elif [ $ngx_module_link = YES ] ; then ngx_module_type=CORE ngx_module_name=$RTMP_CORE_MODULES ngx_module_srcs=$RTMP_CORE_SRCS . auto/module ngx_module_type=HTTP ngx_module_name=$RTMP_HTTP_MODULES ngx_module_incs= ngx_module_deps= ngx_module_srcs=$RTMP_HTTP_SRCS . auto/module fi USE_OPENSSL=YES 

The value of $ngx_module_link set to DYNAMIC for the dynamic module and YES for the static module. In the second case, the auto/module build script is called twice.

PS By the way, one of the forks of Tengine initially supported dynamic modules, for this purpose it was created, because the feature is very necessary.