Validate and Reload nginx Without Dropping Live Requests

You will check an nginx configuration, see which files nginx actually loads, and apply a valid change with a graceful reload. Existing workers continue serving current requests while new workers take 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 that a different nginx binary uses the same files.

2. Test before touching 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 and then tries to open files named by the configuration, including certificates, log files and included files. Exit status 0 means this 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.

Checkpoint: do not continue if this command reports an error. Read the first missing or invalid path, fix that configuration or file permission, and run the same test again. If you omit sudo, a private certificate can produce a misleading permission error even when the root-owned service can read it.

3. Inspect the effective configuration when includes are 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 read:

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

-T performs 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 when 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 belonging to your service. The example is illustrative and should not be copied 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

After 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 workers. A failed reload leaves the old configuration running, but you should still inspect the error log and correct the file rather than assuming the new behaviour is active.

Verify the service from a client that 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. Also check the application or upstream logs if the response is a 502 or 504. Those responses usually mean the nginx configuration loaded 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. It waits for workers to finish current requests.
• sudo nginx -s stop requests a fast shutdown. This can interrupt active requests, so treat it as a service-disrupting action.

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

Common traps

• Testing without elevation can fail to open a certificate or log that the master can read. Compare the unprivileged and sudo results before changing 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, not over nginx.conf.