NGINX’s New ‘worker_shutdown_timeout’ Directive

Peter Cooper
Mar 22, 2017 · 2 min read

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:

When a worker process enters the ‘exiting’ state, it does a few things:

  1. Mark itself as an exiting process.
  2. Set a shutdown timer, iff worker_shutdown_timeout is defined. (New to 1.11.11)
  3. Close listening sockets.
  4. Close idle connections.
  5. Then, if the shutdown timer was set, after the worker_shutdown_timeout interval, 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.



Keeping developers informed.

Peter Cooper

Written by

Friendly chief publisher at @CooperPress, programmer, editor of JavaScript Weekly and more.


Keeping developers informed.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade