关于nginx的几个核心配置说明

2014-06-29 wcdj

学习和使用nginx，首先需要了解nginx的配置选项的含义，比较好的学习方法是，先保存复制一份默认的nginx.conf配置，然后开始动手修改自己感兴趣的配置，尝试各种功能。在遇到配置错误时，nginx可以很友好地给我们做出提示：

比如在添加配置时少一个分号，nginx会提示如下的错误信息：

root@mba:sbin#./nginx 
nginx: [emerg] directive "daemon" is not terminated by ";" in /Users/gerryyang/LAMP/nginx/install/nginx-1.7.2/conf/nginx.conf:19

比如在Mac OS X上指定event为epoll时，会提示如下错误信息：

root@mba:sbin#./nginx 
nginx: [emerg] invalid event type "epoll" in /Users/gerryyang/LAMP/nginx/install/nginx-1.7.2/conf/nginx.conf:14

下面是nginx几个核心的配置说明：

(1) accept_mutex的说明

Syntax:	accept_mutex on | off;
Default:	accept_mutex on;
Context:	events

If accept_mutex is enabled,worker processes will accept new connections by turn.Otherwise, all worker processes will be notified about new connections,and if volume of new connections is low, some of the worker processesmay just waste system resources.

The use of rtsig connection processing methodrequires accept_mutex to be enabled.

Syntax:	accept_mutex_delay time;
Default:	accept_mutex_delay 500ms;
Context:	events

If accept_mutex is enabled, specifies the maximum timeduring which a worker process will try to restart accepting newconnections if another worker process is currently acceptingnew connections.

(2) Connections processing methods的说明

nginx supports a variety of connection processing methods.The availability of a particular method depends on the platform used.On platforms that support several methods nginx will normallyselect the most efficient method automatically.However, if needed, a connection processing method can be selectedexplicitly with the use directive.

The following connection processing methods are supported:

• select — standard method.The supporting module is built automatically on platforms that lackmore efficient methods.The--with-select_module and--without-select_module configuration parameterscan be used to forcibly enable or disable the build of this module.

• poll — standard method.The supporting module is built automatically on platforms that lackmore efficient methods.The--with-poll_module and--without-poll_module configuration parameterscan be used to forcibly enable or disable the build of this module.

• kqueue — efficient method used onFreeBSD 4.1+, OpenBSD 2.9+, NetBSD 2.0, and Mac OS X.

• epoll — efficient method used onLinux 2.6+.

  Some older distributions like SuSE 8.2 provide patchesthat add epoll support to 2.4 kernels.

• rtsig — real time signals, efficient methodused on Linux 2.2.19+.By default,the system-wide event queue is limited by 1024 signals.On loaded servers it may become necessary to increase this limitby changing the/proc/sys/kernel/rtsig-max kernel parameter.However, in Linux 2.6.6-mm2 this parameter is gone, and each processnow has its own event queue.The size of each queue is limited byRLIMIT_SIGPENDINGand can be changed with worker_rlimit_sigpending.

  On queue overflow, nginx discards the queue and falls back topoll connection processing method untilthe situation gets back to normal.

• /dev/poll — efficient method used onSolaris 7 11/99+, HP/UX 11.22+ (eventport), IRIX 6.5.15+,and Tru64 UNIX 5.1A+.

• eventport — event ports, efficient methodused on Solaris 10.

(3) A debugging log说明

To enable a debugging log, nginx needs to be configured to supportdebugging during the build:

./configure --with-debug ...

Then the debug level should be set with the error_log directive:

error_log /path/to/log debug;

The nginx binary version for Windows is always built with the debugging logsupport, so only setting thedebug level will suffice.

Note that redefining the log without also specifying thedebuglevel will disable the debugging log.In the example below, redefining the log on the server level disables the debugging log for this server:

error_log /path/to/log debug;

http {
    server {
        error_log /path/to/log;
        ...

To avoid this, either the line redefining the log should becommented out, or thedebug level specification shouldalso be added:

error_log /path/to/log debug;

http {
    server {
        error_log /path/to/log debug;
        ...

It is also possible to enable the debugging log for selected client addresses only:

error_log /path/to/log;

events {
    debug_connection 192.168.1.1;
    debug_connection 192.168.10.0/24;
}

(4) event说明

Syntax:	events { ... }
Default:	—
Context:	main

Provides the configuration file context in which the directives thataffect connection processing are specified.

(5) include说明

Syntax:	include file | mask;
Default:	—
Context:	any

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

Usage example:

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

(6) lock_file说明

Syntax:	lock_file file;
Default:	lock_file logs/nginx.lock;
Context:	main

nginx uses the locking mechanism to implement accept_mutex and serialize access 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.

(7) master_process说明

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

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

(8) multi_accept说明

Syntax:	multi_accept on | off;
Default:	multi_accept off;
Context:	events

If multi_accept is disabled, a worker processwill accept one new connection at a time.Otherwise, a worker processwill accept all new connections at a time.

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

The use of rtsig connection processing methodautomatically enables multi_accept.

(9) pid说明

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

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

(10) use说明

Syntax:	use method;
Default:	—
Context:	events

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

(11) user说明

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

Defines user and groupcredentials used by worker processes.Ifgroup is omitted, a group whose name equalsthat ofuser is used.

(12) worker_connections说明

Syntax:	worker_connections number;
Default:	worker_connections 512;
Context:	events

Sets the maximum number of simultaneous connections thatcan 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 others),not only connections with clients.Another consideration is that the actual number of simultaneousconnections cannot exceed the current limit onthe maximum number of open files, which can be changed byworker_rlimit_nofile.

(13) worker_processes说明

Syntax:	worker_processes number | auto;
Default:	worker_processes 1;
Context:	main

Defines the number of worker processes.

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

The auto parameter is supported starting fromversions 1.3.8 and 1.2.5.

(14) worker_rlimit_core说明

Syntax:	worker_rlimit_core size;
Default:	—
Context:	main

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.

(15) worker_rlimit_nofile说明

Syntax:	worker_rlimit_nofile number;
Default:	—
Context:	main

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.

(16) worker_rlimit_sigpending说明

Syntax:	worker_rlimit_sigpending number;
Default:	—
Context:	main

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.

(17) working_directory说明

Syntax:	working_directory directory;
Default:	—
Context:	main

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

参考

[1] http://wiki.nginx.org/GettingStarted

[2] http://wiki.nginx.org/NginxModules

[3] http://wiki.nginx.org/NginxConfiguration

[4] http://blog.martinfjordvald.com/2010/07/nginx-primer/

[5] http://blog.martinfjordvald.com/2012/08/understanding-the-nginx-configuration-inheritance-model/