Nginx dynamic modules

Introduction

I use the nginx-extras package from Launchpad, because it has some pre-loaded modules that I use. I recently upgraded to Nginx 1.11.5 and noticed that my Headers More module wasn’t working. Specifically, I was getting this error.

[emerg] unknown directive “more_clear_headers” in /etc/nginx/sites-available/headers.conf

In my site file, I had to comment out the line calling the headers.conf file in order to figure out what was going on.

#Include configuration files
#include /etc/nginx/sites-available/headers.conf;

Commenter Vasile pointed out the same issue, so I opened a ticket on the Nginx Trac, which was promptly closed because I don’t read release notes. Nginx 1.9.11 introduced dynamic modules, which allow modules to be loaded and unloaded as necessary (but they still need compiled into Nginx, unlike Apache).

In the first release of dynamic modules, you still need to compile the optional modules at the same time as the NGINX binary, but you also create a separate shared object for each dynamically loaded module and use a directive in the NGINX configuration file to enable and disable loading of the shared object at runtime.

Looking at the output of nginx -V, you can see that the module is added dynamically, which means it was compiled into Nginx (from the Launchpad package), but not loaded.

--add-dynamic-module=/build/nginx-bz8zMQ/nginx-1.11.5/debian/modules/headers-more-nginx-module

Loading the module

Loading the module is a pretty straight-forward process.

Find module name

First, you need to find the module name. The modules are typically loaded under /usr/share/nginx/modules, as shown below.

--> ls -laL /usr/share/nginx/modules
total 1380
drwxr-xr-x 2 root root   4096 Oct 13 21:44 .
drwxr-xr-x 3 root root   4096 Oct 13 21:09 ..
-rw-r--r-- 1 root root  14304 Oct 13 10:14 ndk_http_module.so
-rw-r--r-- 1 root root  10544 Oct 13 10:14 ngx_http_auth_pam_module.so
-rw-r--r-- 1 root root  18992 Oct 13 10:14 ngx_http_cache_purge_module.so
-rw-r--r-- 1 root root  45072 Oct 13 10:14 ngx_http_echo_module.so
-rw-r--r-- 1 root root  23664 Oct 13 10:14 ngx_http_fancyindex_module.so
-rw-r--r-- 1 root root  20096 Oct 13 10:14 ngx_http_geoip_module.so
-rw-r--r-- 1 root root  28336 Oct 13 10:14 ngx_http_headers_more_filter_module.so
-rw-r--r-- 1 root root  23312 Oct 13 10:14 ngx_http_image_filter_module.so
-rw-r--r-- 1 root root 400944 Oct 13 10:14 ngx_http_lua_module.so
-rw-r--r-- 1 root root  23264 Oct 13 10:14 ngx_http_perl_module.so
-rw-r--r-- 1 root root  18848 Oct 13 10:14 ngx_http_subs_filter_module.so
-rw-r--r-- 1 root root  32064 Oct 13 10:14 ngx_http_uploadprogress_module.so
-rw-r--r-- 1 root root  18592 Oct 13 10:14 ngx_http_upstream_fair_module.so
-rw-r--r-- 1 root root  19168 Oct 13 10:14 ngx_http_xslt_filter_module.so
-rw-r--r-- 1 root root  99464 Oct 13 10:14 ngx_mail_module.so
-rw-r--r-- 1 root root 433792 Oct 13 10:14 ngx_nchan_module.so
-rw-r--r-- 1 root root 149016 Oct 13 10:14 ngx_stream_module.so

The module name in this case is ngx_http_headers_more_filter_module.so.

Load module

Next, you need to add the module to your /etc/nginx/nginx.conf file. The module needs to be loaded pretty early on in the file, so I put mine right after the pid directive.

user www-data;
worker_processes auto;
pid /run/nginx.pid;

#Load dynamic modules
        load_module modules/ngx_http_headers_more_filter_module.so;

Reload Nginx

Next, test Nginx, and if you don’t get any errors, reload it. Don’t forget to uncomment any commented out modules from your site file.

sudo nginx -t
sudo service nginx restart

Now, your module should be working.

 

Hope that helps!

Logan

2 thoughts on “Nginx dynamic modules”

  1. Thank you for making my day. Been trying to figure out why nginx wasn’t working after making an updated AMI for our server.

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.