Configuration reference

This page is a navigational map, not a complete directive list (the canonical reference is at nginx.org/en/docs/dirindex.html). It lists the places where each kind of configuration lives in the source.

Build-time flags (auto/configure)

Defined in auto/options. Run ./auto/configure --help (after a configure pass) for the full list, or read the file directly.

Compilation

Flag	Effect
--prefix=PATH	Install prefix (default /usr/local/nginx)
--sbin-path=PATH	Where the binary goes
--conf-path=PATH	Where nginx.conf goes
--pid-path=PATH	PID file path
--error-log-path=PATH	Default error log path
--http-log-path=PATH	Default access log path
--build=NAME	String returned by nginx -V as the build name
--with-debug	Enable error_log debug; and ngx_log_debug* macros
--with-cc=PATH	Compiler binary
--with-cc-opt='...'	Extra CFLAGS
--with-ld-opt='...'	Extra LDFLAGS

Bundled HTTP modules

Flag	Module
--with-http_ssl_module	TLS for HTTP
--with-http_v2_module	HTTP/2
--with-http_v3_module	HTTP/3 (requires --with-http_ssl_module)
--with-http_realip_module	Replace $remote_addr from a header
--with-http_addition_module	add_after_body, add_before_body
--with-http_xslt_module	XSLT response filtering (requires libxslt)
--with-http_image_filter_module	Image resizing (requires libgd)
--with-http_geoip_module	MaxMind GeoIP
--with-http_sub_module	String-substitution filter
--with-http_dav_module	WebDAV
--with-http_flv_module	Flash pseudo-streaming
--with-http_mp4_module	MP4 pseudo-streaming
--with-http_gunzip_module	Decompress upstream gzip
--with-http_gzip_static_module	Serve precomputed .gz
--with-http_auth_request_module	Subrequest-based auth
--with-http_random_index_module	Random file from a directory
--with-http_secure_link_module	Signed URL links
--with-http_degradation_module	Memory-pressure 204
--with-http_slice_module	Byte-range slicing for caching
--with-http_stub_status_module	The /nginx_status endpoint
--with-http_perl_module[=dynamic]	Perl handlers

Other subsystems

Flag	Effect
--with-mail	Build the mail proxy modules
--with-mail_ssl_module	Mail TLS
--with-stream	Build the stream (L4) proxy
--with-stream_ssl_module	Stream TLS
--with-stream_realip_module	Stream realip from PROXY protocol
--with-stream_geoip_module	Stream GeoIP
--with-stream_ssl_preread_module	TLS preread (SNI peeking)
--with-threads	Enable the thread pool
--with-file-aio	Enable aio (Linux/FreeBSD/POSIX AIO)
--with-poll_module	Force include poll
--with-select_module	Force include select
--without-poll_module, etc.	Exclude default modules
--with-pcre[=DIR]	PCRE library (path optional)
--with-pcre-jit	PCRE JIT
--with-zlib=DIR	Bundled zlib
--with-openssl=DIR	Bundled OpenSSL
--with-libatomic[=DIR]	Use libatomic_ops
--add-module=PATH	Add a third-party static module
--add-dynamic-module=PATH	Add a third-party dynamic module

Runtime directives — context map

Directives are valid in specific contexts (main, events, http, server, location, upstream, if-in-location, mail, server (mail), stream, server (stream), upstream (stream)). Each module's commands[] table specifies via the type flags.

The most useful trick when looking at a directive: grep for it in src/. For proxy_pass:

$ grep -rn "ngx_string(\"proxy_pass\")" src/
src/http/modules/ngx_http_proxy_module.c:435: { ngx_string("proxy_pass"),
src/stream/ngx_stream_proxy_module.c: ...

Each result is the directive's entry in a commands[] table; the file tells you which module owns it; the next struct fields tell you the contexts it's valid in and the setter that handles it.

Default configuration

conf/nginx.conf (~70 lines):

worker_processes  1;
events {
    worker_connections  1024;
}
http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    server {
        listen       80;
        server_name  localhost;
        location / {
            root   html;
            index  index.html index.htm;
        }
        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   html;
        }
    }
}

This is the file make install puts at <prefix>/conf/nginx.conf.

Other shipped config files

File	Purpose
conf/mime.types	Extension → MIME type table
conf/fastcgi.conf	Standard FastCGI parameter setup (fastcgi_param ...)
conf/fastcgi_params	Same, slightly older form
conf/scgi_params	SCGI variant
conf/uwsgi_params	uwsgi variant
conf/koi-utf	KOI8-R ↔ UTF-8 charset map (used by charset filter)
conf/koi-win	KOI8-R ↔ CP1251 charset map
conf/win-utf	CP1251 ↔ UTF-8 charset map

CLI flags (parsed in src/core/nginx.c)

Flag	Effect
-?, -h	Help
-v	Print version
-V	Print version + configure args
-t	Test config and exit
-T	Test config; dump it to stdout
-q	Suppress non-error messages during config testing
-s SIGNAL	Send a signal to the running master (stop, quit, reload, reopen)
-p PREFIX	Set the prefix path
-e PATH	Override error_log path
-c PATH	Use a different config file
-g DIRECTIVES	Inject directives into the main context (e.g., -g 'daemon off;')

Signals (handled in src/os/unix/ngx_process.c)

See systems/process-model for the full handler logic.

Signal	Effect
SIGTERM, SIGINT	Immediate shutdown
SIGQUIT	Graceful shutdown
SIGHUP	Reconfigure (build a new cycle, hand off to new workers)
SIGUSR1	Reopen log files (nginx -s reopen)
SIGUSR2	Begin binary upgrade (exec new master)
SIGWINCH	Tell workers to stop accepting (during graceful binary upgrade)
SIGCHLD	Reap dead workers