FAQ

Page Discussion Edit History

CoreModule

Contents

Synopsis

These are the features that control basic Nginx functionality. This page was previously called NginxHttpMainModule.

Directives

daemon

Syntax: daemon on | off
Default: on
Context: main
Reference:daemon


daemon  off;

Do not use the daemon or master_process directives in a production mode; these options are used for development only. You can use daemon off safely in production mode with runit/daemontools, however you can't do a graceful upgrade. master_process off should never be used in production.

env

Syntax: env variable [= value ]
Default: TZ
Context: main
Reference:env


The instruction allows to limit a set of variables of environment, to change it values or to create new variables for following cases:

  • inheritance of variables during upgrading the binary with zero downtime ;
  • for use by the embedded Perl module
  • for use by working processes. However it is necessary to keep in mind, that management of behaviour of system libraries in a similar way probably not always as frequently libraries use variables only during initialization, that is still before they can be set by means of the given instruction. Exception to it is the above described updating an executed file with zero downtime.

If variable TZ is not described obviously it is always inherited and is always accessible to the embedded Perl module.

Example of use:

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

By default, nginx wipes all its environment variables except TZ variable.

  • "env NAME" allows to keep NAME variable value got from parent process, i.e., shell.
  • "env NAME=val" sets NAME variable value.

debug_points

Syntax: debug_points [stop | abort]

Default: none

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.

error_log

Syntax: error_log file | stderr [ debug | info | notice | warn | error | crit | alert | emerg ]
Default: logs/error.log error
Context: main
http
server
location
Reference:error_log


Specifies the file where server (and fastcgi) errors are logged.

Default values for the error level:

  1. in the main section - error
  2. in the HTTP section - crit
  3. in the server section - crit

Nginx supports separate error logging per virtual host. This is a unique feature, which lighttpd refuses to implement. For an example of separate error logging per server, see SeparateErrorLoggingPerVirtualHost and this mailing list thread on separating error logging per virtual host.

If you've built Nginx with --with-debug, you may also use:

error_log LOGFILE [debug_core | debug_alloc | debug_mutex | debug_event | debug_http | debug_imap];

Note that error_log off does not disable logging - the log will be written to a file named "off". To disable logging, you may use:

error_log /dev/null crit;

Also note that as of version 0.7.53, nginx will use a compiled-in default error log location until it has read the config file. If the user running nginx doesn't have write permission to this log location, nginx will raise an alert like this:

[alert]: could not open error log file: open() "/var/log/nginx/error.log" failed (13: Permission denied)

include

Syntax: include file | mask
Default:
Context:
Reference:include


You can include any configuration files for what ever purpose you want.

Since 0.4.4, the include directive also supports filename globbing:

include vhosts/*.conf;

Note that until version 0.6.7, paths are relative to what was specified to configure via the --prefix=<PATH> directive, which by default is /usr/local/nginx. If you didn't set this when you compiled Nginx, then use absolute paths.

Since version 0.6.7, paths are relative to directory of nginx configuration file nginx.conf, but not to nginx prefix directory.

lock_file

Syntax: lock_file file

Default: compile-time option

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.


master_process

Syntax: master_process on | off
Default: on
Context: main
Reference:master_process


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

pcre_jit

Syntax: pcre_jit on | off
Default: off
Context: main
Appeared in: 1.1.12
Reference:pcre_jit


pid

Syntax: pid file
Default: nginx.pid
Context: main
Reference:pid


Example:

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 `cat /var/log/nginx.pid`

ssl_engine

Syntax: ssl_engine device
Default:
Context: main
Reference:ssl_engine


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 ] 

timer_resolution

Syntax: timer_resolution interval
Default:
Context: main
Reference:timer_resolution


Example:

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.


user

Syntax: user user [ group ]
Default: nobody nobody
Context: main
Reference:user


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.

Example:

user www users;

worker_cpu_affinity

Syntax: worker_cpu_affinity cpumask ...
Default:
Context: main
Reference:worker_cpu_affinity


Linux only.

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

For example,

worker_processes     4;
worker_cpu_affinity 0001 0010 0100 1000;

Bind each worker process to one CPU only.

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

worker_priority

Syntax: worker_priority number
Default: 0
Context: main
Reference:worker_priority


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

worker_processes

Syntax: worker_processes number
Default: 1
Context: main
Reference:worker_processes


e.g.:

A worker process is a single-threaded process.

If Nginx is doing CPU-intensive work such as SSL or gzipping and you have 2 or more CPUs/cores, then you may set worker_processes to be equal to the number of CPUs or cores.

If you are serving a lot of static files and the total size of the files is bigger than the available memory, then you may increase worker_processes to fully utilize disk bandwidth.

Your OS may schedule all workers on single CPU/core this can be avoided using worker_cpu_affinity.

Nginx has the ability to use more than one 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

worker_rlimit_core

Syntax: worker_rlimit_core size
Default:
Context: main
Reference:worker_rlimit_core


Maximum size of core file per worker. Used for Debugging Nginx.

worker_rlimit_nofile

Syntax: worker_rlimit_nofile number
Default:
Context: main
Reference:worker_rlimit_nofile


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

worker_rlimit_sigpending

Syntax: worker_rlimit_sigpending limit

Default:

(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

Syntax: working_directory directory
Default:
Context: main
Reference:working_directory


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

Variables

$pid

The process ID;

$realpath_root

(undocumented)

References

Original Documentation