NGINX’s New ‘worker_shutdown_timeout’ Directive
There’s a new patch level release (1.11.11) of NGINX, the popular open source Web server and load balancer, with the following changes:
*) Feature: the "worker_shutdown_timeout" directive.
*) Feature: vim syntax highlighting scripts improvements.*) Bugfix: a segmentation fault might occur in a worker process if the $limit_rate variable was set to an empty string.
*) Bugfix: the "proxy_cache_background_update", "fastcgi_cache_background_update", "scgi_cache_background_update" and "uwsgi_cache_background_update" directives might work incorrectly if the "if" directive was used.
*) Bugfix: a segmentation fault might occur in a worker process if number of large_client_header_buffers in a virtual server was different from the one in the default server.
*) Bugfix: in the mail proxy server.
The most interesting part to me is the first item — a new directive to play with! What does it do?
What worker_shutdown_timeout Actually Does
worker_shutdown_timeout is a top-most/main context config directive to specify a time limit for NGINX’s attempts to gracefully let worker processes terminate. Once the timeout has expired, NGINX will actively try to close the connections necessary for the processes to terminate.
For example, worker_shutdown_timeout 10s will mean NGINX gives worker processes 10 seconds to gracefully terminate before it will actively close connections.
NGINX’s Maxim Dounin explains further in this mailing list post:
The worker_shutdown_timeout directive is not expected to delay shutdown if there are no active connections. It was introduced to limit possible time spent in shutdown, that is, to ensure fast enough shutdown even if there are active connections.
When a worker process enters the ‘exiting’ state, it does a few things:
- Mark itself as an exiting process.
- Set a shutdown timer, iff
worker_shutdown_timeoutis defined. (New to 1.11.11) - Close listening sockets.
- Close idle connections.
- Then, if the shutdown timer was set, after the
worker_shutdown_timeoutinterval, all connections are closed.
This directive should come in useful if you want to tweak NGINX’s shutdown process, particularly if other servers or load balancers are relying upon predictable restart times.
Trivia:
worker_shutdown_timeoutshares its name with a similar directive in Puma, a high concurrency HTTP server for Ruby.
