FAQ

Page Discussion Edit History

NginxCoreModule

Contents

Edit section: Synopsis Synopsis

These are the features that control basic Nginx functionality.


Edit section: Directives Directives

Edit section: daemon daemon

Syntax: daemon on | off

Default: on 

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.

Edit section: env env

Syntax: env VAR|VAR=VALUE

Default: TZ

Context: main

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;

Edit section: debug_points debug_points

Syntax: debug_points [stop | abort]

Default: none 

debug_points stop;

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.

Edit section: error_log error_log

Syntax: error_log file [ debug | info | notice | warn | error | crit ]

Default: ${prefix}/logs/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)

Edit section: log_not_found log_not_found

Syntax: log_not_found on | off

Default: on

Context: location

Enables or disables logging of requests that resolve into 404 status code. Can be used to prevent nginx from logging requests for the missing robots.txt and favicon.ico files. Example: 

location = /robots.txt {
  log_not_found  off;
}

Edit section: include include

Syntax: include file | *

Default: none

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.

Edit section: lock_file lock_file

Syntax: lock_file file

Default: compile-time option 

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.


Edit section: master_process master_process

Syntax: master_process on | off

Default: on 

master_process  off;

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

Edit section: pid pid

Syntax: pid file

Default: compile-time option

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`

Edit section: ssl_engine ssl_engine

Syntax: ssl_engine engine

Default: system dependent

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 ]

Edit section: timer_resolution timer_resolution

Syntax: timer_resolution t

Default: none

Example: 

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.

Edit section: try_files try_files

Syntax: try_files path1 [ path2] uri

Default: none

Availability: 0.7.27

Checks for the existence of files in order, and returns the first file that is found. A trailing slash indicates a directory - $uri /. In the event that no file is found, and internal redirect to the last parameter is invoked. The last parameter is the fallback URI and *must* exist, or else an internal error will be raised.

Example use in proxying Mongrel: 

location / {
  try_files /system/maintenance.html
  $uri $uri/index.html $uri.html @mongrel;
}
 
location @mongrel {
  proxy_pass http://mongrel;
}

Example of use with Drupal / FastCGI: 

location / {
  try_files $uri $uri/ @drupal;
}
 
location ~ \.php$ {
  try_files $uri @drupal;
  fastcgi_pass 127.0.0.1:8888;
  fastcgi_param  SCRIPT_FILENAME  /path/to$fastcgi_script_name;
  # other fastcgi_param
}
 
location @drupal {
  fastcgi_pass 127.0.0.1:8888;
  fastcgi_param  SCRIPT_FILENAME  /path/to/index.php;
  fastcgi_param  QUERY_STRING     q=$request_uri;
  # other fastcgi_param
}

In this example, the directive try_files: 

location / {
  try_files $uri $uri/ @drupal;
}

Similar directives: 

location / {
  error_page     404 = @drupal;
  log_not_found  off;
}

and here: 

location ~ \.php$ {
  try_files $uri @drupal;
 
  fastcgi_pass 127.0.0.1:8888;
  fastcgi_param  SCRIPT_FILENAME  /path/to$fastcgi_script_name;
  # other fastcgi_param
}


try_files tests the existence of PHP file, before submitting a request to the FastCGI server.

Example of use with Wordpress and Joomla: 

location / {
  try_files $uri $uri/ @wordpress;
}
 
location ~ \.php$ {
  try_files $uri @wordpress;
 
  fastcgi_pass 127.0.0.1:8888;
  fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
  # other fastcgi_param
}
 
location @wordpress {
    fastcgi_pass 127.0.0.1:8888;
    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    # other fastcgi_param
}

Edit section: user user

Syntax: user user [group]

Default: nobody nobody

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;


Edit section: worker_cpu_affinity worker_cpu_affinity

Syntax: worker_cpu_affinity cpumask [cpumask...]

Default: none

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. 

worker_processes     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.


Edit section: worker_priority worker_priority

Syntax: worker_priority [-] number

Default: on

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


Edit section: worker_processes worker_processes

Syntax: worker_processes number

Default: 1

e.g.: 

worker_processes 5;

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


Edit section: worker_rlimit_core worker_rlimit_core

Syntax: worker_rlimit_core size

Default:

Maximum size of core file per worker;


Edit section: worker_rlimit_nofile worker_rlimit_nofile

Syntax: worker_rlimit_nofile limit

Default:

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


Edit section: worker_rlimit_sigpending 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.

Edit section: working_directory working_directory

Syntax: working_directory path

Default: --prefix

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.

Edit section: Variables Variables

Edit section: $nginx_version $nginx_version

The version of Nginx that the server is currently running;

Edit section: $pid $pid

The process ID;

Edit section: $realpath_root $realpath_root

(undocumented)

Edit section: References References

Retrieved from "http://wiki.nginx.org/NginxCoreModule"