user www www;
worker_processes 2;

error_log /var/log/nginx-error.log info;

events {
    use kqueue;
    worker_connections 2048;
}

...

accept_mutex on;

If enabled, accepts of new connections by multiple worker processes will be serialized. Otherwise, all worker processes will be notified about new connections, and if volume of new connections is low, some of the worker processes may just waste system resources.

The use of rtsig connection processing method requires accept_mutex to be enabled.

accept_mutex_delay 500ms;

If accept_mutex is enabled, specifies the maximum time during which a worker process will try to restart accepting new connections if another worker process is already doing this currently.

daemon on;

Determines whether nginx should become a daemon. Mainly used during development.

Enables debugging log for selected client connections. Other connections will use logging level set by the error_log directive. Debugged connections are specified by IPv4 or IPv6 (1.3.0, 1.2.1) address or network. A connection may also be specified using a hostname. For connections using UNIX-domain sockets (1.3.0, 1.2.1), debugging log is enabled by the “unix:” parameter.

events {
    debug_connection 127.0.0.1;
    debug_connection localhost;
    debug_connection 192.0.2.0/24;
    debug_connection ::1;
    debug_connection 2001:0db8::/32;
    debug_connection unix:;
    ...
}

For this directive to work, nginx needs to be built with --with-debug.

This directive is used for debugging.

When internal error is detected, e.g. the leak of sockets on restart of working processes, enabling debug_points leads to a core file creation (abort) or stopping a process (stop) for further analysis using a system debugger.

error_log logs/error.log error;

Configures logging.

The first parameter defines a file that will store the log. The special value stderr selects the standard error file.

The second parameter determines the level of logging. Log levels above are listed in the order of increasing severity. Setting a certain log level will cause all messages of the specified and more severe log levels to be logged. For example, the default level error will cause error, crit, alert, and emerg messages to be logged. If this parameter is omitted then error is used.

For debug logging to work, nginx needs to be built with --with-debug.

env TZ;

By default, nginx removes all environment variables inherited from its parent process except the TZ variable. This directive allows to preserve some of the inherited variables, change their values, or create new environment variables. These variables are then:

• inherited during a live upgrade of an executable file;
• used by the module ngx_http_perl_module;
• used by worker processes. Please bear in mind that controlling system libraries in this way is not always possible as it is not uncommon for libraries to check variables only during initialization, well before they can be set using this directive. An exception from this is an above mentioned live upgrade of an executable file.

The TZ variable is always inherited and made available to the module ngx_http_perl_module, unless configured explicitly.

Usage example:

env MALLOC_OPTIONS;
env PERL5LIB=/data/site/modules;
env OPENSSL_ALLOW_PROXY_CERTS=1;

The NGINX environment variable is used internally by nginx and should not be set directly by the user.

Provides a configuration file context in which the directives that affect connection processing are specified.

Includes another file, or files matching the specified mask, into configuration. Included files should consist of syntactically correct directives and blocks.

Usage example:

include mime.types;
include vhosts/*.conf;

lock_file logs/nginx.lock;

nginx uses the locking mechanism to implement accept_mutex and serialize accesses to shared memory. On most systems the locks are implemented using atomic operations, and this directive is ignored. On other systems the “lock file” mechanism is used. This directive specifies a prefix for the names of lock files.

master_process on;

Determines whether worker processes are started. This directive is intended for nginx developers.

multi_accept off;

If disabled, a worker process will accept one new connection at a time. Otherwise, a worker process will accept all new connections at a time.

The directive is ignored if kqueue connection processing method is used because it can report the number of new connections waiting to be accepted.

The use of rtsig connection processing method automatically enables multi_accept.

pcre_jit off;

Enables or disables the use of “just-in-time compilation” (PCRE JIT) for regular expressions known at configuration parse time.

PCRE JIT can speed up processing of regular expressions significantly.

The JIT is available in PCRE libraries starting from version 8.20 built with the --enable-jit configuration parameter. When building the PCRE library with nginx (--with-pcre=), the JIT support should be enabled with the --with-pcre-jit configuration parameter.

pid nginx.pid;

Defines a file that will store the process ID of the main process.

Defines the name of the hardware SSL accelerator.

Reduces timer resolution in worker processes, thus reducing the number of gettimeofday() system calls made. By default, gettimeofday() is called each time on receiving a kernel event. With reduced resolution, gettimeofday() is only called once per specified interval.

Example:

timer_resolution 100ms;

An internal implementation of interval depends on the method used:

• an EVFILT_TIMER filter if kqueue is used;
• timer_create() if eventport is used;
• setitimer() otherwise.

Specifies the connection processing method to use. There is normally no need to specify it explicitly because nginx will by default use the most efficient method.

user nobody nobody;

Defines user and group credentials used by worker processes. If group is omitted, a group whose name equals that of user is used.

worker_aio_requests 32;

When using aio with the epoll connection processing method, sets the maximum number of outstanding asynchronous I/O operations for a single worker process.

worker_connections 512;

Sets the maximum number of simultaneous connections that can be opened by a worker process.

It should be kept in mind that this number includes all connections (e.g. connections with proxied servers, among other things), not only connections with clients. Another consideration is that the actual number of simultaneous connections may not exceed the current limit on the maximum number of open files that can be changed by worker_rlimit_nofile.

Binds worker processes to the sets of CPUs. Each CPU set is represented by a bitmask of allowed to use CPUs. There should be a separate set defined for each of the worker processes. By default, worker processes are not bound to any specific CPUs.

For example,

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

binds each worker process to a separate CPU, while

worker_processes    2;
worker_cpu_affinity 0101 1010;

binds the first worker process to CPU0/CPU2, and the second worker process to CPU1/CPU3. The second example is suitable for hyper-threading.

The directive is only available on FreeBSD and Linux.

worker_priority 0;

Defines a scheduling priority for worker processes like is done by the nice command: a negative number means higher priority. Allowed range normally varies from -20 to 20.

Example:

worker_priority -10;

worker_processes 1;

Defines the number of worker processes.

The optimal value depends on many factors including (but not limited to) the number of CPU cores, the number of hard disk drives that store data, and load pattern. When in doubt, setting it to the number of available CPU cores would be a good start (the value “auto” will try to autodetect it).

The auto parameter is supported starting from versions 1.3.8 and 1.2.5.

Changes the limit on the largest size of a core file (RLIMIT_CORE) for worker processes. Used to increase the limit without restarting the main process.

Changes the limit on the maximum number of open files (RLIMIT_NOFILE) for worker processes. Used to increase the limit without restarting the main process.

On systems that support rtsig connection processing method, changes the limit on the number of signals that may be queued (RLIMIT_SIGPENDING) for worker processes. Used to increase the limit without restarting the main process.

Defines a current working directory for a worker process. It is primarily used when writing a core-file, in which case a worker process should have write permission for the specified directory.