Starting and testing configuration 14
Default paths depend on the build: nginx -h from the nginx.org Linux package shows /etc/nginx/nginx.conf and /var/log/nginx/error.log, while the documentation describes a source build under /usr/local/nginx.
| Command | What it does |
|---|---|
nginx | Start nginxRun with no parameters, the executable starts a master process that reads the configuration and maintains the workers. |
nginx -t | Test the configurationChecks the syntax and tries to open the files the configuration refers to, then exits; run it before every reload. |
nginx -T | Test and dump the configurationRuns the same test as -t and also writes the configuration files to standard output; added in 1.9.2. |
nginx -q | Suppress non-error test outputMeant to be combined with -t: the informational lines of the check are hidden and only errors appear. |
nginx -c FILE | Use another configuration fileReplaces the built-in default, which is /etc/nginx/nginx.conf in the nginx.org Linux packages. |
nginx -p PREFIX | Set the path prefixPREFIX is the directory holding the server files; a source build defaults to /usr/local/nginx. |
nginx -e FILE | Use another error logAvailable since 1.19.5; the special value stderr sends the log to standard error. |
nginx -g DIRECTIVES | Set global directives inlineThe directives are given as one quoted string and apply at the main level, outside the configuration file. |
nginx -g "pid /var/run/nginx.pid; worker_processes `sysctl -n hw.ncpu`;" | Set pid file and workers inlineThe example printed in the reference: two main-level directives in one string, the worker count taken from a sysctl call. |
nginx -l PORT | Enable the control API on a portOpen-source nginx has the control REST API from 1.31.5; from 1.29.8 until then it needed a commercial subscription. |
nginx -l unix:SOCKET | Enable the control API on a socketBinds the control REST API to a UNIX-domain socket rather than a network port. |
curl -I 127.0.0.1 | Check that nginx respondsA quick check, run on the server itself, that a freshly started nginx is answering. |
service nginx stop | Stop the packaged serviceFirst of the two commands that switch a Linux package installation over to the nginx-debug binary. |
service nginx-debug start | Start the debug binaryLinux packages ship nginx-debug since 1.9.8 with debugging-log support; set error_log to the debug level afterwards. |
Reloading and stopping 5
| Command | What it does |
|---|---|
nginx -s SIGNAL | Send a signal to the masterSIGNAL is stop, quit, reload or reopen; run it as the same user that started nginx. |
nginx -s reload | Reload configThe master checks the new configuration, starts new workers and lets the old ones finish their current requests. |
nginx -s quit | Graceful stopWorker processes finish serving their current requests before nginx exits. |
nginx -s stop | Stop serverFast shutdown: nginx exits at once instead of waiting for requests in progress. |
ps -ax | grep nginx | List running nginx processesShows the master and worker processes with their IDs; signals are addressed to the master. |
Signals to the master and worker processes 10
Signal rows show the name as nginx.org prints it; send it to the master's process ID with kill, as in kill -s QUIT PID. USR1, USR2 and WINCH for the master are listed under Upgrading the binary and rotating logs.
| Command | What it does |
|---|---|
kill -s QUIT PID | Send a signal with killPID is the master process ID, which nginx writes to its nginx.pid file; this example shuts down gracefully. |
TERM, INT | Fast shutdownThe master tells its workers to exit at once; nginx -s stop requests the same thing. |
QUIT | Graceful shutdownWorkers finish the requests they are serving before nginx exits; nginx -s quit is the matching switch. |
HUP | Reload the configurationThe master validates and applies the new configuration, starts fresh workers and retires the old ones; on failure it keeps the old configuration. |
/bin/kill -s HUP $(/bin/cat /run/nginx.pid) | Reload as the systemd unit doesExecReload command of nginx.service in the nginx.org Linux packages: reloading the service sends HUP to the master. |
/bin/kill -s TERM $(/bin/cat /run/nginx.pid) | Stop as the systemd unit doesExecStop command of the packaged nginx.service, so stopping the service is the fast shutdown rather than QUIT. |
TERM, INT | Fast shutdown of one workerAddressed to a worker's own process ID; the reference notes that signalling workers directly is not required. |
QUIT | Graceful shutdown of one workerOnly that worker stops, after it has served its current clients. |
USR1 | Reopen logs in one workerMakes that single worker open the new log files and close the old ones. |
WINCH | Abort a worker for debuggingTerminates the worker abnormally and works only when the debug_points directive is enabled. |
Upgrading the binary and rotating logs 9
| Command | What it does |
|---|---|
USR2 | Start the upgraded executablePut the new binary in place first; the old master renames its pid file to nginx.pid.oldbin and launches the new one. |
WINCH | Retire the old workers gracefullySent to the old master during an upgrade; it stays alive with its listen sockets open in case a rollback is needed. |
QUIT | Finish the upgradeAddressed to the old master, whose ID is in the .oldbin pid file; it exits and the new binary runs alone. |
HUP | Roll back: revive the old workersUse when the new binary misbehaves, then send QUIT to the new master so its processes exit gracefully. |
TERM | Roll back: stop the new masterOnce the new master is gone, the old one starts workers again by itself and drops the .oldbin suffix. |
KILL | Force stuck new processes to exitLast resort in a rollback, for processes of the new binary that survive the TERM sent to their master. |
USR1 | Reopen log files after renamingThe master reopens every log and tells the workers to follow, so the renamed files can be compressed almost immediately. |
nginx -s reopen | Reopen log files with nginx -sDoes what USR1 does without looking up the master's process ID. |
kill -USR1 `cat /run/nginx.pid` | Reopen logs as logrotate doespostrotate step of the logrotate file in the nginx.org Linux packages, which rotates /var/log/nginx/*.log daily. |
Help, version and build information 5
| Command | What it does |
|---|---|
nginx -v | Print the nginx versionPrints a single line such as nginx version: nginx/1.31.6 and exits. |
nginx -V | Print version and build optionsAdds the compiler version and every configure argument, which shows built-in paths and options such as --with-debug. |
nginx -h | Show command-line helpSame as -?; the option list also prints the compiled-in defaults for the prefix, error log and configuration file. |
nginx -V 2>&1 | awk -F: '/configure arguments/ {print $2}' | xargs -n1 | List configure arguments line by lineLook for --conf-path, --error-log-path and --http-log-path to locate the configuration file and both logs. |
./configure --with-debug ... | Build with debugging-log supportNeeded only for source builds: Linux packages include an nginx-debug binary and the Windows build always has it. |
Windows 3
nginx/Windows runs as a console application, not a service, and is managed with the same nginx -s stop, quit, reload and reopen commands as on UNIX.
| Command | What it does |
|---|---|
start nginx | Start nginx on WindowsRun it inside the unpacked distribution directory, which becomes the prefix for relative paths in the configuration. |
tasklist /fi "imagename eq nginx.exe" | List nginx processes on WindowsNormally shows two nginx.exe entries, the master and a worker; if none appear, read logs\error.log. |
root C:/web/html; | Write Windows paths with forward slashesConfiguration paths on Windows use the UNIX style, and a relative one such as logs/site.log starts from the prefix directory. |
Core configuration directives 24
A small selection: each row is the syntax line of the nginx.org directive reference with placeholders in capitals. The reference adds the default value, the allowed context and the full description.
| Command | What it does |
|---|---|
worker_processes NUMBER | auto; | Set the number of workersMain context, default 1; auto tries to detect the number of CPU cores. |
worker_connections NUMBER; | Limit connections per workerBelongs in the events block; the count includes connections to proxied servers, not only clients. |
error_log FILE [LEVEL] [json]; | Set the error log and levelLevels run from debug to emerg and default to error; FILE can also be stderr, syslog: or memory:. |
error_log /path/to/log debug; | Turn on the debugging logHas an effect only when nginx -V shows --with-debug, or with the nginx-debug binary of the Linux packages. |
error_log memory:32m debug; | Log debug output to memoryUses a cyclic buffer of the given size, which costs little even under high load; read it out with gdb or lldb. |
pid FILE; | Set the pid fileStores the master process ID that kill needs; the default is logs/nginx.pid. |
include FILE | MASK; | Include other configuration filesAllowed in any context; a mask such as vhosts/*.conf pulls in every matching file. |
user USER [GROUP]; | Set the worker user and groupWithout GROUP, the group whose name equals USER is used; the built-in default is nobody. |
server { ... } | Define a virtual serverGoes inside http; its listen and server_name directives decide which requests the block receives. |
listen ADDRESS[:PORT] [default_server] [ssl] | Set the listening address and portWith only an address the port is 80; the full syntax has many more options, such as reuseport and backlog. |
server_name NAME ...; | Set the server namesThe first name is the primary one; an asterisk may replace the first or last part of a name. |
root PATH; | Set the document rootThe request URI is appended to PATH to build the file path; use alias when the URI has to change. |
location [ = | ~ | ~* | ^~ ] URI { ... } | Match requests by URI= is an exact match, ~ and ~* are case-sensitive and case-insensitive regular expressions, and ^~ skips the regular-expression check. |
location @NAME { ... } | Define a named locationNever used for ordinary requests; it is a target for redirection, for example from try_files or error_page. |
try_files FILE ... URI; | Serve the first existing fileFiles are checked in order; when none exists, nginx redirects internally to the last parameter, a URI or a named location. |
try_files FILE ... =CODE; | Fall back to a status codeWhen none of the files exists the request ends with that code, for example =404. |
error_page CODE ... [=[RESPONSE]] URI; | Set a custom error pageRedirects internally to URI for the listed codes; =RESPONSE changes the status code that is sent. |
client_max_body_size SIZE; | Limit the request body sizeDefault 1m; a larger body gets error 413, and 0 turns the check off. |
return CODE [TEXT]; | Return a status codeEnds processing with CODE and an optional body; 444 closes the connection without any response header. |
return CODE URL; | Redirect to a URLFor codes 301, 302, 303, 307 and 308 the second parameter is the redirect target. |
proxy_pass URL; | Proxy requests to a backendURL is http or https plus an address; when it carries a URI, that replaces the part matching the location. |
proxy_set_header FIELD VALUE; | Set a header for the backendInherited from the level above only when the current level defines none; Host and Connection are set by default. |
access_log PATH [FORMAT [buffer=SIZE] [gzip[=LEVEL]] [flush=TIME] [if=CONDITION]]; | Set the access logDefault is logs/access.log in the combined format; with buffer or gzip, writes are buffered. |
access_log off; | Turn off access loggingCancels every access_log directive on the current level. |
No row on this page matches that filter.
Notes
Test first, then reload
nginx -t checks the configuration for correct syntax and tries to open the files it refers to; running it before every reload turns a typo into an error message on the terminal. A reload with a broken configuration is not fatal either: the master process rolls the change back and keeps working with the old configuration. nginx -T runs the same test and also dumps the configuration files to standard output, which shows exactly what nginx reads. nginx -s reload then applies the change: the master process starts new workers with the new configuration and the old ones finish their current requests before they exit.
Stopping gracefully versus now
nginx -s quit and the QUIT signal stop nginx gracefully, letting workers finish the requests they are serving. nginx -s stop and TERM, INT are the fast shutdown. Signals go to the master process, whose ID is written to the nginx.pid file, for example kill -s QUIT PID. The systemd unit in the nginx.org Linux packages reloads with HUP and stops with TERM, so stopping that service is the fast shutdown. WINCH gracefully shuts down only the workers, which is used during binary upgrades together with USR2, the signal that starts a new master from an upgraded executable while the old one keeps running. USR1 reopens the log files after they have been renamed; the packaged logrotate file sends it.
Finding paths and build options
nginx -h prints the defaults compiled into the binary: the prefix, the error log and the configuration file, which is /etc/nginx/nginx.conf in the nginx.org Linux packages. nginx -V (capital V) lists the configure arguments, which settles whether --with-debug or another build option is present, and nginx -V 2>&1 | awk -F: '/configure arguments/ {print $2}' | xargs -n1 prints them one per line so that --conf-path, --error-log-path and --http-log-path are easy to read. ps -ax | grep nginx lists the master and worker processes when a signal has to be sent by hand.
Questions
Does nginx -s reload drop connections?
No. The master process starts new workers with the new configuration and asks the old ones to shut down; they stop accepting new connections and keep serving current requests until those are finished.
Why did my reload silently do nothing?
If the new configuration fails the syntax check or cannot be applied, the master process rolls the change back and continues with the old configuration. Run nginx -t yourself to see the message.
How do I find which config file nginx is using?
nginx -h shows the compiled-in default next to -c, and the --conf-path value in the output of nginx -V is the same path. A server started with nginx -c FILE reads FILE instead, and nginx -T dumps the configuration files it finds.
Which signal do I use after log rotation?
USR1 to the master process, or nginx -s reopen. The logrotate file in the nginx.org Linux packages already runs kill -USR1 `cat /run/nginx.pid` after rotating /var/log/nginx/*.log.
What does the packaged systemd unit send when the nginx service is reloaded or stopped?
In the nginx.org Linux packages nginx.service reloads with /bin/kill -s HUP $(/bin/cat /run/nginx.pid) and stops with /bin/kill -s TERM $(/bin/cat /run/nginx.pid), so a service stop is the fast shutdown, not the graceful QUIT.
Sources and checks
- nginx.org documentation: Command-line parameters The parameters of the nginx executable, with the version that introduced each
- nginx.org documentation: Controlling nginx Signals of the master and worker processes, configuration reload, log rotation and upgrading the executable on the fly
- nginx.org documentation: Beginner's Guide Starting nginx, nginx -s stop, quit, reload and reopen, sending a signal with kill, listing processes with ps
- nginx.org documentation: nginx for Windows (mainline 1.31.6) Starting nginx on Windows, tasklist, path style in the configuration
- nginx.org documentation: A debugging log Building with --with-debug, the nginx-debug binary of the Linux packages, error_log at the debug level
- nginx 1.31.6 built-in help: output of nginx -h and nginx -v from the official nginx.org Linux package (mainline, Ubuntu 24.04, amd64) Usage line, every command-line option and the compiled-in default paths
7 more source pages
- nginx.service and logrotate file shipped in the official nginx.org Linux package 1.31.6 (mainline, Ubuntu 24.04, amd64) The kill commands the packaged systemd unit and logrotate configuration run
- F5 NGINX documentation: Installing NGINX Open Source
- nginx.org directive reference: Core functionality (ngx_core_module) Syntax of worker_processes, worker_connections, error_log, pid, include and user
- nginx.org directive reference: ngx_http_core_module Syntax of server, listen, server_name, root, location, try_files, error_page and client_max_body_size
- nginx.org directive reference: ngx_http_proxy_module Syntax of proxy_pass and proxy_set_header
- nginx.org directive reference: ngx_http_log_module Syntax of access_log
- nginx.org directive reference: ngx_http_rewrite_module Syntax of return
Every row on this page was matched to a line in the documentation above on . A binding that could not be found there is not listed.
4 rows from the earlier version of this page were removed in that check: duplicates, and bindings the documentation does not list or lists differently.
Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.