1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
|
=encoding utf-8
=head1 Name
control - Controlling nginx
=head1
nginx can be controlled with signals.
The process ID of the master process is written to the file
F<E<sol>usrE<sol>localE<sol>nginxE<sol>logsE<sol>nginx.pid> by default.
This name may be changed at configuration time, or in
F<nginx.conf> using the
L<ngx_core_module>
directive.
The master process supports the following signals:
B<NOTE>
TERM, INT fast shutdown
QUIT graceful shutdown
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:
B<NOTE>
TERM, INT fast shutdown
QUIT graceful shutdown
USR1 re-opening log files
=head1 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.
Let’s illustrate this by example.
Imagine that nginx is run on FreeBSD and the command
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:
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 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)
=head1 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.
=head1 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 F<.oldbin> suffix, e.g.
F<E<sol>usrE<sol>localE<sol>nginxE<sol>logsE<sol>nginx.pid.oldbin>,
then starts a new executable file that in turn starts new
worker processes:
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:
=over
=item *
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.
=item *
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.
=back
If the new master process exits then the old master process discards
the F<.oldbin> suffix from the file name with the process ID.
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)
|
