[edit] Nginx documentation

The nginx directives always end with a ; or is enclosed between { and }.

Due the fact that nginx isn't only a http(s)-server and http(s)-reverse-proxy, the configuration file is divided into the following sections:

1. [#main The main section]
2. [#events The events { } section]
3. [#http The http { } section]
4. [#imap The imap { } section]

Template:Anchor

[edit] The main section

daemon  off;          # disable daemon mode
master_process  off;  # disable worker_processes: master process handles
: # connections by itself

Do not use the "daemon" and "master_process" directives in a production mode, these options are mainly used for development only.

user  USER [GROUP] ;

If the master process is run as root, then nginx will setuid()/setgid() to USER/GROUP. If GROUP is not specified, then nginx uses the same name as USER. By default it's nobody user and nobody or nogroup group or the --user=USER and --group=GROUP from the ./configure script.

timer_resolution  100ms;

The directive allows to decrease number gettimeofday() syscalls. By default gettimeofday() is called after each return from kevent(), epoll, /dev/poll, select(), poll().

But if you need an exact time in logs when logging $upstream_response_time, or $msec variables, then you should use timer_resolution.

pid /var/log/nginx.pid;

The pid-file. It can be used for the kill-command to send signals to nginx, eg: to reload the config: kill -HUP <code>cat /var/log/nginx.pid

lock_file  /var/log/lock_file;

nginx uses accept mutex to serialize accept() syscalls. If nginx is built by gcc, Intel C++, or SunPro C++ compilers on i386, amd64, sparc64, and ppc64, then nginx uses the atomic instructions to implement the mutex. In other cases the lock file would be used.

worker_processes NUM;

nginx has the ability to use more then on worker process for several reasons:

1. to use SMP,
2. to decrease latency when workers blockend on disk I/O,
3. to limit number of connections per process when select()/poll() is used.

The worker_processes and worker_connections from the event sections allows you to calculate maxclients value:

max_clients = worker_processes * worker_connections

debug_points [stop|abort] ;

There are some assertion points inside nginx that allow to stop nginx to attach the debugger, or to abort and to create the core file.

worker_priority [-] NUM;

With this option you can give to all worker processes the priority (nice) you need/wish, it calls setpriority().

worker_cpu_affinity CPUMASK [CPUMASK]  ...;

Linux only.

With this option you can bind the worker process to a CPU, it calls sched_setaffinity(). For example,

worker_proceses     4;
worker_cpu_affinity 0001 0010 0100 1000;

Bind each worker process to one CPU only.

worker_proceses     2;
worker_cpu_affinity 0101 1010;

Bind the first worker to CPU0/CPU2, bind the second worker to CPU1/CPU3. This is suitable for HTT.

worker_rlimit_nofile FDLIMITS;

Specifies the value for maximum file descriptors that can be opened by this process.

worker_rlimit_core SIZE;

Maximum size of core file per worker;

worker_rlimit_sigpending ;

(Since Linux 2.6.8) Specifies the limit on the number of signals that may be queued for the real user ID of the calling process.

working_directory DIR;

This is the working directory for the workers. It's used for core files only. nginx uses absolute paths only, all relative paths in configuration files are relative to --prefix==PATH.

error_log LOGFILE [ debug | info | notice | warn | error | crit ] ;
error_log LOGFILE [ debug_core | debug_alloc | debug_mutex | debug_event
]: | debug_http | debug_imap ;

The debug options are only useful if you have added the --with-debug flag to the ./configure script.

include FILE;

You can include any configuration files for what ever purpose you want ;-)

Template:Anchor

[edit] The events { } section

worker_connections NUM;

The worker_connections and worker_proceses from the main section allows you to calculate maxclients value:

max_clients = worker_processes * worker_connections

---

use [ kqueue | rtsig | epoll | /dev/poll | select | poll ] ;

If you have more than one event-model specified at the ./configure script, then you can tell nginx which one do you want to use. By default nginx looks for the most suitable method for your OS at ./configure time.

rtsig_signo

nginx uses two signals when the rtsig method is used. The directive specified the first signal number. The second is plus 1. By default rtsig_signo is SIGRTMIN+10 (40).

rtsig_overflow_events
rtsig_overflow_test
rtsig_overflow_threshold

The directives specifies how to handle rtsig queue overflows. When overflow occurred nginx flushes rtsig queue, then it handles events switching between poll() and rtsig. poll() handles consecutively all unhandled events, while rtsig periodicaly drains queue to prevent a new overflow. When overflow is handled completely, nginx switches to rtsig method again.

The rtsig_overflow_events specifies the number of events to be passed via poll(). The default is 16.

The rtsig_overflow_test specifies after which number of events handled by poll() nginx will drains rtsig queue. The default is 32.

The rtsig_overflow_threshold works in Linux 2.4.x only. Before to drain rtsig queue nginx looks in a kernel how the queue is filled up

The default is 1/10. "rtsig_overflow_threshold 3" means 1/3.

devpoll_changes
devpoll_events
kqueue_changes
kqueue_events
epoll_events

The directives specify how many events may be passed to/from kernel, using appropriate method. The default devpoll values are 32, the rest are 512.

multi_accept [ on | off ] ;

multi_accept tries to accept() as many connections as possible after nginx gets notification about a new connection.

accept_mutex [ on | off ] ;

nginx uses accept mutex to serialize accept() syscalls.

accept_mutex_delay Nms;

If a worker process does not have accept mutex it will try to aquire it at least after this delay. By default delay is 500ms.

debug_connection IP;
Since 0.3.54 this option support CIDR address format

This option gives you the ability to write debug log only for the clients of this IP/NET. Several different directives are possible.

ssl_engine OPENSSLENGINE;

Here you can set your preferred openssl engine if any available. You can figure out which one do you have with the commandline tool: openssl engine -t

For example:

$ openssl engine -t
(cryptodev) BSD cryptodev engine
: [ available ] 
(dynamic) Dynamic engine loading support
: [ unavailable ] 

Template:Anchor Template:Anchor