Skip to content

Testing and reloading

Scope: the two habits that make nginx safe to operate — test before you touch the running server, and reload instead of restarting.

nginx -t is not optional

nginx -t parses the entire configuration and reports, without starting or disturbing anything:

$ nginx -t
nginx: the configuration file /home/you/nginx-lab/nginx.conf syntax is ok
nginx: configuration file /home/you/nginx-lab/nginx.conf test is successful

And when it's not fine, it says where, in plain terms, and exits non-zero:

$ nginx -t -c broken.conf
2026/10/20 20:46:46 [emerg] ... unknown directive "limit_req_zone_broken" in .../broken.conf:28
nginx: configuration file .../broken.conf test failed
exit: 1

That pair of captures is the whole argument: the typo'd config was tested against a copy, the running server never saw it, and nobody's site went down. We caused that failure on purpose in two seconds; production supplies them for free if you skip the test.

The habit, for the system instance:

nginx -t && systemctl reload nginx

The && is the point: the reload runs only if the test passed. (A reload with a bad config is in fact refused by nginx itself and the old workers keep serving — but finding that out from your monitoring is worse than finding out from -t.)

Reload versus restart

A restart kills every worker and starts over: connections in flight die, and if the new config is bad you have no server at all until you fix it.

A reload (SIGHUP to the master, or nginx -s reload, or systemctl reload nginx) asks the master to re-read the config and roll the workers: new workers start on the new config, old workers finish their current requests and exit. From the lab, changing the config and the served page, then reloading:

$ master PID before: 13739
$ nginx -t && nginx -s reload
nginx: configuration file .../nginx.conf test is successful
$ master PID after: 13739
$ curl -s http://127.0.0.1:8080/
<!doctype html>
<h1>main root: index — edited, served after a reload</h1>

The master never moved; the content changed underneath it. (Watch ps during a reload and you may briefly see old and new workers side by side — that's the graceful handover, not a leak.)

nginx -s takes other signals worth knowing: reload (above), stop (immediate, drops connections), quit (graceful: workers finish, then the master exits). For the systemd-managed instance you'll use systemctl reload|restart|stop nginx, which send the same signals through the unit.

When a restart is actually required

Almost never for config. Changing the binary, or the user the workers run as, is about it — and changing the bind address of a listen is still just a reload. If you find yourself restarting nginx to make a config edit "take," the edit isn't in the loaded config; go back to chapter 3's nginx -T and find out which file is really in play.

Check: on a machine you administer, run nginx -t right now. It should say "test is successful." If it doesn't, you have learned something about that machine for free — and before it cost you anything.