nginx中文文档-ngx_core_module

本文档包含以下指令:accept_mutex、accept_mutex_delay、daemon、debug_connection、debug_points、error_log、env、events、include、load_module、lock_file、master_process、multi_accept、pcre_jit、pid、ssl_engine、thread_pool、timer_resolution、use、user、worker_aio_requests、worker_connections、worker_cpu_affinity、worker_priority、worker_processes、worker_rlimit_core、worker_rlimit_nofile、working_directory

示例配置

user www www;
worker_processes 2;

error_log /var/log/nginx-error.log info;

events {
    use kqueue;
    worker_connections 2048;
}

...

accept_mutex

语法:accept_mutex on | off
默认:accept_mutex on
上下文:events

如果accept_mutex启用,工作进程会轮流接受新连接。否则,所有工作进程会接到新连接的通知,如果新连接的数量少,一些工作进程会浪费系统资源。

accept_mutex_delay

语法:accept_mutex_delay time
默认:accept_mutex_delay 500ms
上下文:events

如果accept_mutex启用,指定一个最大的时间,在这个期间如果另一个工作进程正在接受新连接,工作进程会尝试重新开始接受新连接。

daemon

语法:daemon on | off
默认:daemon on
上下文:main

决定nginx是否是守护进程。主要用于开发期间。

debug_connection

语法:debug_connection address | CIDR | unix:
默认:—
上下文:events

为选择的客户端连接启用调试日志。其他连接将使用error_log指令设置的日志等级。被调试的连接指定为IPv4或IPv6(1.3.0+,1.2.1+)地址或网络。连接也可以用主机名指定。对于使用UNIX-domain sockets(1.3.0+,1.2.1+)的连接,调试日志通过“unix:”参数启用。

events {
    debug_connection 127.0.0.1;
    debug_connection localhost;
    debug_connection 192.0.2.0/24;
    debug_connection ::1;
    debug_connection 2001:0db8::/32;
    debug_connection unix:;
    ...
}

为了使该指令工作,nginx需要使用–with-debug参数构建。

debug_points

语法:debug_points abort | stop
默认:—
上下文:main

该指令用于调试。
当检测到内部错误,例如,在重启工作进程时泄露的socket,开启debug_points引起核心文件创建(abort)或停止进程(stop)以便后续使用系统调试器进一步分析。

error_log

语法:error_log file [level]
默认:error_log logs/error.log error
上下文:main, http, mail, stream, server, location

配置日志。多个日志可以在同一个等级中指定(1.5.2+)。
第一个参数定义一个文件保存日志。特殊值stderr选择标准错误文件。记录到syslog可以由指定的“syslog:”前缀配置。记录到cyclic memory buffer可以有指定的“memory:”前缀和缓冲区大小配置,一般用于调试(1.7.11+)。
第二个参数决定了日志的等级,可以是下面任何一个值:debug, info, notice, warn, error, crit, alert 或 emerg。上面列出的日志等级是按严重度逐级递增的。如果参数忽略,则使用error。
为了debug记录工作,nginx需要以–with-debug参数构建。
从1.7.11版本起,指令可以在stream等级上指定。
从1.9.0版本起,指令可以在mail等级上指定。

env

语法:env variable[=value]
默认:env TZ
上下文:main

默认情况下,nginx移除所有继承自父进程的环境变量,处理TZ变量。这个指令允许保留一些继承的变量,改变它们的值或创建新的环境变量。这些变量是:

  • 当live upgrade是从可执行文件继承的
  • ngx_http_perl_module模块使用的
  • 工作进程使用的。应该清楚的是,通过这种方式控制系统库不总是可行的,因为一般的库只有在初始化时会检查变量,是在它们可以使用这个指令设置之前。一个例外就是上面提到的live upgrade的可执行文件。

TZ变量总是会继承,对ngx_http_perl_module模块有效,除非显式的配置它。
用法示例:

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

nginx环境变量是nginx内部使用的,不能直接由用户设置。

events

用法:events { … }
默认:—
上下文:main

指定配置文件上下文,用于指定关于连接处理的指令。

include

用法:include file | mask
默认:—
上下文:any

包含另一个文件或匹配指定的mask到配置中。被包含的文件应该保证依据语法结构的正确语句和块。
用法示例:

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

load_module

语法:load_module file
默认:—
上下文:main
版本:1.9.11+

加载动态模块。
例子:
load_module modules/ngx_mail_module.so;

lock_file

语法:lock_file file
默认:lock_file logs/nginx.lock
上下文:main

nginx使用锁机制时间accept_mutex和序列化访问共享内存。大多数操作系统上,锁使用原子操作实现,这个指令会被忽略。在其他系统上“lock file”机制被使用。这个指令为锁文件指定一个前缀。

master_process

语法:master_process on | off
默认:master_process on
上下文:main

决定工作进程是否启动。这个指令为开发者准备。

multi_accept

语法:multi_accept on | off
默认:multi_accept off
上下文:events

如果multi_accept禁用,工作进程将一次接受一个新连接。否则一个工作进程会同时接受所有的新连接。
如果使用kqueue连接处理方式,该指令会被忽略,因为它报告等待被接受的新连接的数量。

pcre_jit

语法:pcre_jit on | off
默认:pcre_jit off
上下文:main
版本:1.1.12+

启用或禁用为正则表达式使用“just-in-time compilation”(PCRE JIT)。
PCRE JIT可以显著提升处理正则表达式的速度。
JIT在PCRE库中可以使用时从8.20版本开始同–enable-jit配置参数构建。当PCRE与nginx一同构建(–with-pcre=),JIT支持可以通过–with-pcre-jit配置参数启用。

pid

语法:pid file
默认:pid nginx.pid
上下文:main

定义用于保存主进程的进程ID的文件。

ssl_engine

语法:ssl_engine device
默认:—
上下文:main

定义硬件SSL加速器的名字。

thread_pool

语法:thread_pool name threads=number [max_queue=number]
默认:thread_pool default threads=32 max_queue=65536
上下文:main
版本:1.7.11+

定义线程池名称用于多线程读取和发送文件,不阻塞工作进程。
threads参数定义了线程池中线程的数量。
在线程池中所有线程都繁忙的情况下,新任务会在队列中等待。max_queue参数限制了允许在队列中等待的任务的数量。默认是65536个。当队列溢出,任务会以错误完成。

timer_resolution

语法:timer_resolution interval
默认:—
上下文:main

降低工作进程中的时钟精度,以降低gettimeofday()系统调用发生的次数。默认情况下,gettimeofday()会在每一次内核时间接受后调用。设置后会在指定的间隔调用gettimeofday()。
例子:
timer_resolution 100ms;
间隔的内部实现取决于使用的方法:

  • 如果使用kqueue,则EVFILT_TIMER过滤器
  • 如果使用eventport,则timer_create()
  • 其他情况是setitimer()

use

语法:use method
默认:—
上下文:events

指定使用的连接处理方式。通常不需要显式的指定它,因为nginx默认会使用最高效的方法。

user

语法:user user [group]
默认:user nobody nobody
上下文:main

定义工作进程使用的用户和组的凭证。如果group忽略,会用同user的名字。

worker_aio_requests

语法:worker_aio_requests number
默认:worker_aio_requests 32
上下文:events
版本:1.1.4+1.0.7+

当使用aio和epoll连接处理方式时,设置一个工作进程未完成的异步I/O操作最大数。

worker_connections

语法:worker_connections number
默认:worker_connections 512
上下文:events

设置一个工作进程可以打开的最大并发连接数。
需要记住这个数包含所有连接(例如,与被代理服务器之间的连接),不只是与客户端的连接。还需要考虑的是实际并发连接数不能超过当前打开文件最大数限制,这个可以通过worker_rlimit_nofile改变。

worker_cpu_affinity

语法:worker_cpu_affinity cpumask …;
worker_cpu_affinity auto [cpumask]
默认:—
上下文:main

绑定工作进程与CPU。每个CPU设置体现在允许的CPU的位掩码。应该单独为每个工作进程定义。默认工作进程不会绑定任何指定的CPU。
例如,

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

绑定每一个工作进程到单独的CPU,但

worker_processes    2;
worker_cpu_affinity 0101 1010;

绑定第一个工作进程到CPU0/CPU2,第二个工作进程个到CPU1/CPU3。第二个例子适用于超线程技术。
特殊值auto(1.9.10+)允许自动绑定工作进程到可用的CPU:

worker_processes auto;
worker_cpu_affinity auto;

可选的掩码参数可以用于限制CPU对自动绑定的可用:
worker_cpu_affinity auto 01010101;
该指令只在FreeBSD和Linux系统上可用。

worker_priority

语法:worker_priority number
默认:worker_priority 0
上下文:main

为工作进程定义优先级,负数表示更高的优先级。允许的值从-20到20。
例子:
worker_priority -10;

worker_processes

语法:worker_processes number | auto
默认:worker_processes 1
上下文:main

定义工作进程数。
最佳值取决于很多因素包括(但不限于)CPU核心数、硬盘驱动器保存数据数以及加载的模式。当不确定时,设置为可用CPU核心数比较好(auto值会尝试自动识别)。
auto参数从1.3.8和1.2.5版本开始支持。

worker_rlimit_core

语法:worker_rlimit_core size
默认:—
上下文:main

为工作进程改变核心文件(RLIMIT_CORE)的最大大小的限制。用于增加限制而不重启主进程。

worker_rlimit_nofile

语法:worker_rlimit_nofile number
默认:—
上下文:main

为工作进程改变打开文件(RLIMIT_NOFILE)的最大数限制。用于增加限制而不需要重启主进程。

working_directory

语法:working_directory directory
默认:—
上下文:main

为工作进程定义当前的工作目录。主要用在写核心文件,这种情况下工作进程需要有指定目录的写权限。