Mercurial > hg > nginx-site
comparison xml/en/docs/control.xml @ 186:abc48ad4b7c4
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> |