Does nginx support atomic rollback of upstream configuration after reload

Direct Answer

nginx does not provide a built-in automatic rollback mechanism for upstream configuration changes after a reload. When you send a reload signal (SIGHUP), the master process validates the new configuration. If validation fails, the new worker processes are never started and the existing workers continue serving with the previous configuration — this is a passive safety net, not an active rollback. If validation succeeds but the new upstream definitions cause runtime problems (unreachable backends, routing errors), nginx will not revert automatically.

What Actually Happens During Reload

Graceful Worker Replacement

On successful reload, nginx starts new worker processes with the updated configuration while old workers continue processing in-flight requests. Old workers exit only after their connections complete or the worker_shutdown_timeout is reached. New connections immediately use the new configuration.

Upstream Group Changes

Adding, removing, or modifying servers within an upstream block, changing parameters (weights, max_fails, etc.), or renaming upstream groups are all handled via reload. If an upstream group referenced by active connections is removed or renamed, those connections continue on the old workers until they naturally terminate. The old group name remains in memory for the lifetime of those workers.

When Full Restart Is Required

A full stop/start cycle is only necessary for changes affecting the master process itself: user/group directives, master-level settings (pid file, worker_processes count), or certain SSL/TLS parameters requiring master reinitialization. Upstream definition changes never require a full restart.

Practical Rollback Strategy

Since nginx lacks transactional configuration swaps, implement rollback at the deployment layer:

1. Keep the previous configuration file versioned (git, config management, or timestamped backups)
2. Test syntax before reload: nginx -t
3. On reload failure, the old workers persist — restore the previous config file and reload again
4. On runtime failure after successful reload, detect via health checks (nginx Plus API, external monitoring) and manually restore the previous config + reload

Verification Steps

# Test configuration syntax
nginx -t

# Trigger reload
nginx -s reload

# Observe process transition
ps aux | grep nginx

# Check error log for validation failures
tail -f /var/log/nginx/error.log

Establish a long-lived connection (curl --no-buffer -N), trigger reload, and verify the connection completes on the old worker.

One Diagnostic Detail

What nginx version are you running? worker_shutdown_timeout behavior and reload semantics have evolved — run nginx -V to confirm your version's capabilities.