One of the benefits of Nginx is that, in its unmodified state, it is such a light weight web server, running few core modules – and that's one reason it performs so well.
Generally though, we have specific server requirements and so we will likely want to add and/or remove Nginx modules at what Nginx calls compile-time.
To spell out what we're doing here, let's take a look at the Nginx installation process, in summary:-
- create and enter a download directory, /home/USERNAME/sources
- download and unzip Nginx, together with any required 3rd party modules
- compile/configure Nginx with those mods and any parameters
- install Nginx
- setup the nginx.conf configuration file
- setup a default sites virtual host file and a symlink
- setup your sites with virtual host files and symlinks
.. this guide covers 3. We've covered the rest, linked as above.
I'll be adding various guides about configuring popular non-default modules in due course.
Nginx Modules & Parameters: The 101
Nginx modules are the equivalent to, say, Firefox addons or WordPress plugins. They add functionality, ranging from server enhancements to website features.
For instance, if you want the options of shopping facilities on some site you want to host, you'll include the SSL (secure socket layer) module http_ssl_module. If you want to be able to stream Flash movies, you'll need the the FLV mod, http_flv_module. But maybe you want security enhancements, mail server capabilities and so on, and on (and on!)
And what if your want some special installation parameter, such as telling Linux where to install the Nginx error log file? Again that can be specified when you compile Nginx.
So What Is Nginx Compilation (or Configuration)?
Compiling – or configuring – is a Linux thing that developers such as from Nginx use to give us application options. Instead of installing a one-size-fits-no-one we can specify – compile or configure – a package just as we want it, adding options and maybe ditching others.
Then, once bespoke-compiled, we install the thing. So, put it another way, it's a bit like mixing a bunch of ingredients together .. before baking the cake.
Compile or Configure?
We're talking semantics here! Linux uses a programme, called a compiler, to configure a package at what Nginx calls compile-time.
Compiling Nginx Web Server
Here's the squeeze .. when preparing your Nginx package you must bear in mind not only the functionality you want for your sites, but for any sites that are to be hosted on that server. That said, no need to fret, the default package will suit most needs.
.. What's more, once you have the hang of it, re-compiling with extra requirements is a snap and, with version upgrades appearing every few months or so, most likely you'll reconsider your modules at the same time.
Official or 3rd Party Nginx Modules
Modules come in two main flavors, official and third party. Official ones may be better supported but don't discount the 3rd party ones which are generally of a high standard.
For a complete list of Nginx modules goto the wiki page. You will see there are:-
How to Use Nginx Modules
Once you've compiled Nginx with its default or your required modules, you configure those in nginx.conf and/or in your website configuration (virtual host) files.
I'll detail this for some popular modules in further tutorials, as discussed below.
Examining An Existing Nginx Compilation
Before exampling some compilation scenarios, for those of you who have already installed Nginx, you'll find it useful to know what modules and parameters you bundled with previously. At the command line:-
You'll see something like this:-
Here's an example of what we have:-
- nginx version the installed Nginx version
- built by gcc the compiler programme used to build Nginx
- configure arguments the variables used when compiling Nginx. If you specified none, there will be none. Of those I'm exampling here:-
- –sbin-path=/usr/local/sbin/nginx you specified this path for the Nginx installation directory
- –with-http_ssl_module you specified to bundle Nginx with just this module. You may have several other, similar looking, modules combined too.
To replicate that setup you'd use the options shown after the text configure arguments:, ie:-
So, to tell Ubuntu to compile the same package again (for instance, if you want to upgrade from an old Nginx version with the same modular options):-
Nginx Compile-Time Examples
Compiling Nginx, there are various approaches we may take. As explained above, we should have already downloaded and unzipped Nginx and gone into the (newly unzipped) source files directory, so something like:-
Core Nginx Compilation
In that source folder, to default-compile simply type:-
Specifying Nginx Parameters
Parameters are most likely used to specify file locations. For example:-
.. sets a path to install Nginx' binary file, or:-
.. does the above and sets another for the web server's error log file.
Nginx Plus Additional Official Modules
.. this configures the package with one argument specifying an additional module, in this case the Secure Socket Layer for e-commerce as mentioned earlier.
Nginx Minus Default-Compiled Modules
.. this argument disables a default module, in this case Memcached caching.
Simple enough to recognise .. instead of the module prefix –without- we have the syntax –without-.
Nginx with Extra Official Modules but Disabling Default Mods
Combining Parameters and Modules
.. is now pretty self-explanatory: we've set a prefered path for the Nginx binary, added a couple of official modules and disabled another.
Beginning to fall asleep? I'll wake you up 😛
Nginx with Added Third Party Modules
Whereas Nginx own modules are included in the zipped up folder and we just choose the ones we want, with 3rd party mods we have to download them separately. Moreover, in some cases, 3rd party mods require dependency packages of their own – so be sure to read the module's documentation. Let me try to spell it out but it's really no big deal.
Change directory to where we download source files:-
.. and (using the PAM Authentication module as an example):-
This 3rd party example does need a dependency package called libpam-dev (so the module's documentation tells me). Fine. We'll install that in the regular way:-
Now we head back to the unzipped Nginx directory and carry on as before:-
.. so here I am including the 3rd party mod which we downloaded and unzipped into its separate, specified directory. To clarify this point which, unchecked, can lead to compilation errors ..
The noticible difference between official and 3rd party modules syntax: adding official mods we prefix the mod's name with –with- and, for the 3rd parties we prefix them with –add-module=/path/to/unzipped/module/directory. Be careful with that path to avoid errors.
(Official modules don't need the path specified because they haven't had to be downloaded and unzipped separately, instead having been downloaded with the original Nginx zip file.)
Compiler Warnings as Errors
Sometimes the compiler treats warnings as errors. If that happens to you, have another go, like this:-
An Nginx Compilation Example
Figured I'd throw this one in the mix, a recent Nginx compilation I've used.
Other than setting the install path, there are some web development tools, a couple of authentication mods and a zipper. I'm losing Memcached here too.
First, here's the requirement:-
Install to:-
- /usr/local/sbin/nginx
Nginx Modules:-
- http_ssl_module #shopping
- http_secure_link_module #authentication
- http_stub_status_module #server statistics
Nginx Modules to Lose:-
- http_memcached_module #Memcached caching
3rd Party Modules:-
- ngx_http_strip_filter_module.c #strip whitespace/speed pageload
- ngx_http_accesskey_module.c #authentication
- mod_zip-1.x #zip stuff
- ngx_http_circle_gif_module.c #real fast round corners
- ngx_http_log_request_speed_filter.c #check page requests
So, having downloaded the 3rd party modules, unzipped them and plotted the single specific path location for my binary file, here's the appropriate Nginx configuration command:-
Module Configuration
Once we've compiled Nginx we have to configure our modules individually, setting their parameters. Generally, this is done in one of three places:-
- nginx.conf
- default virtual host
- somesite.com virtual host
We've already configured many of the default modules, in the above files, throughout vpsBible's Nginx installation guides. But – you guessed it – with this particular tutorial there's suddenly a whole lot of new ground to cover.
Damn!
For an exisitng example of how to configure a module, take a look at the http_auth_basic_module tutorial Password-Protected Web Pages, paying particular attention to the section Adapt the Virtual Host File.
I'll look at configuration options for popular modules in further guides. Let me know any specific requests. There is of course always developer documentation for each and every mod, as linked from the Nginx module wiki page, so that's a start and, hopefully now, a little less daunting.
Go play!