Nginx - Core Module Directives

The following is the list of directives made available by the Core module. Most of these directives must be placed at the root of the configuration file and can only be used once. However, some of them are valid in multiple contexts. If that is the case, the following is the list of valid contexts under the directive name:

daemon

Enables or disables daemon mode. If you disable it, the program will not be started in the background; it will stay in the foreground

when launched from the shell. This may come in handy for debugging, in situations where you need to know what causes Nginx to crash, and when.

Accepted values: on or off

Example: daemon on;

Default value: on

debug_points

Activates debug points in Nginx. Use stop to interrupt the application when a debug point comes about in order to attach a

debugger. Use abort to abort the debug point and create a core dump file.

To disable this option, simply do not use the directive.

Accepted values: stop or abort

Example: debug_points stop;

Default value: None

env

Lets you (re)define environment variables.

Syntax: env MY_VARIABLE;

Syntax: env MY_VARIABLE=my_value;

error_log

Where level is one of the following values: debug, info, notice, warn, error, and crit (from most to least detailed: debug provides frequent log entries, crit only reports critical errors).

Enables error logging at different levels: Application, HTTP server, virtual host, and virtual host directory.

By redirecting the log output to /dev/null, you can disable error logging. Use the following directive at the root of the configuration file: error_log /dev/null crit;

Context: main, http, server, and location

Syntax: File path

Example: error_log /file/path level;

Default value: logs/error.log error

lock_file

Use a lock file for mutual exclusion. This is disabled by default, unless you enabled it at compile time. On most operating systems the locks are implemented using atomic operations, so this directive is ignored anyway.

Syntax: File path

Example: lock_file logs/nginx.lock;

Default value: Defined at compile time

log_not_found

Enables or disables logging of 404 not found HTTP errors. If your logs get filled with 404 errors due to missing favicon.ico or robots.txt files, you might want to turn this off.

Context: main, http, server, and location

Accepted values: on or off

Syntax: log_not_found on;

Default value: on

master_process

If enabled, Nginx will start multiple processes: a main process (the master process) and worker processes. If disabled, Nginx works with a unique process. This directive should be used for testing purposes only as it disables the master process—clients thus cannot connect to your server.

Accepted values: on or off

Example: master_process on;

Default value: on

pcre_jit

Enables or disables Just-In-Time compilation for regular expressions (PCRE from version 8.20 and above) which may speed up their processing significantly. For this to work, the PCRE libraries on your system must be specifically built with the --enable-jit configuration argument. When configuring your Nginx build, you must also add the --with-pcre-jit argument.

Accepted values: on or off

Example: pcre_jit on;

pid

Path of the pid file for the Nginx daemon. The default value can be configured at compile time. Make sure to enable this directive and set its value properly, since the pid file may be used by the Nginx init script depending on your operating system.

Syntax: File path

Example: pid logs/nginx.pid;

Default value: Defined at compile time.

ssl_engine

Where enginename is the name of an available hardware SSL accelerator on your system. To check for available hardware SSL accelerators, run this command from the shell: openssl engine –t

Syntax: ssl_engine enginename;

Default value: None

thread_stack_size

Defines the size of the thread stack; please refer to the worker_threads directive below.

Syntax: Numeric (size)

Example: thread_stack_size 1m;

Default value: None

timer_resolution

Controls the interval between system calls to gettimeofday() to synchronize the internal clock. If this value is not specified, the clock is refreshed after each kernel event notification.

Syntax: Numeric (time)

Example: timer_resolution 100ms;

Default value: None

user

Lets you define the user account, and optionally the user group used for starting the Nginx worker processes. For security reasons, you should make sure to specify a user and group with limited privileges. For example, create a new user and group dedicated to Nginx, and remember to apply proper permissions on the files that will be served.

Syntax: user username groupname;

Syntax: user username;

Default value: Defined at compile time. If still undefined, the user and group of the Nginx master process are used.

worker_threads

Defines the amount of threads per worker process. Warning! Threads are disabled by default. The author stated that "the code is currently broken."

Syntax: Syntax: Numeric

Example: worker_threads 8;

Default value: None

worker_cpu_affinity

This directive works in conjunction with worker_processes. It lets you affect worker processes to CPU cores.

There are as many series of digit blocks as worker processes; there are as many digits in a block as your CPU has cores.

If you configure Nginx to use three worker processes, there are three blocks of digits. For a dual-core CPU, each block has two

digits: worker_cpu_affinity 01 01 10;

The first block (01) indicates that the first worker process should be affected to the second core.

The second block (01) indicates that the second worker process should be affected to the second core.

The third block (10) indicates that the third worker process should be affected to the first core.

Note that affinity is only recommended for multi-core CPUs, not for processors with hyper-treading or similar technologies.

Example: worker_cpu_affinity 1000 0100 0010 0001;

Example: worker_cpu_affinity 10 10 01 01;

Example: worker_cpu_affinity;

Default value: None

worker_priority

Defines the priority of the worker processes, from -20 (highest) to 19 (lowest). The default value is 0. Note that kernel processes run at priority level -5, so it's not recommended that you set the priority to -5 or less.

Syntax: Numeric

Example: worker_priority 0;

Default value: 0

worker_processes

Defines the amount of worker processes. Nginx offers to separate the treatment of requests into multiple processes. The default value is 1, but it's recommended to increase this value if your CPU has more than one core. Besides, if a process gets blocked due to slow I/O operations, incoming requests can be delegated to the other worker processes.

Alternatively, you may use the auto value which will let Nginx select an appropriate value for this directive. By default, it is the amount of CPU cores detected on the system.

Syntax: Numeric, or auto

Example: worker_processes 4;

Default value: 1

worker_rlimit_core

Defines the size of core files per worker process.

Syntax: Numeric (size)

Example: worker_rlimit_core 100m;

Default value: None

worker_rlimit_nofile

Defines the amount of files a worker process may use simultaneously.

Syntax: Numeric

Example: worker_rlimit_nofile 10000;

Default value: None

worker_rlimit_sigpending

Defines the amount of signals that can be queued per user (user ID of the calling process). If the queue is full, signals are ignored past this limit.

Syntax: Numeric

Example: worker_rlimit_sigpending 10000;

Default value: None

working_directory

Working directory used for worker processes, it is only used to define the location of core files. The worker process user account (user directive) must have write permissions on this folder in order to be able to write core files.

Syntax: Directory path

Example: working_directory /usr/local/nginx/;

Default value: The prefix switch defined at compile time.

worker_aio_requests

If you are using aio with the epoll connection processing method, this directive sets the maximum number of outstanding synchronous I/O operations for a single worker process.

Syntax: Numeric

Example: worker_aio_requests 10000;