Controlling nginx

nginx控制

Changing Configuration

更改配置

Rotating Log-files

日志循环

Upgrading Executable on the Fly

在线升级可执行文件


nginx can be controlled with signals. The process ID of the master process is written to the file /usr/local/nginx/logs/nginx.pid by default. This name may be changed at configuration time, or in nginx.conf using the pid directive. The master process supports the following signals:

nginx可以用信号控制。主进程的进程ID默认写入文件/usr/local/nginx/logs/nginx.pid。该名称可在配置时更改,或在nginx.conf中使用pid指令更改。主进程支持以下信号

TERM, INT快速关闭(fast shutdown)

QUIT优雅关闭(graceful shutdown)

HUP更改配置、与更改的时区保持同步(仅适用于 FreeBSD 和 Linux)、使用新配置启动新的工作进程、优雅关闭旧的工作进程
(changing 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)

USR1重新打开日志文件(re-opening log files)

USR2升级可执行文件(upgrading an executable file)

WINCH优雅的关闭工作进程(graceful shutdown of worker processes)

Individual worker processes can be controlled with signals as well, though it is not required. The supported signals are:

单个工作进程也可以用信号控制(但并非必需)。支持的信号有:

TERM, INT快速关闭(fast shutdown)

QUIT优雅关闭(graceful shutdown)

USR1重新打开配置文件(re-opening log files)

WINCH调试异常终止,要求启用debug_points(abnormal termination for debugging (requires debug_points to be enabled))

Changing Configuration

更改配置

In order for nginx to re-read the configuration file, a HUP signal should be sent to the master process. 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.

为了让nginx重新读取配置文件,应向主进程发送HUP信号。主进程首先检查语法是否有效,然后尝试应用新配置,即打开日志文件和监听新的套接字。如果失败,主进程会退回更改,继续使用旧配置。如果成功,它会启动新的工作进程,并向旧的工作进程发送信息,要求它们优雅地关闭。旧工作进程关闭监听套接字,继续为旧客户端提供服务。当所有客户端完成服务后,旧的工作进程就会关闭。

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. After some time it exits:

其中一个PID为33129的旧工作进程仍在继续工作。直到一段时间后,它才退出了:

  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. 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.

为了持续记录日志文件,需要先重命名这些文件。然后向主进程发送USR1信号。接着,主进程将重新打开所有当前打开的日志文件,并将它们分配给正在运行工作进程的非特权用户作为所有者。重新打开成功后,主进程会关闭所有打开的文件,并向工作进程发送信息,要求打开日志文件。工作进程会立即打开新文件并关闭旧文件。此时,旧文件即可用于压缩等后期处理。

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. 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:

要升级服务器可执行文件,首先应将新的可执行文件放在旧文件的位置上。然后向主进程发送USR2信号。主进程首先会将其重命名为带有进程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:

之后,所有工作进程(新旧进程)都将继续接受请求。如果向第一个主进程发送了WINCH信号,它就会向其工作进程发送信息,要求它们优雅地关闭,然后开始退出:

  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:

需要注意的是,旧的主进程并不会关闭其套接字,如果需要,可以再次启动其工作进程。如果新的可执行文件由于某种原因无法正常运行,可以采取以下措施之一:

  • Send the HUP signal to the old master process. The old master process will start new worker processes without re-reading the configuration. After that, all new processes can be shut down gracefully, by sending the QUIT signal to the new master process.

    向旧主进程发送HUP信号。旧的主进程将在不重新读取配置的情况下启动新的工作进程。之后,通过向新的主进程发送QUIT信号,可以优雅地关闭所有新进程。

  • Send the TERM signal to the new master process. It will then send a message to its worker processes requesting them to exit immediately, and they will all exit almost immediately. (If new processes do not exit for some reason, the KILL signal should be sent to them to force them to exit.) When the new master process exits, the old master process will start new worker processes automatically.

    向新的主进程发送TERM信号。然后,它会向其工作进程发送立即退出的信息,则工作进程立即退出。(如果新进程由于某种原因没有退出,则应向它们发送 KILL 信号以强制它们退出)。新的主进程退出后,旧的主进程将自动启动新的工作进程。

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:

如果升级成功,则应向旧的主进程发送QUIT信号,只保留新的进程:

  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)