Nginx

Name note

Meant to be pronounced as “Engine X”. (The software's name is often pronounced quite different, such as “Engeenks”, by those unfamiliar with the preferred pronunciation.) Calomel.org's Relayd guide seems to recommend “Nginx, pronounced "Engine X"”, and compares this software product to Lighttpd and thttpd and Apache.

Other basic/overview info

The site's domain may be at http://nginx.org which is fairly sparse. One of the hyperlinks on the right side of that page points to Nginx's Wiki.

Calomel.org's guide to Nginx

Notes for OpenBSD

Note: Most of this information was written prior to the OpenBSD 5.2, which started to include Nginx as part of OpenBSD. So, some of this information may currently be outdated. (The information is remaining here for now, pending review.)

Users of OpenBSD may notice a package called “Passenger”. Reviewing the commit logs from 2010-Nov-08 and especially 2009-Aug-20, this appears to be related to Phusion Passenger which is related to Ruby on Rails. (There is also an OpenBSD package named ruby-passenger.)

As that did not seem too incredibly necessary for a more basic setup, this guide was made for the basic, plain-vanilla package (simply named nginx rather than nginx-passenger, e.g. nginx-1.0.4.tgz instead of nginx-1.0.4-passenger.tgz).

Commit of nginx code indicates that this software is getting merged into base. The commit message notes that this software “is not yet linked to the build but we would like to work on it in tree to provide an apache replacement for base”. What this means is that the software is not completely part of what gets really included in the process of creating a standard release version of OpenBSD, but the code is made available for developers in a way that developers can more easily use the code. That is simply a common first step. Then, later with OpenBSD 5.2, nginx became included with OpenBSD. When OpenBSD version 5.2 was the latest version, OpenBSD FAQ: What is new in the latest version of OpenBSD stated, “Added ngingx(8)”. (The “(8)” refers to the manual page section for a command.) Also, “, Nginx is an HTTP server, reverse proxy server and mail proxy server. Ultimately, it is hoped nginx will replace the Apache 1.3-derived httpd in base OpenBSD.” ([sic]... after the text for the hyperlink in the title, the HTML was “</a></b><br>,”, and then the following text was on the next line.)

To use, it may be as simple as running nginx and then having a web client visit the page, requesting the IPv4 address or DNS name. (Err, maybe this also enables a mail proxy by default... Some further research on that may be warranted.)

The default location for web content may be /var/nginx/html/ as specified by the configuration file, which may be nginx.conf in /etc/nginx/ or /etc/ (depending, perhaps, on how it was installed).

Nginx's guide to installing on OpenBSD, which is believed to have pre-dated the software becoming included with OpenBSD (with OpenBSD version 5.2), showed a guide for downloading the source code and making the program. Actually, the first recommended step in that process was to add the PCRE library by using “sudo pkg_add -v pcre”. The guide also hd some information about Rails support.

Configuration file

To run the software, the first recommendation is to back up the nginx.conf file. (One way may be to use the cpytobakscript provided by this site.

Check out the configuration file, which may be a file named nginx.conf which may be located in the /etc/nginx/ directory.

A basic configuration file
gzip

Right underneath:

    #gzip  on;

go ahead and enable support.

    gzip  on;
    gzip_static  on;
Supporting (multiple) HTTP site(s)

Just below the configuration about gzip support (in the original default configuration file), go ahead and make a new section. (This new section will be residing entirely within a pre-existing “http {” configuration block.)

(The following content is adapted from Nginx Wiki: Server Block Example and ServerFault.com question about nginx named-based virtual hosts on IPv6.)

index index.html index.htm;

server {
# Default info used when client does not properly specify a
# recognized name of a web server

# The following two lines cause nginx to listen for HTTPS
# traffic, if they are uncommented.

# listen [::]:443 ssl default_server ipv6only=on;
# listen 443 ssl default_server;

# The following are used even for standard HTTP traffic.
listen [::]:80 default_server ipv6only=on;
listen 80 default_server;

server_name _; # never matches real name of a web site's server

access_log /var/nginx/logs/noname.log combined;
# Some common builds of nginx might not support the following line.
# error_log /var/nginx/logs/noname-debug.log debug;

server_name_in_redirect off;

# For HTTPS support, make the following files exist and uncomment.

# ssl_certificate /etc/ssl/noname.crt;
# ssl_certificate_key /etc/ssl/private/noname.key;

root /var/www/vhosts/noname;
} #end server section

server {
# example.org
# listen [::]:443 ssl;
listen [::]:80;
# listen 443;
listen 80;

server_name example.org *.example.org;

access_log /var/nginx/logs/exampleo.log combined;
# Some common builds of nginx might not support the following line.
# error_log /var/nginx/logs/exampleo-debug.log debug;

# For HTTPS support, make the following files exist and uncomment.

# ssl_certificate /etc/ssl/exampleo.crt;
# ssl_certificate_key /etc/ssl/private/exampleo.key;

root /var/www/vhosts/exampleo;
} #end server section

server {
# example.net
# listen [::]:443 ssl;
listen [::]:80;
# listen 443;
listen 80;

server_name example.org *.example.org;

access_log /var/nginx/logs/examplen.log combined;
# Some common builds of nginx might not support the following line.
# error_log /var/nginx/logs/examplen-debug.log debug;

# For HTTPS support, make the following files exist and uncomment.
# ssl_certificate /etc/ssl/examplen.crt;
# ssl_certificate_key /etc/ssl/private/examplen.key;

root /var/www/vhosts/examplen;
} #end server section

Of course, customize that new section as needed. Also, if the file comes with a pre-existing example “server {” section, comment out that now-unneeded section. (This guide recommends just making a new section as described, and commenting out the example, instead of customizing/improving the pre-existing example. The simple reason is that the pre-provided example does not have the lines needed for HTTPS and/or SSL. The description provided in this guide creates a bit of a more flexible setup for supporting multiple sites.)

Making required directories

e.g.:

sudo mkdir /var/nginx/logs

Also, make any other directories that the configuration file refers to, such as any directories for the web content.

Starting the web server

First, go ahead and test the configuration file:

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf text is successful
$

Start the server.

sudo nginx
HTTPS in Nginx

Also available: some more generalized information about HTTPS.

Certs

First, at least one certificate file and server key will need to be generated. Each website will need to be referenced by a certificate. (However, it is not necessarily required that each site have a unique certificate. Wildcard certificates and UCC/SAN certificates may allow multiple sites to use a smaller number of certificates.) See communicating with certificates to get the details about creating a certificate.

Get the certs in the needed format. (Concatenate?)

Update the config file

In the Nginx configuration file, for each site, add the following three lines:

listen 443 ssl;

ssl_certificate filename.crt;
ssl_certificate_key filename.key;

e.g., the end result section may look something like:

index index.html index.htm;

server {
listen 443 ssl;

server_name example.org *.example.org;
ssl_certificate /etc/ssl/exampleo.crt;
ssl_certificate_key /etc/ssl/private/exampleo.key;
access_log logs/exampleo.log combined;

root /var/www/exampleo/htdocs;
} #end server section

server {

listen 443 ssl;
server_name example.net *.example.net;

ssl_certificate /etc/ssl/exampleo.crt;
ssl_certificate_key /etc/ssl/private/exampleo.key;

access_log logs/examplen.log combined;

root /var/www/examplen/htdocs;
} #end server section

server {
listen [::]:443 default_server ipv6only=on;
listen [::]:80 default_server ipv6only=on;
listen 443 ssl;
listen 80 default_server;

server_name _; # never matches real name of a web site's server

ssl_certificate /etc/ssl/noname.crt;
ssl_certificate_key /etc/ssl/private/noname.key;

access_log logs/noname.log combined;

server_name_in_redirect off;

root /var/www/noname/htdocs;
} #end server section

Implement

Tell the server to reload its configuration.

sudo nginx -s reload

Test.

There are some online documents about optimizing the HTTPS server. e.g. Nginx documetnation: Configuring HTTPS servers: section on optimization, and Calomel.org's guide to Nginx.