Monday, December 24, 2012

Nginx Http Subs Module for CentOS - Packaging Howto

The case

I recently involved in a reverse proxy project using nginx as reverse proxy server. Turns out that nginx has a built in HttpSubModule that allow us to replace urls in http stream, which is a very important requirements for us.  But the problem is that the HttpSubModule only allow one replacement per location. 
After a few searches, found that an additional HttpSubsModule (notice the additional s)  will do the task, allowing multiple replacement per location.The nginx wiki is kind enough to provide installation instructions for HttpSubsModule, but provides no rpm package.

DISCLAIMER: This blog post shows step by step tutorial to produce a RPM package file. If you only interested in installing nginx with HttpSubsModule, please jump to the last heading 'Installation'. But if you're not on Centos 6 x86_64, maybe you really should follow all the steps anyway.

Repository Hunt

I prefer repository packages other than compiling manually. We found that EPEL repository carries nginx 0.8.55 for Centos 5 (here) or 1.0.15 for Centos 6 (here), but unfortunately these are compiled without HttpSubsModule. Nginx site points us to a repository at which carries nginx 1.2.6, but this is too without HttpSubsModule.

SRPM install

First to install the source RPM for nginx  (do this as a normal user other than root) :
rpm -i nginx-1.2.6-1.el6.ngx.src.rpm
 Prepare your system for rpmbuild and install devel packages (do these as root):
yum install rpm-build
yum install zlib-devel pcre-devel openssl-devel


Time to bite the bullet and rebuild nginx package.
Rpmbuild is a tool to build rpm. It is a packaging tool with functionality similar to Java's Ant, but albeit a complex one. In the executing rpmbuild we executed these phases:
  1. %prep stage
  2. %build stage
  3. %install stage
The spec file provides similar function such as ant's build.xml, that is specifying build steps and sources.

After wrestling with some rpmbuild online documentation, I found that essentially I need to (do these as a normal user):
  • download the http subs module sources using git, compress it into tar gz format, and host it in a website somewhere
  • add additional source line  in nginx.spec, and also download the tar gzipped file to ~/rpmbuild/SOURCES directory (rpmbuild expects the tar gz file exists with the same name as the URL given below, it won't download it for you)
Source5: nginx.vh.default.conf
Source6: nginx.vh.example_ssl.conf
Source7: nginx.suse.init
  • add additional %setup invocation to extract the httpsubs.tar.gz. The -q means quiet (disable tar's chattiness), -a 8 means extract source 8 after cd to package directory, -T means don't extract source 0 again,  -D means dont delete top level directory before extract. Really complex line for simple behavior.
%setup -q
%setup -q -T -D -a 8
  • add clauses to the configure command (there are two of them):
         --with-http_addition_module \
        --with-http_sub_module \
        --add-module=ngx_http_substitutions_filter_module \        --with-http_dav_module \
        --with-http_flv_module \
And run rpmbuild (still as user), pray that there are no errors :
  • rpmbuild -ba nginx.spec
Voila, we got at rpm files at /home/username/rpmbuild/RPMS/x86_64.


If you don't want to create rpm file, but only want to install one, and it happens that you're running Centos 6 on x86_64 platform, feel free to download my resulting rpm file at
From the resulting rpm file (whether from download or following steps above), install it (as root):

rpm -i nginx-1.2.6-1.el6.ngx.x86_64.rpm
Thats all.. I hope these steps works for you too.


L. Matthew Blancett said...

Care to publish your spec file? I'm working one up too ;)

L. Matthew Blancett said...

Care to publish your spec file? I'm working one up too ;)