Reload nginx Without Dropping Live Requests

A typo in an nginx config is harmless until someone reloads it straight into production, so this walkthrough checks first and reloads last. Existing workers keep serving current requests while new workers pick up the new configuration. Allow 15 minutes for a small change, plus time to test the endpoint behind it.

You need shell access, a readable nginx configuration, and a way to test the affected URL. Editing /etc/nginx, reading private keys, and signalling a root-owned master normally require sudo. The commands below target the installed Ubuntu package, nginx 1.24.0.

1. Find the executable and configuration paths

Start by confirming which binary will run and which configuration it was built to use:

$ command -v nginx
/usr/sbin/nginx
$ nginx -v
nginx version: nginx/1.24.0 (Ubuntu)
$ nginx -V 2>&1 | grep -- '--conf-path\|--pid-path'
configure arguments: ... --conf-path=/etc/nginx/nginx.conf ... --pid-path=/run/nginx.pid ...

The version output can include a longer build line on your machine. The useful facts are the executable, the main configuration path and the PID path. Do not assume a different nginx binary elsewhere uses the same files.

2. Test before you touch the running service

Run the syntax and file-open check before every reload:

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

-t does not run nginx. It checks syntax, then tries to open every file the configuration names, including certificates, log files and included files. Exit status 0 means the check passed, status 1 means it failed. A successful syntax check is not an HTTP health check, so request the changed endpoint separately after reloading.

3. Inspect the effective configuration when includes get confusing

nginx commonly builds its configuration from an include tree. Use -T when you need both the test and a dump of the files nginx actually read:

$ sudo nginx -T > /tmp/nginx-effective.conf
$ grep -n 'server_name\|listen\|proxy_pass' /tmp/nginx-effective.conf

-T runs the same test as -t and additionally writes the configuration to standard output. Treat that dump as sensitive operational material, it can reveal internal hostnames, upstream addresses and filesystem paths. Remove the temporary file once you have finished reviewing it:

$ rm -- /tmp/nginx-effective.conf

Do not paste a whole production dump into a public issue. A focused excerpt is usually enough to locate an unexpected server block or an include loaded twice.

4. Make one small configuration change

Edit the specific file that owns the relevant server or location block. nginx's configuration is hierarchical: events and http belong in the main context, server belongs inside http, and location belongs inside server. A proxy location might look like this:

server {
    listen 80;
    server_name example.test;

    location / {
        proxy_pass http://127.0.0.1:8080;
    }
}

Replace example.test and 127.0.0.1:8080 with values that belong to your service. Do not copy the example straight into a live site without checking its port, host name, TLS requirements and access policy. Save a backup or use your normal version control before editing. If the change is wrong, restore the previous file, run sudo nginx -t, and only then reload.

5. Reload gracefully

Once the test passes, ask the master process to reload:

$ sudo nginx -s reload

The reload signal is SIGHUP. nginx checks the new configuration, starts new workers if it can apply it, and gracefully retires the old ones. A failed reload leaves the old configuration running, but inspect the error log and fix the file anyway rather than assuming the new behaviour is live.

Verify the service from a client that actually exercises the changed route:

$ curl --fail --silent --show-error --resolve example.test:80:127.0.0.1 http://example.test/health
ok

Use an appropriate HTTPS URL and port for a TLS virtual host. Check the application or upstream logs too if the response comes back 502 or 504, that usually means the nginx configuration loaded fine but the upstream is unavailable or rejected the connection.

6. Know the other control signals

Use the narrowest action that matches the job:

• sudo nginx -s reopen asks nginx to reopen log files, normally after they have been rotated.
• sudo nginx -s quit requests a graceful shutdown, waiting for workers to finish current requests.
• sudo nginx -s stop requests a fast shutdown. This can interrupt active requests, treat it as service-disrupting.

Do not use stop as a substitute for reload. If you send the wrong signal, start nginx through your distribution's service manager, then test the configuration before making further changes. Avoid killing individual workers unless you are diagnosing a specific incident.

Common traps

• Testing without elevation fails to open a certificate or log that the master can read fine. Compare the unprivileged and sudo results before you change permissions.
• Editing a file that is not included has no effect. Use sudo nginx -T to identify the loaded path.
• A valid nginx configuration can still point at a dead application. Test the real URL, not just the exit status of nginx -t.
• Shell redirection overwrites its destination before the command runs. Keep effective configuration dumps in a disposable path such as /tmp, never over nginx.conf.