Nginx - Build and add dynamic module (pagespeed, nginx-module-vts, …)

About

This page will show you how to add module to an existent nginx installation

If you want to add another module to an existing installation, you need to build it against the source as dynamic module (.so) and add it to your configuration.

Steps

Nginx preparation steps

Install the Nginx Dependencies

If you have installed Nginx from a package, you may need to install them

yum install -y redhat-rpm-config openssl-devel gc gcc gcc-c++ pcre-devel zlib-devel make wget libxml2-devel libxslt-devel gd-devel perl-ExtUtils-Embed GeoIP-devel gperftools gperftools-devel libatomic_ops-devel perl-ExtUtils-Embed

Download and zunip the Nginx source

• Check your Nginx version

nginx -v

• Download

wget https://nginx.org/download/nginx-${nginx_version}.tar.gz
# example
wget https://nginx.org/download/nginx-1.16.1.tar.gz

• unzip

tar zxf nginx-1.16.1.tar.gz

Module preparation steps

Install the module dependencies

Install the dependencies of your module

Example

• pagespeed

yum  install -y  gcc-c++ pcre-devel zlib-devel make unzip libuuid-devel

Download the module source

Example :

• pagespeed on x64. See the whole documentation here

wget https://github.com/apache/incubator-pagespeed-ngx/archive/1.13.35.2-stable.zip
unzip 1.13.35.2-stable.zip
# psol page speed dependency download
cd incubator-pagespeed-ngx-1.13.35.2
wget https://dl.google.com/dl/page-speed/psol/1.13.35.2-x64.tar.gz
tar zxf 1.13.35.2-x64.tar.gz

Configure and build

• Get the actual configuration arguments

nginx -V 
# or
nginx -V 2>&1 | grep 'configure arguments' | cut --delimiter ':' --fields=2-

• Add the module as dynamic

cd nginx
./configure \
   CONFIGURE_ARGUMENTS \ # should be replace with the output of nginx -V 
   --add-dynamic-module=/path/to/module

• Example with pagespeed and a little of magic to extract the actual arguments

cd nginx
IFS=$'\t'; ./configure \
        --add-dynamic-module=../incubator-pagespeed-ngx-1.13.35.2 \
        $(nginx -V 2>&1 | grep 'configure arguments' | cut --delimiter ':' --fields=2- | sed $'s/ --/\t--/g' | sed $'s/\t--param/ --param/g' | tr -d "'" | cut -c2- )  \
        > configure-stdout-ansible-cmd.log 2>&1

• build

make
# or with two process
make -j 2

Copy the shared library

Copy the shared library create into the module path.

• Get the prefix

nginx -V 2>&1 | grep 'configure arguments' | sed 's/--/\n--/g' | grep prefix

--prefix=/usr/share/nginx

• Copy

cp ./objs/dynamic_library.so  /usr/share/nginx/modules
# with pagespeed
cp ./objs/ngx_pagespeed.so  /usr/share/nginx/modules

Add it to the configuration, test and reload

• At the top

load_module "modules/dynamic_library.so";
# with pagespeed
load_module "modules/ngx_pagespeed.so";

• Verify the configuration

nginx -t

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

• Reload the service

systemctl reload nginx
# FYI: may be also restart ?
systemctl restart nginx

Support

module.so is not binary compatible in /etc/nginx/nginx.conf

There is a lot of chance that the configuration arguments passed to the configure steps are not the good one.

See configure_and_build

dlopen failed

nginx: [emerg] dlopen() "/usr/share/nginx/modules/ngx_pagespeed.so" failed (/usr/share/nginx/modules/ngx_pagespeed.so: cannot e...ginx.conf:11

selinux may unauthorize the loading of the library.