Detailed explanation of Nginx configuration file examples

Nginx configuration file structure

The nginx configuration file is composed of directives. The instructions are divided into two forms, simple instructions and block instructions.

A simple command consists of the command name, parameters and a trailing semicolon (;), for example: listen 80 backlog 4096;, where "listen" is the command name, "80", "backlog", and "4096" are all parameters, and ";" indicates the end of the command.

Block instruction consists of the instruction name, parameters and curly braces ({}), for example: location /imag {}, where "location" is the instruction name , "/imag" is a parameter, "{}" is used to include other instructions and indicate the end. If the curly braces in a block instruction can include other simple instructions or block instructions, then this block instruction is called "context(context)". Most commonly used block instructions are "context".

Instructions that are not included in any other block instructions are considered to be in the main context, that is, the main context is the outermost context in the nginx configuration file, and any instruction is located in the main context or main context. in the child context of . Please look at the following configuration file example:

 1 # nginx.conf 2 worker_processes 2; 3 events { 4     use epoll; 5     worker_connections 1024; 6 } 7 http { 8     include       mime.types; 9     upstream server_group_a {   
10       server 192.168.1.1:8080;11       server 192.168.1.2:8080;12     }13     server {14         listen       80;15         server_name  www.example.com;   
16         location / {17            proxy_pass  http://server_group_a;        18         } 
19     }20 }

In the above example, the worker_processes, event, and http instructions are in the main context, the use and worker_connections instructions are in the event context, and the include and upstream The server instruction is located in the http context, and the two server instructions are located in the upstream context...

nginx software is composed of modules with various functions, so the configuration file also follows this modular structure , the nginx core module provides some global configuration instructions, and the functional configuration instructions are provided by other functional modules. The worker_processes and event instructions in the above example are provided by the core module of nginx, while the http instruction is provided by the http function module, and the proxy_pass instruction is provided by a submodule of the http module.

When installing nginx, some common function modules are included by default. Users can also freely choose to install other function modules through source code compilation and installation. When configuring nginx, they can find the documentation for the function modules. The documentation will Explain what instructions this functional module includes, and the context in which these instructions should be configured. However, it is unreliable to find out which configurable instructions it contains from the context (instructions), because the installed modules contain different instructions. It is also different, so configuring nginx requires some experience. Beginners can only start by referring to other people's examples.

In addition to http, the functional modules also include mail (mail proxy) and stream (TCP, UDP proxy, v1.9.0 and later) These two functional modules.

Global configuration directive

• Syntax: include file | mask;

• Default value: None

• Context: Any

can be used in any context to introduce directives in other configuration files into the context of using the include directive. The imported instructions need to comply with the syntax and context requirements of the introduction. Example:

http {
    include mime.types;
    include vhosts/*.conf;
}

将mime.types和vhosts目录下以“.conf”结尾的文件引入到http语境中。

• 语法：deamon on | off;

• 默认值：deamon on

• 语境：main

指定nginx是否以守护进程运行。

• 语法：debug_points abort | stop;

• 默认值：无

• 语境：main

用于debug，判断nginx内部错误，特别是判断工作中进程的socket溢出问题。nginx代码中包含了一些调试点，如果debug_points设置为abord，当运行到调试点时会产生一个核心运行信息dump文件，当设置为stop时会停止进程。

• 语法：error_log file [level]

• 默认值：error_log logs/error.log error;

• 语境：main, http, mail(v1.9.0后), stream(v1.7.11后), server, location

指定日志文件和日志级别。

file可以是指定的文件，也可以是标准错误输出文件stderr、syslog服务器或内存。输出到syslog服务器使用“syslog:”前缀，输出到循环内存缓冲区使用“memory:”前缀和缓冲区大小。

level参数指定输出日志的级别，高于指定级别的日志将被输出。支持的级别从低到高依次有：debug、info、notice、warn、error、crit、alert、emerg。

指定debug级别需要编译时安装了debug模块。

• 语法：env variable[=value];

• 默认值：env TZ;

• 语境：main

默认情况下，nginx只会继承TZ这个环境变量，这条指令可以将环境变量传递到nginx进程中，也可以定义新的变量传递到nginx进程中。

• 语法：load_module file;

• 默认值：无

• 语境：main

载入动态模块。例如：

load_module module/ngx_mail_module.so;

• 语法：lock_file file;

• 默认值：lock_file logs/nginx.lock;

• 语境：main

nginx使用锁的机制来实现accept_mutex功能和共享内存，大多数操作系统中锁都是一个原子操作，这种情况下这条指令无效，还有一些操作系统中使用“锁文件”的的机制来实现锁，此命令用来指定锁文件前缀名。

• 语法：master_process on | off;

• 默认值：master_process on;

• 语境：main

是否启用worker进程，如果设置为off，则不启用worker进程，由master进程处理请求。

• 语法：pcre_jit on | off;

• 默认值：pcre_jit off;

• 语境：main

在解析配置文件时对正则表达式启用或禁用实时编译（PCRE JIT）。

RCRE JIT能显著提升正则表达式的处理速度。

JIT依赖PCRE库8.20以后版本，并且在编译时需要指定--enable-jit参数。也可以将PCRE库作为nginx的模块编译安装（编译nginx指定--with-pcre=参数），并在编译时指定--with-pcre-jit参数启用JIT功能。

• 语法：pid file;

• 默认值：pid nginx.pid;

• 语境：main

指定pid文件。pid文件存放了master进程的进程号。

语法：ssl_engine device;

默认值：无

语境：main

如果使用了硬件ssl加速设备，使用此指令指定。

• 语法：thread_pool name threads=number [max_queue=number];

• 默认值：thread_pool default threads=32 max_queue=65535;

• 语境：main

在使用异步IO的情况下，定义命名线程池，并设置线程池大小和等待队列大小。当线程池中所有线程都繁忙时，新任务会放在等待队列中，如果等待队列满了，任务会报错退出。

命名线程池可以定义多个，供http模块的异步线程指令（aio）调用。

此指令在v1.7.11中出现。

• 语法：timer_resolution interval;

• 默认值：无

• 语境：main

设置时间精度，减少worker进程调用系统时间函数的次数。默认情况下，每个核心事件都会调用gettimeofday()接口来获得系统时间，以便nginx计算连接超时等工作，此指令指定更新时间的间隔，nginx在间隔时间内只调用一次系统时间函数。

• 语法：user user [group];

• 默认值：user nobody nodoby;

• 语境：main

指定master启动worker进程使用的linux用户和组。如果组（group）没有指定，那么会默认用一个和user同名的组名。

• 语法：worker_processes number | auto

• 默认值：worker_processes 1

• 语境：main

指定worker进程的数量。进程数最好是CPU核心数或CPU核心数的倍数。当设置为auto时，nginx会尝试自动获取CPU核心数并设置。

auto参数从v1.3.8和v1.2.5版本以后支持。

• 语法：worker_cpu_affinity cpumask ...;

• 　　　worker_cpu_affinity auto [cpumask];

• 默认值：无

• 语境：main

将worker进程绑定到CPU核心，每个worker进程对应一个二进制掩码，掩码的每一位对应一个CPU。默认情况下，worker不与cpu核心绑定。此指令只适用于Linux和FreeBSD。

举例：

worker_processes 4;
worker_cpu_affinity 0001 0010 0100 1000;

表示有4个worker进程，第一个绑定到CPU0，第二个绑定到CPU1，以此类推，4个进程分别绑定一个CPU核心。

再例：

worker_processes 2;
worker_cpu_affinity 0101 0101;

表示将第一个进程绑定到CPU0/CPU2，第二个worker进程绑定到CPU1/CPU3，这个例子适用于超线程场景，即一个核心虚拟出两个CPU线程。

值auto（v1.9.10）允许自动和可用的CPU绑定：

worker_process auto;
worker_cpu_affinity auto;

掩码（mask）可用用于限制某些CPU参加绑定。例如：

worker_cpu_affinity auto 01010101;

只有CPU0/2/4/6参与绑定，其他的CPU不分配worker进程。

• 语法：worker_rlimit_core size;

• 默认值：无

• 语境：main

为worker进程修改系统核心转储文件（core file）的大小限制。通常提升这个值不需要重启主进程。

• 语法：worker_rlimit_nofile number;

• 默认值：无

• 语境：main

修改worker进程最大可打开句柄数限制。通常提升这个值不需要重启主进程。

• 语法：worker_shutdown_timeout time;

• 默认值：无

• 语境：main

此指令在v1.11.11中出现。用于设置安全地结束一个worker进程的超时时间。

当安全结束一个worker进程时，会停止对worker进程分配新连接，并等待他处理完当前的任务后再退出，如果设置了超时时间，超时后nginx会强制关闭worker进程的连接。

• 语法：working_directory directory;

• 默认值：无

• 语境：main

指定默认工作路径。主要用于worker进程导出内存转储文件，为worker进程指定的用户需要有改文件的写入权限。

连接处理控制指令

• 语法：events { ... }

• 默认值：无

• 语境：main

作用只是开辟一个指令区块，events语境中配置的指令用于控制连接处理行为。

• 语法：accept_mutex on | off;

• 默认值：accept_mutex off;

• 语境：events

当启用这个参数时，会使用互斥锁交替给worker进程分配新连接，否则话所有worker进程会争抢新连接，即或造成所谓的“惊群问题”，惊群问题会使nginx的空闲worker进程无法进入休眠状态，造成系统资源占用过多。启用此参数会一定程度上导致后台服务器负载不均衡，但是在高并发的情况下，关闭此参数可以提高nginx的吞吐量。

在支持epoll的操作系统上不需要启用accept_mutex（v1.11.3后），使用了reuseport功能也不需要启用（v1.9.1后，需要操作系统支持SO_REUSEPORT socket选项，Linux 3.9+）。

在v1.11.3以前版本中，默认值为on。

• 语法：accept_mutex_delay time;

• 默认值：accept_mutex_delay 500ms;

• 语境：events

如果accept_mutex参数启用，当一个空闲worker进程尝试获取互斥锁时发现有另一个worker进程已经获得互斥锁并处理新连接，这个空闲的worker进程等待下一次获取互斥锁尝试的时间。而获得互斥锁的进程在处理完当前连接后，会立即尝试获取互斥锁，因此此数值较大或连接压力较小时，会造成部分worker进程总是空闲，一部分进程总是繁忙的情况。

• 语法：debug_connection address | network | unix:;

• 默认值：无

• 语境：events

需要debug模块支持，需确认安装时包括了debug模块，可以使用nginx -V命令确定包含--wih-debug参数。

对特定的客户发起的连接开启debugging级别日志，用于分析和拍错。可以指定IPv4或者IPv6地址（v1.3.0,v1.2.1）或一个无类网段或域名，或UNIX socket（v1.3.0,v1.2.1）。例如：

events {
    debug_connection 127.0.0.1;
    debug_connection localhost;
    debug_connection 192.168.2.0/24;
    debug_connection 2001:0db8::/32;
    debug_connection unix:;
}

The log level of non-specified connections is still determined by the error_log directive.

• Syntax: multi_accept on | off;

• Default value: multi_accept off;

• Context: events

When set to off, a worker process will only process one new connection at a time when acquiring the mutex. If set If it is on, all new connections will be allocated to the worker process that obtains the current mutex lock at once. When using kqueue connection processing method (use kqueue), this instruction is invalid.

• Syntax: use method;

• Default value: None

• Context: events

Specifies the connection processing method. Usually there is no need to specify, nginx will automatically use the most effective method.

The connection processing method is used to determine the method to use to find out which connections are ready to transmit/receive data from the current connection pool. Common connection processing methods include:

select (requires select module), poll (requires poll module), kqueue (macOS/FreeBSD 4.1+/OpenBSD 2.9+), epoll (Linux 2.6+), /dev/ poll (Solaris 7 11/99+, HP/UX 11.22+ (eventport), IRIX 6.5.15+, and Tru64 UNIX 5.1A+), eventport (Solaris 10+)

• Syntax: worker_aio_requests number;

• Default value: worker_aio_requests 32;

• Context: events

Appears in v1.1.4 and 1.0.7. When aio (asynchronous IO) and epoll connection processing are enabled, the maximum number of outstanding asynchronous IO operations for a single worker process.

• Syntax: worker_connections number;

• ##Default value: worker_connections 512;

• Context: events

The above is the detailed content of Detailed explanation of Nginx configuration file examples. For more information, please follow other related articles on the PHP Chinese website!