Understanding and Performing a Smooth Upgrade of Nginx

1. Explanation of Nginx Smooth Upgrade

As Nginx becomes increasingly popular, its rapid version iteration (e.g., version 1.9.0 introduced the stream four‑layer proxy) demands frequent upgrades while keeping online services running, making smooth upgrade a key operation for administrators.

The principle of a smooth upgrade is simple:

Start a new master process without terminating the old one.

The old processes finish any in‑flight requests but stop accepting new ones.

The new processes accept new requests.

After the old processes have handled all pending requests and closed their connections, they exit.

Typically, an upgrade is needed either to move to a newer Nginx version or to add new modules.

2. Nginx Smooth Upgrade Mechanism

In multi‑process mode, Nginx runs a master process that loads the configuration and binds ports, then forks a configurable number of worker processes. These workers inherit the listening socket file descriptor and accept connections.

The master process stays idle after startup, waiting for system signals such as SIGCHLD, SIGHUP, and SIGUSR2.

Nginx Signal Overview

(1) Signals supported by the master process

TERM, INT – terminate immediately

QUIT – wait for workers to finish and then exit

KILL – forcefully kill the process

HUP – reload configuration and start new workers gradually

USR1 – reopen log files

USR2 – start a new master process for hot upgrade

WINCH – gradually shut down workers

(2) Signals supported by worker processes

TERM, INT – terminate immediately

QUIT – exit after completing current requests

USR1 – reopen log files

3. Performing a Smooth Upgrade

1. Download the new Nginx version:

wget http://www.nginx.org/download/nginx-1.19.6.tar.gz

tar -xvf nginx-1.19.6.tar.gz

2. Configure and compile the new version:

cd nginx-1.19.6

./configure

make

3. Backup the old binary and copy the new one:

mv /usr/local/nginx/sbin/nginx /usr/local/nginx/sbin/nginx.old

cp nginx-1.19.6/objs/nginx /usr/local/nginx/sbin/

4. Restart Nginx:

nginx -t

kill -USR2 $(cat /usr/local/nginx/logs/nginx.pid)

kill -QUIT $(cat /usr/local/nginx/logs/nginx.oldbin)

nginx -V

These commands start a new master process, transfer new connections to it, and gracefully shut down the old master after it has completed all pending requests.