Project: Tengine (Orchestration & Management / Service Proxy)
File: ngx_dso_module.md

Name ==== Dynamic Module Loading Support (DSO*) Description =========== You can choose which functionalities to include by selecting a set of modules. A module will be compiled as a Dynamic Shared Object (DSO*) that exists from the main tengine binary. So you don't have to recompile tengine when you want to add or enable a functionality to it. If you want to enable a standard module, you can enable it via configure's option while compiling tengine, for instance, --with-http\_example_module or --with-http\_example\_module=shared. Run ./configure --help* for more details. The maximum of dynamically loaded modules is limited to 128. For now, only HTTP modules can be dynamically loaded. This feature is tested only on Linux/FreeBSD/MacOS. Example =========== worker_processes 1; dso { load ngxhttplua_module.so; load ngxhttpmemcached_module.so; } events { worker_connections 1024; } Directives ========== path Syntax: path path Default: NGX\_PREFIX/modules Context: dso This directive specifies the default path (prefix) of DSO modules. Example: path /home/dso/module; Sets the default path to /home/dso/module. load Syntax: load [module_name] \[module_path] Default: none Context: dso The load directive loads the shared object file and enables the module. module\_name is the name of the DSO module, and module\_path is the path of the DSO module. The order in which the module is searched is as follows: the absolute path. relative path to the prefix specified by the 'path' directive. relative path to the default path (NGX\_PREFIX/modules or path which is specified by the '--dso-path' configure option). Example: load ngxhttpemptygifmodule ngxhttpemptygifmodule.so; load ngxhttptest_module; load ngxhttptest2_module.so; It will load the ngx\http\empty\gif\module from ngx\http\empty\gif\module.so, ngx\http\testmodule and ngx\http\test2\module from ngx\http\test\module.so and ngx\http\test2\module.so. module_stub Syntax: module_stub module_name Default: none Context: dso This directive can insert a module into nginx's module array in order (see conf/module\stubs for more details). Note it will change the module runtime order. This directive does not need to be used in most cases. Don't use it or edit the *conf/module\stubs* file unless you know what you are doing. Example: modulestub ngxcore_module; modulestub ngxerrlog_module; modulestub ngxconf_module; modulestub ngxevents_module; modulestub ngxeventcoremodule; modulestub ngxepoll_module; modulestub ngxopenssl_module; modulestub ngxhttp_module; modulestub ngxhttpcoremodule; ....................... modulestub ngxhttpadditionfilter_module; modulestub ngxhttpmyfilter_module; It will place ngx\http\my\filter\module before ngx\http\addition\filter\module. include Syntax: include file_name Default: none Context: dso Specifies a file which contains the module stubs (via the module_stub directive). Example: include module_stubs; It will load conf/modulestubs and define the loading order of the modules (via the **module\stub directive). How to compile a module =========== Standard module If you want to enable a standard module after you compiled and installed tengine, you can take these steps as following. enable the standard module you wanted in shared mode, for example: $ ./configure --with-httpsubmodule=shared compile it: $ make install the shared object (.so): $ make dso_install It will copy the *.so files to the destination, or you can copy the files you want (in objs/modules) manually to the modules directory. Third party module You can use the dso_tool located in the directory of nginx binary to compile a third party module. Example: ./dso_tool --add-module=/home/dso/lua-nginx-module It will compile the ngx_lua module into a shared object, and install it to the default module path. You can specify the destination directory you want install to by the --dst option. Note =========== Removed dsotool tool and dso directive after the Tengine-2.3.0 version, If before using Tengine dso feature, you could switch to the Nginx official loadmodule directive, detailed reference .