others-How to load dynamic module in nginx?

1. Purpose

In this post, I would demonstrate how to load dynamic module into nginx, I would compile the module from source code, and then load it to the nginx.

2. The solution

Say if we what to load a module named echo to nginx.

2.1 Download source of the nginx

First, we need the source code of currently running nginx , we would use that code to compile our module’s source code.

Check the version of current nginx:

$ nginx -v
nginx version: nginx/1.20.0

Then we can get the source code of nginx 1.20 from official site of nginx:

wget https://github.com/nginx/nginx/archive/release-1.20.0.tar.gz

After downloaded, unzip it:

tar zxvf release-1.20.0.tar.gz

2.2 Download source of module

Download the tarball:

wget https://github.com/openresty/echo-nginx-module/archive/refs/tags/v0.62.tar.gz

And then extract it to module_sources directory of the nginx source, then we got this directory structure:

The root is nginx source directory:

.
|-- auto
|   |-- cc
|   |-- define
|   |-- endianness
|   |-- feature
|   |-- have
|   |-- have_headers
|   |-- os
|   |-- sources
|   |-- stubs
|   |-- summary
|   |-- threads
|   |-- types
|   `-- unix
|-- CHANGES
|-- CHANGES.ru
|-- conf
|   |-- fastcgi.conf
|   |-- fastcgi_params
|   |-- koi-utf
|   |-- koi-win
|   |-- mime.types
|   |-- nginx.conf
|   |-- scgi_params
|   |-- uwsgi_params
|   `-- win-utf
|-- configure
|-- contrib
|   |-- geo2nginx.pl
|   |-- README
|   |-- unicode2nginx
|   `-- vim
|-- html
|   |-- 50x.html
|   `-- index.html
|-- LICENSE
|-- Makefile
|-- man
|   `-- nginx.8
|-- module_sources
|   |-- echo-nginx-module-0.62
|   `-- v0.62.tar.gz
|-- objs
|   |-- addon
|   |-- autoconf.err
|   |-- Makefile
|   |-- nginx
|   |-- nginx.8
|   |-- ngx_auto_config.h
|   |-- ngx_auto_headers.h
|   |-- ngx_http_echo_module_modules.c
|   |-- ngx_http_echo_module_modules.o
|   |-- ngx_http_echo_module.so
|   |-- ngx_http_image_filter_module_modules.c
|   |-- ngx_http_image_filter_module_modules.o
|   |-- ngx_http_image_filter_module.so
|   |-- ngx_modules.c
|   |-- ngx_modules.o
|   |-- ngx_stream_module_modules.c
|   |-- ngx_stream_module_modules.o
|   |-- ngx_stream_module.so
|   `-- src
|-- README
`-- src
    |-- core
    |-- event
    |-- http
    |-- mail
    |-- misc
    |-- os
    `-- stream

24 directories, 57 files

2.3 Compile the source of module

Install the dependencies:

sudo apt install make gcc zlib1g-dev libpcre3-dev libssl-dev

Get the currently running nginx’s build options:

nginx -V

then compile the module with --add-dynamic-module and original options:

./configure --add-dynamic-module=./module_sources/echo-nginx-module-0.62 --with-http_ssl_module --with-http_image_filter_module=dynamic --modules-path=/etc/nginx/modules --with-http_v2_module --with-stream=dynamic --with-http_addition_module --with-http_mp4_module

Then

make modules

Then we got the module’s .so files in the objs directory:

root@launch-advisor-20191120:~/nginx_source/nginx-release-1.20.0# ll objs/ngx_http_echo_module*
-rwxr-xr-x 1 root root 500464 Jan 17 11:15 objs/ngx_http_echo_module.so*
-rw-r--r-- 1 root root    339 Jan 17 11:15 objs/ngx_http_echo_module_modules.c
-rw-r--r-- 1 root root  35424 Jan 17 11:15 objs/ngx_http_echo_module_modules.o

2.4 Deploy the module in nginx

copy the module to nginx modules path: say if your module path is /etc/nginx/modules:

 ⚡ root@launch-advisor-20191120  ~/nginx_source/nginx-1.20.0  cp objs/ngx_http_echo_module.so /etc/nginx/modules/

 ⚡ root@launch-advisor-20191120  ~/nginx_source/nginx-1.20.0  ll /etc/nginx/modules
total 1.6M
-rwxr-xr-x 1 root root 544K Jan 18 17:03 ngx_http_echo_module.so
-rwxr-xr-x 1 root root 135K Jan 18 16:46 ngx_http_image_filter_module.so
-rwxr-xr-x 1 root root 937K Jan 18 16:46 ngx_stream_module.so

change /etc/nginx/nginx.conf,add this line to main block:

load_module modules/ngx_http_echo_module.so

2.5 Test the module

Now check if the module is correctly installed:

nginx -t
nginx -s reload

We should see this:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

It works!

3. Summary

In this post, I demonstrated how to add dynamic module to nginx by building from module’s source code . That’s it, thanks for your reading.