NGINX Web Server

../_images/proxy_nginx.png

WARNING - Topics covered in this page require you to have administrator/root access to your machine(s) to install/deploy software.

Overview

NGINX is a free, open-source, high-performance HTTP server and reverse proxy. NGINX is known for its high performance, stability, rich feature set, simple configuration, and low resource consumption.

All the information in this page can be found at the NGINX Official Wiki.

This is just a simple digest of what we have found the most relevant information. It is recommended to consult the full NGINX documentation before continuing configuration.

Installation

NGINX has both Windows and Linux binaries. Currently Windows is NOT fully featured and is NOT recommended for production by NGINX.

Debian Distro

In the terminal run:

>>> sudo apt-get install nginx

Red Hat Distro

In the terminal run:

>>> sudo yum install nginx

Configuration

Note, this section gives some background information about NGINX. To learn more go to the NGINX Official Wiki.

NGINX modules are created in configuration files. By default, the configuration file is called nginx.conf.

The config files are usually located in:

/usr/local/nginx/conf
/etc/nginx/
/usr/local/etc/nginx

In the main nginx.conf file make sure you have the following in the http declarative:

include deadline.conf

Create a file next to your nginx.conf called deadline.conf.

Config File Structure

NGINX conf files consist of modules called declaratives. Declaratives are divided into simple declaratives and block declaratives.

A simple declarative has a name and a parameter and is separated by a semi-colon character, eg: root /data/www;

A block declarative has a name and surrounding braces ({}) which contain a set of simple declaratives. eg: http { server {} }

Common Commands

To start NGINX:

>>> nginx -s start

To stop NGINX:

>>> nginx -s stop
>>> nginx -s quit

To reload a config file:

>>> nginx -s reload

Setup your NGINX

These are our recommended NGINX configurations.

Logging

To enable NGINX logging, add the following to the http declarative in your nginx.conf file:

http {
    #.......
    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;
    #.......
}

HTTP Load Balancing

Add the following to your deadline.conf:

map $request_uri $upstreamserver {
default         deadline;
~transactionID.*    deadline2;
}

upstream deadline2 {
    hash $binary_remote_addr$request_uri$args;

    server <SERVER IP>:<PORT>;
    #...
    #...
}
upstream deadline {
    server <SERVER IP>:<PORT>;
    #...
    #...
}

server {
    listen 80;

    location / {
        proxy_pass http://$upstreamserver;
    }
}

In the Deadline upstream declarative, add your list of Deadline Proxy Servers in the format: server <IP Address>:<PORT>;

You can add as many as you need to this list.

HTTPS Load Balancing

To generate server and client certificates yourself, please see the SSL Certificate Generation documentation.

Add the following to your deadline.conf:

map $request_uri $upstreamserver {
default         deadline;
~transactionID.*    deadline2;
}

upstream deadline2 {
    hash $binary_remote_addr$request_uri$args;

    server <SERVER IP>:<PORT>;
    #...
    #...
}

upstream deadline {
    server <SERVER IP>:<PORT>;
    #...
    #...
}

server {
    listen 80;
    return 301 https://$host$request_uri;
}

server {
        listen 443 ssl;
        server_name <HOSTNAME OR IP>;

        ssl_certificate           <PATH TO THE SERVER .CRT FILE>;
        ssl_certificate_key       <PATH TO THE SERVER .KEY FILE>;

        ssl_client_certificate    <PATH TO THE CLIENT .CRT FILE>;
        ssl_verify_client         on;

        ssl on;
        ssl_session_cache builtin:1000 shared:SSL:10m;
        ssl_protocols  TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
        ssl_prefer_server_ciphers on;

        location / {
            proxy_set_header        Host $host;
            proxy_set_header        X-Real-IP $remote_addr;
            proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header        X-Forwarded-Proto $scheme;

            # Fix the "It appears that your reverse proxy set up is broken" error.
            proxy_pass          http://$upstreamserver;
            proxy_read_timeout  90;

            proxy_redirect      http://deadline https://<HOST NAME>;
        }
}

In the Deadline upstream declarative, add your list of Deadline Proxy Servers in the format: server <IP Address>:<PORT>;

Replace <HOST NAME> with the name of the machine your NGINX is running on as well as applicable paths for <PATH TO THE SERVER .CRT FILE> and <PATH TO THE SERVER .KEY FILE>, and <PATH TO THE CLIENT .CRT FILE>.

Redundancy and Failover

Let’s say you are using NGINX and load balancing between 3 servers, and one of them goes down unexpectedly. What behaviour will the Client see?

The answer is nothing. NGINX handles redundancy out of the box. When NGINX considers a server to be unavailable, it will temporarily stop sending requests to it until it is active again.

You can tune this behaviour by changing the max_fails or fail_timeout flag. By default max_fails is set to 1 and fail_timeout is set to 10 seconds.

In general it is not necessary to play with these variables. But if you need to, here is an example of how you would set these parameters:

upstream deadline {
    server 192.168.1.1;
    server 192.168.1.2 max_fails=3 fail_timeout=30s;
    server 192.168.1.3 max_fails=2;
}