Controlling nginx控制nginx

Changing Configuration更改配置
Rotating Log-files旋转日志文件
Upgrading Executable on the Fly动态升级可执行文件

nginx can be controlled with signals. nginx可以通过信号进行控制。The process ID of the master process is written to the file /usr/local/nginx/logs/nginx.pid by default. 默认情况下,主进程的进程ID写入文件/usr/local/nginx/logs/nginx.pidThis name may be changed at configuration time, or in nginx.conf using the pid directive. 此名称可以在配置时更改,也可以在nginx.conf中使用pid指令更改。The master process supports the following signals:主进程支持以下信号:

TERM, INTfast shutdown快速关机
QUITgraceful shutdown优雅关机
HUPchanging configuration, keeping up with a changed time zone (only for FreeBSD and Linux), starting new worker processes with a new configuration, graceful shutdown of old worker processes更改配置,跟上更改的时区(仅适用于FreeBSD和Linux),使用新配置启动新的工作进程,优雅地关闭旧的工作进程
USR1re-opening log files重新打开日志文件
USR2upgrading an executable file升级可执行文件
WINCHgraceful shutdown of worker processes工作进程的正常关闭

Individual worker processes can be controlled with signals as well, though it is not required. 单个工作进程也可以通过信号进行控制,尽管这不是必需的。The supported signals are:支持的信号包括:

TERM, INTfast shutdown快速关机
QUITgraceful shutdown优雅关机
USR1re-opening log files重新打开日志文件
WINCHabnormal termination for debugging (requires debug_points to be enabled)调试异常终止(需要启用debug_points

Changing Configuration更改配置

In order for nginx to re-read the configuration file, a HUP signal should be sent to the master process. 为了让nginx重新读取配置文件,应该向主进程发送一个HUP信号。The master process first checks the syntax validity, then tries to apply new configuration, that is, to open log files and new listen sockets. 主进程首先检查语法有效性,然后尝试应用新配置,即打开日志文件和新的侦听套接字。If this fails, it rolls back changes and continues to work with old configuration. 如果失败,它将回滚更改并继续使用旧配置。If this succeeds, it starts new worker processes, and sends messages to old worker processes requesting them to shut down gracefully. 如果成功,它将启动新的工作进程,并向旧的工作进程发送消息,请求它们正常关闭。Old worker processes close listen sockets and continue to service old clients. 旧工作进程关闭侦听套接字并继续为旧客户端提供服务。After all clients are serviced, old worker processes are shut down.在所有客户端都得到服务之后,旧的工作进程将关闭。

Let’s illustrate this by example. 让我们用例子来说明这一点。Imagine that nginx is run on FreeBSD and the command假设nginx在FreeBSD上运行,命令

ps axw -o pid,ppid,user,%cpu,vsz,wchan,command | egrep '(nginx|PID)'

produces the following output:生成以下输出:

PID  PPID USER    %CPU   VSZ WCHAN  COMMAND 33126     1 root     0.0  1148 pause  nginx: master process /usr/local/nginx/sbin/nginx 33127 33126 nobody   0.0  1380 kqread nginx: worker process (nginx)
33128 33126 nobody   0.0  1364 kqread nginx: worker process (nginx)
33129 33126 nobody   0.0  1364 kqread nginx: worker process (nginx)

If HUP is sent to the master process, the output becomes:如果HUP被发送到主进程,则输出变为:

PID  PPID USER    %CPU   VSZ WCHAN  COMMAND 33126     1 root     0.0  1164 pause  nginx: master process /usr/local/nginx/sbin/nginx 33129 33126 nobody   0.0  1380 kqread nginx: worker process is shutting down (nginx)
33134 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
33135 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
33136 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)

One of the old worker processes with PID 33129 still continues to work. 其中一个PID为33129的旧辅助进程仍在继续工作。After some time it exits:一段时间后,它退出:

PID  PPID USER    %CPU   VSZ WCHAN  COMMAND 33126     1 root     0.0  1164 pause  nginx: master process /usr/local/nginx/sbin/nginx 33134 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
33135 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
33136 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)

Rotating Log-files旋转日志文件

In order to rotate log files, they need to be renamed first. 为了旋转日志文件,需要首先重命名它们。After that USR1 signal should be sent to the master process. 之后,USR1信号应发送至主进程。The master process will then re-open all currently open log files and assign them an unprivileged user under which the worker processes are running, as an owner. 然后,主进程将重新打开所有当前打开的日志文件,并为它们分配一个工作进程运行时所使用的非特权用户作为所有者。After successful re-opening, the master process closes all open files and sends the message to worker process to ask them to re-open files. 成功重新打开后,主进程关闭所有打开的文件,并将消息发送给工作进程,要求它们重新打开文件。Worker processes also open new files and close old files right away. 辅助进程还可以立即打开新文件和关闭旧文件。As a result, old files are almost immediately available for post processing, such as compression.因此,旧文件几乎可以立即用于后处理,如压缩。

Upgrading Executable on the Fly动态升级可执行文件

In order to upgrade the server executable, the new executable file should be put in place of an old file first. 为了升级服务器可执行文件,应首先将新的可执行文件替换为旧文件。After that USR2 signal should be sent to the master process. 之后,USR2信号应发送至主进程。The master process first renames its file with the process ID to a new file with the .oldbin suffix, e.g. /usr/local/nginx/logs/nginx.pid.oldbin, then starts a new executable file that in turn starts new worker processes:主进程首先使用进程ID将其文件重命名为带有.oldbin后缀的新文件,例如/usr/local/nginx/logs/nginx.pid.oldbin,然后启动一个新的可执行文件,该文件依次启动新的工作进程:

PID  PPID USER    %CPU   VSZ WCHAN  COMMAND 33126     1 root     0.0  1164 pause  nginx: master process /usr/local/nginx/sbin/nginx 33134 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
33135 33126 nobody   0.0  1380 kqread nginx: worker process (nginx)
33136 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
36264 33126 root     0.0  1148 pause  nginx: master process /usr/local/nginx/sbin/nginx 36265 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36266 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36267 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)

After that all worker processes (old and new ones) continue to accept requests. 在此之后,所有工作进程(旧进程和新进程)继续接受请求。If the WINCH signal is sent to the first master process, it will send messages to its worker processes, requesting them to shut down gracefully, and they will start to exit:如果绞车信号被发送到第一个主进程,它将向其工作进程发送消息,请求它们正常关闭,它们将开始退出:

PID  PPID USER    %CPU   VSZ WCHAN  COMMAND 33126     1 root     0.0  1164 pause  nginx: master process /usr/local/nginx/sbin/nginx 33135 33126 nobody   0.0  1380 kqread nginx: worker process is shutting down (nginx)
36264 33126 root     0.0  1148 pause  nginx: master process /usr/local/nginx/sbin/nginx 36265 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36266 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36267 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)

After some time, only the new worker processes will process requests:一段时间后,只有新的工作进程将处理请求:

PID  PPID USER    %CPU   VSZ WCHAN  COMMAND 33126     1 root     0.0  1164 pause  nginx: master process /usr/local/nginx/sbin/nginx 36264 33126 root     0.0  1148 pause  nginx: master process /usr/local/nginx/sbin/nginx 36265 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36266 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36267 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)

It should be noted that the old master process does not close its listen sockets, and it can be managed to start its worker processes again if needed. 应该注意的是,旧的主进程不会关闭其侦听套接字,如果需要,可以管理它重新启动其工作进程。If for some reason the new executable file works unacceptably, one of the following can be done:如果由于某种原因,新的可执行文件无法正常工作,则可以执行以下操作之一:

If the new master process exits then the old master process discards the .oldbin suffix from the file name with the process ID.如果新主进程退出,则旧主进程将丢弃进程ID为的文件名中的.oldbin后缀。

If upgrade was successful, then the QUIT signal should be sent to the old master process, and only new processes will stay:如果升级成功,则应向旧主进程发送退出信号,并且只有新进程将保留:

PID  PPID USER    %CPU   VSZ WCHAN  COMMAND 36264     1 root     0.0  1148 pause  nginx: master process /usr/local/nginx/sbin/nginx 36265 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36266 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36267 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)