NGINX installation

2014-12-28T07:48:00Z.

NGINX can be used as HTTP server and load balancer.

This article assumes you to install and configure NGINX 1.5 or above on Debian GNU/Linux.

For SSL support, this article assumes OpenSSL has been installed and signing the certificate by Comodo SSL (PositiveSSL).

Installing NGINX

The NGINX package is available on Debian official repositories. If the NGINX package is too old, it is possible to install from NGINX official repositories.

To obtain pre-built packages from NGINX, first add the key used to sign the NGINX packages:


wget -O nginx_signing.key http://nginx.org/keys/nginx_signing.key

apt-key add nginx_signing.key

Add the following lines to /etc/apt/sources.list:


# NGINX (mainline).

deb http://nginx.org/packages/mainline/debian/ wheezy nginx

deb-src http://nginx.org/packages/mainline/debian/ wheezy nginx

Note: Replace wheezy with appropriate code name of installed version of Debian GNU/Linux.

Update package cache:


aptitude update

To install pre-built package from NGINX, execute:


aptitude install nginx

To install from Debian official repositories, execute:


aptitude install nginx-light

Configure NGINX

Any line begins with "#" (pound) character is a comment. Each configuration is called directive and must end with ";" (semi-colon) character. Some configurations may enclose child configurations with a pair of braces ("{" and "}"), those kind of configurations are called context.


worker_processes 1;

This directive controls how many worker processes will handle the requests. The value should equal to the number of CPU cores.


server_tokens off;

This directive disables the version number of NGINX being propagated to client.


gzip on;

gzip_min_length 1024;

gzip_proxied any;

gzip_types text/css application/javascript application/json text/xml application/xml text/plain;

These directives enable GZIP compression of response body, even for proxied response. Only response body of declared MIME types will be compressed. MIME type text/html is always being compressed.


client_max_body_size 0;

This directive disables checking of client request body size. The default value is 1 megabyte.


access_log off;

This directive disables access log.


add_header X-Frame-Options SAMEORIGIN;

This directive tells web browser that files being served are embeddable only in documents from same origin.


proxy_set_header X-Real-IP $remote_addr;

This directive makes the client IP address available to the back-end servers via the header X-Real-IP.


upstream http-01 {
  server 127.0.0.1:8080;
  keepalive 16;
}

This context defines a server group namely "http-01", containing one server (which can be reached at 127.0.0.1 and it is listening on port 8080).


server {
  # Content omitted.
}

This context defines a server.


server_name example.com

This directive defines names of virtual server and the first one becomes the primary virtual server.


listen 80;

This directive defines the server should listen on port 80 for incoming requests over HTTP.


listen 443 ssl;

This directive defines the server should listen on port 443 for incoming requests over HTTPS.


location /static {
  # Content omitted.
}

This context defines the configurations dependent on the request URI.


root /var/www;

index index.html;

These directives define the root document directory of the enclosing request URI as "/var/www". The index file of the directory is "index.html". Note that the request URI will be added to the root document directory when resolving path to files.


proxy_pass http://http-experiment-01;

proxy_http_version 1.1;

proxy_pass_header Server;

These directives redirect the requests to the defined server group "http-experiment-01" over HTTP. The redirection of request will be sent with HTTP 1.1. The response header "Server" sent from server group will be kept and sent back to the client.


ssl_certificate /etc/nginx/certificates/example-ssl-bundle.crt;

ssl_certificate_key /etc/nginx/certificates/example.com.key;

ssl_session_cache shared:SSL:10m;

ssl_session_timeout 10m;

These directives define the path of SSL certificates bundle file, path of SSL certificate private key, SSL cache configuration and SSL session timeout.

After updating the NGINX configurations, execute the following to reload the new configurations:


nginx -s reload

Configure NGINX for HTTPS connections

First generate a private key and CSR (Certificate Signing Request):


openssl req -nodes -newkey rsa:2048 -keyout example.key -out example.csr

When generating the private key and public CSR, make sure to provide the domain name as the Common Name. Obtain the content of CSR by executing:


cat example.csr

Now you can submit the CSR to certificate issuer for signing.

Note: Replace the file names of private key and CSR with appropriate name when necessary.

When the signed certificate is received, combine the signed certificate, intermediate certificate and root certificate into one file:


cat example_com.crt COMODORSADomainValidationSecureServerCA.crt \
COMODORSAAddTrustCA.crt AddTrustExternalCARoot.crt \
> example-ssl-bundle.crt

Note that the ordering of certificates is important, always begin with primary certificate (i.e. the signed certificate for the domain name), then intermediate certificate(s), then root certificate.

Update the NGINX configuration file. In server context, add the following lines:


listen 443 ssl;

ssl_certificate /etc/nginx/certificates/example-ssl-bundle.crt;

ssl_certificate_key /etc/nginx/certificates/example.key;

ssl_ciphers "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES256-SHA:AES128-SHA:DES-CBC3-SHA:HIGH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4";

ssl_prefer_server_ciphers on;

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

ssl_session_cache shared:SSL:10m;

ssl_session_timeout 10m;

SSL version 3 is enabled by default, while the above configurations will disable it. SSL version 3 is an out-dated protocol and security issues have been found. After disabling SSL version 3, some old browsers and operating systems may have problem connecting to the server.

Note: Replace the path to private key and combined certificates when necessary. All keys should be readable by root only.

Restart NGINX:


/etc/init.d/nginx restart

Load balancing with NGINX

To pass requests to a group of back-end servers, first define a server group. In http context, add the following lines:


upstream group01 {
  server 127.0.0.1:8181;
  keepalive 16;
}

In server context (in http context), add or update the location context as following:


location / {
  proxy_pass https://group01;
  proxy_pass_header Server;
  proxy_http_version 1.1;
}

Then restart NGINX:


/etc/init.d/nginx restart

Home / Articles