Nginx核心模块|Nginx中文参考手册,教程

###主模块（Main Module）

·摘要
包含一些Nginx的基本控制功能
·指令
```
daemon
```
语法：daemon on | off
默认值：on
```
daemon off;
```
生产环境中不要使用"daemon"和"master_process"指令，这些指令仅用于开发调试。虽然可以使用daemon off在生产环境中，但对性能提升没有任何帮助，但是在生产环境中永远不要使用master_process off。

```
env
```
语法：env VAR|VAR=VALUE
默认值：TZ
使用字段：main
这个命令允许其限定一些环境变量的值，在以下的情况下会创建或修改变量的值：
·在不停机情况下升级、增加或删除一些模块时继承的变量
·使用嵌入式perl模块
·使用工作中的进程，必须记住，某些类似系统库的行为管理仅在变量初始化时频繁地使用库文件，即仍然可以用之前给定的命令设置，上面提到的零停机更新文件是一个例外（此句不知怎么翻，原文：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. ）
如果没有明确的定义TZ的值,默认情况下它总是继承的，并且内置的Perl模块总是可以使用TZ的值。
例：

```
env  MALLOC_OPTIONS;
env  PERL5LIB=/data/site/modules;
env  OPENSSL_ALLOW_PROXY_CERTS=1;
debug_points
```
语法：debug_points [stop | abort]
默认值：none（无）
```
debug_points stop;
```
在Nginx内部有很多断言，如果debug_points的值设为stop时，那么触发断言时将停止Nginx并附加调试器。如果debug_point的值设为abort,那么触发断言时将创建内核文件。

```
error_log
```
语法：error_log file [ debug | info | notice | warn | error | crit ]
默认值：${prefix}/logs/error.log
指定Nginx服务（与FastCGI）错误日志文件位置。
每个字段的错误日志等级默认值：
1、main字段 - error
2、HTTP字段 - crit
3、server字段 - crit
Nginx支持为每个虚拟主机设置不同的错误日志文件，这一点要好于lighttpd，详细为每个虚拟主机配置不同错误日志的例子请参考：SeparateErrorLoggingPerVirtualHost和mailing list thread on separating error logging per virtual host
如果你在编译安装Nginx时加入了--with-debug参数，你可以使用以下配置：
```
error_log LOGFILE [debug_core | debug_alloc | debug_mutex | debug_event | debug_http | debug_imap];
```
注意error_log off并不能关闭日志记录功能，而会将日志文件写入一个文件名为off的文件中，如果你想关闭错误日志记录功能，应使用以下配置：
```
error_log /dev/null crit;
```
同样注意0.7.53版本，nginx在使用配置文件指定的错误日志路径前将使用编译时指定的默认日志位置，如果运行nginx的用户对该位置没有写入权限，nginx将输出如下错误：
```
[alert]: could not open error log file: open() "/var/log/nginx/error.log" failed (13: Permission denied)
log_not_found
```
语法：log_not_found on | off
默认值：on
使用字段：location
这个参数指定了是否记录客户端的请求出现404错误的日志，通常用于不存在的robots.txt和favicon.ico文件，例如：
```
location = /robots.txt {
  log_not_found  off;
}
include
```
语法：include file | *
默认值：none
你可以包含一些其他的配置文件来完成你想要的功能。
0.4.4版本以后，include指令已经能够支持文件通配符：
```
include vhosts/*.conf;
```
注意：直到0.6.7版本，这个参数包含的文件相对路径随你在编译时指定的--prefix=PATH目录而决定，默认是/usr/local/nginx，如果你不想指定这个目录下的文件，请写绝对路径。
0.6.7版本以后指定的文件相对路径根据nginx.conf所在的目录而决定，而不是prefix目录的路径。
```
lock_file
```
语法：lock_file file
默认值：编译时指定
lock_file  /var/log/lock_file;
Nginx使用连接互斥锁进行顺序的accept()系统调用，如果Nginx在i386,amd64,sparc64,与ppc64环境下使用gcc,Intel C++,或SunPro C++进行编译，Nginx将采用异步互斥进行访问控制，在其他情况下锁文件会被使用。

```
master_process
```
语法：master_process on | off
默认值：on
```
master_process  off;
```
生产环境中不要使用"daemon"和"master_process"指令，这些选项仅用于开发调试。
```
pid
```
语法：pid file
默认值：编译时指定
```
pid /var/log/nginx.pid;
```
指定pid文件，可以使用kill命令来发送相关信号，例如你如果想重新读取配置文件，则可以使用：kill -HUP `cat /var/log/nginx.pid`
```
ssl_engine
```
语法：ssl_engine engine
默认值：依赖于系统环境
这里可以指定你想使用的OpenSSL引擎，你可以使用这个命令找出哪个是可用的：openssl engine -t
```
$ openssl engine -t
(cryptodev) BSD cryptodev engine
  [ 可用 ] 
(dynamic) Dynamic engine loading support
  [ 不可用 ] 
timer_resolution
```
语法：timer_resolution t
默认值：none
```
timer_resolution  100ms;
```
这个参数允许缩短gettimeofday()系统调用的时间，默认情况下gettimeofday()在下列都调用完成后才会被调用：kevent(), epoll, /dev/poll, select(), poll()。
如果你需要一个比较准确的时间来记录$upstream_response_time或者$msec变量，你可能会用到timer_resolution
```
try_files
```
语法：try_files path1 [ path2] uri
默认值：none
可用版本：0.7.27
按照顺序检查存在的文件，并且返回找到的第一个文件，斜线指目录：$uri / 。如果在没有找到文件的情况下，会启用一个参数为last的内部重定向，这个last参数“必须”被设置用来返回URL，否则会产生一个内部错误。
在代理Mongrel中使用：
```
location / {
  try_files /system/maintenance.html
  $uri $uri/index.html $uri.html @mongrel;
}
 
location @mongrel {
  proxy_pass http://mongrel;
}
```
在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
}
```
在这个例子中，这个try_files指令：
```
location / {
  try_files $uri $uri/ @drupal;
}
```
等同于下列配置：
```
location / {
  error_page     404 = @drupal;
  log_not_found  off;
}
```
这段：
```
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在将请求提交到FastCGI服务之前检查存在的php文件。
一个在Wordpress和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
}
```
user
语法：user user [group]
默认值：nobody nobody
如果主进程以root运行，Nginx将会调用setuid()/setgid()来设置用户/组，如果没有指定组，那么将使用与用户名相同的组，默认情况下会使用nobody用户与nobody组（或者nogroup），或者在编译时指定的--user=USER和--group=GROUP的值。

```
user www users;
worker_cpu_affinity
```
语法：worker_cpu_affinity cpumask [cpumask...]
默认值：none
仅支持linux系统。
这个参数允许将工作进程指定到cpu，它调用sched_setaffinity()函数
```
worker_processes     4;
worker_cpu_affinity 0001 0010 0100 1000;
```
指定每个进程到一个CPU：
```
worker_processes     2;
worker_cpu_affinity 0101 1010;
```
指定第一个进程到CPU0/CPU2，指定第二个进程到CPU1/CPU3，对于HTT处理器来说是一个不错的选择。
```
worker_priority
语法：worker_priority [-] number
```
默认值：on
这个选项可以用来设置所有工作进程的优先级（即linux系统中的nice），它调用setpriority()。
```
worker_processes
语法：worker_processes number
```
默认值：1
```
worker_processes 5;
```
由于以下几点原因，Nginx可能需要运行不止一个进程
·使用了SMP（对称多处理技术）。
·当服务器在磁盘I/O出现瓶颈时为了减少响应时间。
·当使用select()/poll()限制了每个进程的最大连接数时。
在事件模块这一章中我们将使用worker_processes和worker_connections来计算理论最大连接数（max_clients）：
```
max_clients = worker_processes * worker_connections
worker_rlimit_core
```
语法：worker_rlimit_core size
默认值：
允许的每个进程核心文件最大值。
```
worker_rlimit_nofile
语法：worker_rlimit_nofile limit
```
默认值：
进程能够打开的最多文件描述符数
```
worker_rlimit_sigpending
语法：worker_rlimit_sigpending limit
```
默认值：
linux内核2.6.8以后，限制调用的进程中真实用户队列可能使用的信号数量。
```
working_directory
```
语法：working_directory path
默认值：--prefix
程序的工作目录，一般只用来指定核心文件位置，Nginx仅使用绝对路径，所有在配置文件中的相对路径会转移到--prefix==PATH
·变量
```
$pid
```
进程ID号
```
$realpath_root
```

###事件模块（Events Module）

·摘要
控制Nginx处理连接的方式
·指令
```
accept_mutex
```
语法：accept_mutex [ on | off ]
默认值：on
Nginx使用连接互斥锁进行顺序的accept()系统调用
```
accept_mutex_delay
```
语法：accept_mutex_delay Nms;
默认值：500ms
如果一个进程没有互斥锁，它将至少在这个值的时间后被回收，默认是500ms
```
debug_connection
```
语法：debug_connection [ip | CIDR]
默认值：none
0.3.54版本后，这个参数支持CIDR地址池格式。
这个参数可以指定只记录由某个客户端IP产生的debug信息。
当然你也可以指定多个参数。
```
error_log /var/log/nginx/errors;
events {
  debug_connection   192.168.1.1;
}
devpoll_changes
devpoll_events
kqueue_changes
kqueue_events
epoll_events
```
语法：devpoll_changes
默认值：
这些参数指定了按照规定方式传递到或者来自内核的事件数，默认devpoll的值为32，其余为512。
```
multi_accept
```
语法：multi_accept [ on | off ]
默认值：off
multi_accept在Nginx接到一个新连接通知后调用accept()来接受尽量多的连接
```
rtsig_signo
```
语法：rtsig_signo
默认值：
Nginx在rtsig模式启用后使用两个信号，该指令指定第一个信号编号，第二个信号编号为第一个加1
默认rtsig_signo的值为SIGRTMIN+10 (40)。
```
rtsig_overflow_events
rtsig_overflow_test
rtsig_overflow_threshold
语法：rtsig_overflow_*
```
默认值：
这些参数指定如何处理rtsig队列溢出。当溢出发生在nginx清空rtsig队列时，它们将连续调用poll()和 rtsig.poll()来处理未完成的事件，直到rtsig被排空以防止新的溢出，当溢出处理完毕，nginx再次启用rtsig模式。
rtsig_overflow_events specifies指定经过poll()的事件数，默认为16
rtsig_overflow_test指定poll()处理多少事件后nginx将排空rtsig队列，默认值为32
rtsig_overflow_threshold只能运行在Linux 2.4.x内核下，在排空rtsig队列前nginx检查内核以确定队列是怎样被填满的
默认值为1/10，“rtsig_overflow_threshold 3”意为1/3。
```
use
```
语法：use [ kqueue | rtsig | epoll | /dev/poll | select | poll | eventport ]
默认值：
如果你在./configure的时候指定了不止一个事件模型，你可以通过这个参数告诉nginx你想使用哪一个事件模型，默认情况下nginx在编译时会检查最适合你系统的事件模型。
你可以在这里看到所有可用的事件模型并且如果在./configure时激活它们。
```
worker_connections
```
语法：worker_connections
默认值：
worker_connections和worker_proceses（见主模块）允许你计算理论最大连接数：
最大连接数 = worker_processes * worker_connections
在反向代理环境下：
最大连接数 = worker_processes * worker_connections/4
由于浏览器默认打开2个连接到服务器，nginx使用来自相同地址池的fds（文件描述符）与前后端相连接