nginx-site: xml/en/docs/control.xml annotate

annotate xml/en/docs/control.xml @ 2677:3760176ba83e

Documented ngx_mail_realip_module.

author	Yaroslav Zhuravlev <yar@nginx.com>
date	Wed, 10 Mar 2021 20:35:36 +0000
parents	52d603f58bca
children

rev	line source
580 be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	1 <!--
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	2 Copyright (C) Igor Sysoev
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	3 Copyright (C) Nginx, Inc.
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	4 -->
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	5
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	6 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd">
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	7
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	8 <article name="Controlling nginx"
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	9 link="/en/docs/control.html"
589 764fbac1b8b4 Added document revision. Ruslan Ermilov <ru@nginx.com> parents: 585 diff changeset	10 lang="en"
2195 52d603f58bca Controlling nginx: removed history info from FreeBSD. Sergey Kandaurov <pluknet@nginx.com> parents: 2194 diff changeset	11 rev="7">
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	12
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	13 <section>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	14
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	15 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	16 nginx can be controlled with signals.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	17 The process ID of the master process is written to the file
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	18 <path>/usr/local/nginx/logs/nginx.pid</path> by default.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	19 This name may be changed at configuration time, or in
288 b33d3f3cd8ca Removed terminal whitespace. Ruslan Ermilov <ru@nginx.com> parents: 186 diff changeset	20 <path>nginx.conf</path> using the
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	21 <link doc="ngx_core_module.xml" id="pid"/>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	22 directive.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	23 The master process supports the following signals:
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	24 <note>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	25 <table>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	26
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	27 <tr><td width="20%">TERM, INT</td><td>fast shutdown</td></tr>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	28 <tr><td width="20%">QUIT</td><td>graceful shutdown</td></tr>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	29 <tr><td width="20%">HUP</td><td>changing configuration,
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	30 keeping up with a changed time zone (only for FreeBSD and Linux),
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	31 starting new worker processes with a new configuration,
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	32 graceful shutdown of old worker processes</td></tr>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	33 <tr><td width="20%">USR1</td><td>re-opening log files</td></tr>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	34 <tr><td width="20%">USR2</td><td>upgrading an executable file</td></tr>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	35 <tr><td width="20%">WINCH</td><td>graceful shutdown of worker processes</td></tr>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	36
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	37 </table>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	38 </note>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	39 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	40
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	41 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	42 Individual worker processes can be controlled with signals as well,
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	43 though it is not required.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	44 The supported signals are:
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	45 <note>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	46 <table>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	47
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	48 <tr><td width="20%">TERM, INT</td><td>fast shutdown</td></tr>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	49 <tr><td width="20%">QUIT</td><td>graceful shutdown</td></tr>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	50 <tr><td width="20%">USR1</td><td>re-opening log files</td></tr>
585 e83b551cb90e Documented what WINCH signal does when sent to a worker process. Ruslan Ermilov <ru@nginx.com> parents: 580 diff changeset	51 <tr><td width="20%">WINCH</td><td>abnormal termination for debugging
e83b551cb90e Documented what WINCH signal does when sent to a worker process. Ruslan Ermilov <ru@nginx.com> parents: 580 diff changeset	52 (requires <link doc="ngx_core_module.xml" id="debug_points"/> to be enabled)
e83b551cb90e Documented what WINCH signal does when sent to a worker process. Ruslan Ermilov <ru@nginx.com> parents: 580 diff changeset	53 </td></tr>
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	54
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	55 </table>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	56 </note>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	57 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	58
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	59 </section>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	60
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	61
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	62 <section id="reconfiguration" name="Changing Configuration">
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	63
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	64 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	65 In order for nginx to re-read the configuration file, a HUP
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	66 signal should be sent to the master process.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	67 The master process first checks the syntax validity, then tries
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	68 to apply new configuration, that is, to open log files and new
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	69 listen sockets.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	70 If this fails, it rolls back changes and continues to work
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	71 with old configuration.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	72 If this succeeds, it starts new worker processes, and
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	73 sends messages to old worker processes requesting them to
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	74 shut down gracefully.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	75 Old worker processes close listen sockets and continue to service
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	76 old clients.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	77 After all clients are serviced, old worker processes are shut down.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	78 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	79
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	80 <para>
625 af3f38e349eb Removed terminal whitespace and fixed apostrophes used. Ruslan Ermilov <ru@nginx.com> parents: 589 diff changeset	81 Let’s illustrate this by example.
2195 52d603f58bca Controlling nginx: removed history info from FreeBSD. Sergey Kandaurov <pluknet@nginx.com> parents: 2194 diff changeset	82 Imagine that nginx is run on FreeBSD and the command
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	83 <programlisting>
838 d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	84 ps axw -o pid,ppid,user,%cpu,vsz,wchan,command \| egrep '(nginx\|PID)'
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	85 </programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	86 produces the following output:
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	87 <programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	88 PID PPID USER %CPU VSZ WCHAN COMMAND
838 d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	89 33126 1 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	90 33127 33126 nobody 0.0 1380 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	91 33128 33126 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	92 33129 33126 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	93 </programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	94 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	95
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	96 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	97 If HUP is sent to the master process, the output becomes:
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	98 <programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	99 PID PPID USER %CPU VSZ WCHAN COMMAND
838 d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	100 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx
d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	101 33129 33126 nobody 0.0 1380 kqread nginx: worker process is shutting down (nginx)
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	102 33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	103 33135 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	104 33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	105 </programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	106 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	107
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	108 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	109 One of the old worker processes with PID 33129 still continues to work.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	110 After some time it exits:
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	111 <programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	112 PID PPID USER %CPU VSZ WCHAN COMMAND
838 d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	113 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	114 33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	115 33135 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	116 33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	117 </programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	118 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	119
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	120 </section>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	121
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	122
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	123 <section id="logs" name="Rotating Log-files">
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	124
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	125 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	126 In order to rotate log files, they need to be renamed first.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	127 After that USR1 signal should be sent to the master process.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	128 The master process will then re-open all currently open log files and
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	129 assign them an unprivileged user under which the worker processes
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	130 are running, as an owner.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	131 After successful re-opening, the master process closes all open files and
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	132 sends the message to worker process to ask them to re-open files.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	133 Worker processes also open new files and close old files right away.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	134 As a result, old files are almost immediately available for post
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	135 processing, such as compression.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	136 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	137
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	138 </section>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	139
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	140
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	141 <section id="upgrade" name="Upgrading Executable on the Fly">
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	142
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	143 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	144 In order to upgrade the server executable, the new executable file
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	145 should be put in place of an old file first.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	146 After that USR2 signal should be sent to the master process.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	147 The master process first renames its file with the process ID to a
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	148 new file with the <path>.oldbin</path> suffix, e.g.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	149 <path>/usr/local/nginx/logs/nginx.pid.oldbin</path>,
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	150 then starts a new executable file that in turn starts new
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	151 worker processes:
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	152 <programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	153 PID PPID USER %CPU VSZ WCHAN COMMAND
838 d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	154 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	155 33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	156 33135 33126 nobody 0.0 1380 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	157 33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
838 d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	158 36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	159 36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	160 36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	161 36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	162 </programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	163 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	164
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	165 <!--
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	166
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	167 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	168 The process 36264 with a new executable file creates its own file
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	169 with the <path>.newbin</path> suffix that will keep the process ID,
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	170 e.g. <path>/usr/local/nginx/logs/nginx.pid.newbin</path>.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	171 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	172
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	173 -->
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	174
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	175 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	176 After that all worker processes (old and new ones) continue to accept requests.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	177 If the WINCH signal is sent to the first master process, it will
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	178 send messages to its worker processes, requesting them to shut
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	179 down gracefully, and they will start to exit:
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	180 <programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	181 PID PPID USER %CPU VSZ WCHAN COMMAND
838 d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	182 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx
d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	183 33135 33126 nobody 0.0 1380 kqread nginx: worker process is shutting down (nginx)
d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	184 36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	185 36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	186 36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	187 36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	188 </programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	189 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	190
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	191 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	192 After some time, only the new worker processes will process requests:
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	193 <programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	194 PID PPID USER %CPU VSZ WCHAN COMMAND
838 d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	195 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx
d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	196 36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	197 36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	198 36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	199 36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	200 </programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	201 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	202
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	203 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	204 It should be noted that the old master process does not close its listen
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	205 sockets, and it can be managed to start its worker processes again if needed.
837 6678b1f27514 Improved readability of "Upgrading Executable on the Fly". Ruslan Ermilov <ru@nginx.com> parents: 625 diff changeset	206 If for some reason the new executable file works unacceptably, one of the
6678b1f27514 Improved readability of "Upgrading Executable on the Fly". Ruslan Ermilov <ru@nginx.com> parents: 625 diff changeset	207 following can be done:
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 288 diff changeset	208 <list type="bullet">
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	209
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	210 <listitem>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	211 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	212 Send the HUP signal to the old master process.
837 6678b1f27514 Improved readability of "Upgrading Executable on the Fly". Ruslan Ermilov <ru@nginx.com> parents: 625 diff changeset	213 The old master process will start new worker processes
6678b1f27514 Improved readability of "Upgrading Executable on the Fly". Ruslan Ermilov <ru@nginx.com> parents: 625 diff changeset	214 without re-reading the configuration.
6678b1f27514 Improved readability of "Upgrading Executable on the Fly". Ruslan Ermilov <ru@nginx.com> parents: 625 diff changeset	215 After that, all new processes can be shut down gracefully,
844 621d5dfcb4f4 Controlling nginx: fixed fallout from my rewrite of text. Ruslan Ermilov <ru@nginx.com> parents: 842 diff changeset	216 by sending the QUIT signal to the new master process.
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	217 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	218 </listitem>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	219
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	220 <listitem>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	221 <para>
837 6678b1f27514 Improved readability of "Upgrading Executable on the Fly". Ruslan Ermilov <ru@nginx.com> parents: 625 diff changeset	222 Send the TERM signal to the new master process.
6678b1f27514 Improved readability of "Upgrading Executable on the Fly". Ruslan Ermilov <ru@nginx.com> parents: 625 diff changeset	223 It will then send a message to its worker processes requesting them
6678b1f27514 Improved readability of "Upgrading Executable on the Fly". Ruslan Ermilov <ru@nginx.com> parents: 625 diff changeset	224 to exit immediately, and they will all exit almost immediately.
842 c9a425a3e4f5 Controlling nginx: be more precise about killing processes. Ruslan Ermilov <ru@nginx.com> parents: 838 diff changeset	225 (If new processes do not exit for some reason,
c9a425a3e4f5 Controlling nginx: be more precise about killing processes. Ruslan Ermilov <ru@nginx.com> parents: 838 diff changeset	226 the KILL signal should be sent to them to force them to exit.)
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	227 When the new master process exits, the old master process will start new
837 6678b1f27514 Improved readability of "Upgrading Executable on the Fly". Ruslan Ermilov <ru@nginx.com> parents: 625 diff changeset	228 worker processes automatically.
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	229 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	230 </listitem>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	231
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	232 </list>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	233
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	234 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	235
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	236 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	237 If the new master process exits then the old master process discards
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	238 the <path>.oldbin</path> suffix from the file name with the process ID.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	239 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	240
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	241 <para>
2194 a90594ae6686 Controlling nginx: unified English translation. Sergey Kandaurov <pluknet@nginx.com> parents: 1465 diff changeset	242 If upgrade was successful, then the QUIT signal should be sent to
a90594ae6686 Controlling nginx: unified English translation. Sergey Kandaurov <pluknet@nginx.com> parents: 1465 diff changeset	243 the old master process, and only new processes will stay:
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	244 <programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	245 PID PPID USER %CPU VSZ WCHAN COMMAND
838 d1b5814e5265 Controlling nginx: use "ps -w" in examples. Ruslan Ermilov <ru@nginx.com> parents: 837 diff changeset	246 36264 1 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx
186 abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	247 36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	248 36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	249 36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	250 </programlisting>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	251 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	252
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	253 <!--
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	254
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	255 <para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	256 To complete the upgrade process, the
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	257 <path>/usr/local/nginx/logs/nginx.pid.newbin</path> file should be renamed to
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	258 <path>/usr/local/nginx/logs/nginx.pid</path>.
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	259 </para>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	260
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	261 -->
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	262
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	263 </section>
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	264
abc48ad4b7c4 Translated the "Controlling nginx" article into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	265 </article>

Mercurial > hg > nginx-site

annotate xml/en/docs/control.xml @ 2677:3760176ba83e