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
Optional
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.
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.