nginx Reference

Kip Landergren

(Updated: )

My cheat sheet for nginx covering helpful documentation links, installation, setup, tuning tips, terminology, and common commands.

Contents

Documentation and Resources

Installation

Pre-compiled packages are accessible from most package managers or directly from nginx here.

Compile from source when you need functionality from non-dynamic modules.

Initial Setup

The default directory setup looks like:

# the main config file. defines worker process configuration and the
# main http block applied to all HTTP/s requests. loads every file in
# conf.d by default
/etc/nginx/nginx.conf
# defines the default server
/etc/nginx/conf.d/default.conf
# parameters if used as fastcgi, scgi or uwsgi server
/etc/nginx/fastcgi_params
/etc/nginx/scgi_params
/etc/nginx/uwsgi_params
# charset mappings (from koi8 and from win)
/etc/nginx/koi-utf
/etc/nginx/koi-win
/etc/nginx/win-utf
# Maps file name extensions to MIME types of responses.
/etc/nginx/mime.types

Consider adding directories within conf.d/ scoped by their functionality:

/etc/nginx/conf.d/security/
/etc/nginx/conf.d/web-performance/

and, if the server is handling multiple hosts, make use of the sites/ convention:

/etc/nginx/sites/example–foo-com.conf
/etc/nginx/sites/example-bar-com.conf

A more opinionated take on this can be found at HTML5 Boilerplate’s Nginx Server Configs repository.

Tuning

gzip

nginx can serve precompressed gzip files directly without any on-the-fly compression:

http {
    gzip off;       # do not gzip on the fly
    gzip_static on; # do send correct gzip headers.
}

More info on gzip and gzip_static.

worker_rlimit_nofile

In a reverse-proxy setup nginx will use two file descriptors per request: one for the incoming connection and another for the outgoing. Under high load the operating system limit for the user nginx is running as may be hit, causing nginx to reject new connections. Enter worker_rlimit_nofile which will increase the maximum number of open files available for worker processes.

The value should be chosen with consideration and awareness of the capabilities of the operating system nginx runs on.

Nginx Terminology

block directive
a configuration instruction that has the same structure of a simple directive but ends with braces ({ and }) that may contain other instructions
context
a block directive that may contain other directives
simple directive
a configuration instruction consisting of a name and parameters separated by spaces, ending in a semicolon (;)

Commands

Run nginx with a non-default configuration file:

nginx -c /path/to/filename.conf

Test the configuration, print it to standard out, and exit:

nginx -T

Reload nginx configuration:

nginx -s reload

kill -HUP

View nginx processes:

ps axu | grep nginx

Frequently Asked Questions (FAQs)

Where is the location of the logs on MacOS?

/usr/local/var/log/nginx/access.log
/usr/local/var/log/nginx/error.log