Mercurial > hg > nginx-site

comparison xml/en/docs/control.xml @ 186:abc48ad4b7c4

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