nginx Reference

Kip Landergren

(Updated: )

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

Contents

Command Line Parameters
-c file config file
-g directives global configuration directives
-p prefix prefix for nginx server files
-s signal send signal to master process; stop, quit, reload, reopen
-t test config
-T test config and dump to stdout
-e file an alternative error log file

See complete list of switches for more.

Signals
stop shut down quickly
quit shut down gracefully
reload reload configuration, start the new worker process with a new configuration, gracefully shut down old worker processes.
reopen reopen log files

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 $nginx_master_pid

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

What is the difference between stable and mainline? What is the difference between nginx and nginxMainline? Should I choose mainline or stable?

mainline is released with odd version numbers and always gets the latest:

Choose mainline to have the latest and greatest features and fixes, at the expense of potential third party module conflict.

stable is cut at some regular interval, is released with even version numbers, and always receives:

Choose stable when you want to ensure your third party modules continue to work.

How do I bypass the nginx warning “could not open error log file” on startup?

If you see something like:

nginx: [alert] could not open error log file: open() "/var/log/nginx/error.log" failed (2: No such file or directory)

It is likely your nginx was built with the configure option:

--error-log-path=/var/log/nginx/error.log

To get around this pass a valid path to -e:

nginx -e /usr/local/var/log/nginx/error.log

Note: as of at least 1.27.2 it is not possible to accomplish this bypass through -g 'error_log /usr/local/var/log/nginx/error.log' for the global configuration directives.

Documentation and Resources