Glossary

Project-specific vocabulary that recurs across the codebase. Where a term has both an everyday meaning and a nginx-specific meaning, the entry covers the latter.

Term	Definition
cycle	The big "world" object: the parsed configuration, the listening sockets, the connection table, the modules array, the shared-memory zones. Type ngx_cycle_t in src/core/ngx_cycle.h. A reload creates a new cycle from the old one.
module	A static struct (ngx_module_t) that registers config directives, type-specific hooks, and process-lifecycle callbacks. Every feature is a module. See primitives/module.
directive	A line in nginx.conf like worker_processes auto;. Each is matched by a ngx_command_t entry inside a module's commands table.
block / context	A { ... } section in nginx.conf. Top-level is main; common nested contexts are events, http, server, location, upstream, mail, stream. Directives declare which contexts they're valid in via flags like NGX_HTTP_SRV_CONF.
phase	One of 11 stages in the HTTP request engine (POST_READ, SERVER_REWRITE, FIND_CONFIG, REWRITE, POST_REWRITE, PREACCESS, ACCESS, POST_ACCESS, PRECONTENT, CONTENT, LOG). Modules attach phase handlers; nginx walks them in order.
handler	A function that produces a response body for a request. Set on a location (ngx_http_static_module, ngx_http_proxy_module, etc.). Distinct from a phase handler, which is a hook called during request processing.
filter	A function in the output filter chain (header or body). Filters wrap each other to form a pipeline: SSI → range → gzip → chunked → header → write. See ngx_http_top_header_filter, ngx_http_top_body_filter.
subrequest	An internal request spawned from a parent request. Used by SSI, add_after_body, auth_request, mirror. Subrequests share the parent's connection but have their own ngx_http_request_t.
upstream	A backend that nginx proxies to. Either declared by an upstream { server ...; } block (for load balancing) or implicit in a proxy_pass http://host;. Code in src/http/ngx_http_upstream.c.
pool	A bump-allocator (ngx_pool_t). Memory allocated from a pool is freed all at once when the pool is destroyed. There's a per-cycle pool, a per-connection pool, a per-request pool, and many short-lived pools.
slab	A fixed-size class allocator over a shared-memory zone. Used for caches that need to survive between worker processes. Code in src/core/ngx_slab.c.
shared zone	A named mmap-backed memory region created via ngx_shared_memory_add() and shared across all workers. Used by limit_req, limit_conn, upstream zone, SSL session cache.
buf / chain	ngx_buf_t is a span of bytes plus metadata (in-memory? file-backed? last in request? flush?). ngx_chain_t is a linked-list link of buffers. Output filters work on chains.
event	An ngx_event_t. Has a handler function pointer, a timer node, ready/active/pending flags. Lives inside a ngx_connection_t (read, write).
posted event	An event scheduled to run after the current event handler returns (via ngx_post_event). Lets modules avoid stack reentrancy. Two queues: ngx_posted_events, ngx_posted_next_events.
listening socket	An ngx_listening_t. Bound and listen()'d in the master, inherited by workers. Reload preserves them so connections aren't dropped.
master / worker	The two main nginx process types. The master forks workers and watches signals; workers handle traffic. There may also be cache manager and cache loader processes.
graceful shutdown	A worker stops accept()ing new connections, finishes in-flight requests, then exits. Triggered by SIGQUIT (nginx -s quit) or by reload.
binary upgrade	Replacing the running nginx with a newer binary by sending SIGUSR2 to the master. The old master forks the new one, the new master forks new workers, traffic shifts; SIGQUIT to the old master then drains the old workers. See ngx_exec_new_binary.
mainline	The active development branch. The master branch in this repo is mainline. Stable branches live elsewhere and only get backported fixes.
NGX_OK / NGX_ERROR / NGX_AGAIN / NGX_DECLINED / NGX_DONE	Return codes used everywhere. NGX_AGAIN means "would block, call me again later"; NGX_DECLINED means "I don't handle this, try the next module"; NGX_DONE means "the request is finalized, don't do anything else".
ngx_str_t	NGINX's string type: { size_t len; u_char *data; }. Not null-terminated. Macros: ngx_string("..."), ngx_str_set, ngx_str_null. Beware: data is u_char *, not char *.
ngx_array_t	A growable array ({ elts, nelts, size, nalloc, pool }). Used everywhere a small dynamic list is needed. Doubles in size on grow.
ngx_list_t	An ngx_array_t-of-arrays. Used for HTTP request headers because adding a header should not invalidate previously taken pointers.
ngx_queue_t	An intrusive doubly-linked list. Embed ngx_queue_t q; inside a struct, use ngx_queue_data() to recover the enclosing pointer.
ngx_rbtree_t	A self-balancing red-black tree. Used by the timer wheel (ngx_event_timer_rbtree), file cache, OCSP cache, SSL session cache, and plenty more.
ngx_radix_tree_t	A bitwise radix tree, indexed on IPv4/IPv6 prefixes. Backs geo and realip.
ngx_hash_t	A read-only hash table built once at config time. Variants: ngx_hash_t, ngx_hash_combined_t (for wildcard hosts), ngx_hash_keys_arrays_t (for building one).
variable	A $name placeholder that expands in directives like proxy_pass or log_format. Implemented by ngx_http_variable_t (HTTP) / ngx_stream_variable_t. See src/http/ngx_http_variables.c.
complex value	A precompiled directive argument that can contain variables. Built by ngx_http_compile_complex_value, evaluated per request by ngx_http_complex_value.
script	Compiled instructions for evaluating variables, rewrite rules, or complex values. Code in src/http/ngx_http_script.c.
ABT	"ABT" abbreviates ngx_abort_* and similar — not a project term, just a naming convention. Mentioned here only because the abbreviation appears occasionally in diagnostics.
NGX_DEBUG / debug log	A log level only emitted when nginx is built with --with-debug and the user sets error_log ... debug;. Massive output; useful when tracing one request.
dynamic module	A module compiled as a .so with --add-dynamic-module=... and loaded at runtime via load_module. Same struct, different lifecycle.
PROXY protocol	A small header (v1 text or v2 binary) that an upstream load balancer prepends to a TCP connection so nginx knows the original client IP. Implemented in src/core/ngx_proxy_protocol.c.
HPACK / QPACK	The header compression formats for HTTP/2 and HTTP/3. nginx ships its own implementations in src/http/v2/ngx_http_v2_table.c and src/http/v3/ngx_http_v3_table.c.
QUIC	The UDP-based transport that HTTP/3 runs on. nginx implements it from scratch in src/event/quic/. The key entry point is ngx_event_quic_run().
OCSP stapling	Caching and serving an OCSP response from inside the TLS handshake so clients don't have to query the CA. Implementation: src/event/ngx_event_openssl_stapling.c.
session ticket	A piece of TLS state encrypted with a server key, returned to the client, and replayed on the next connection to skip the handshake. Code in ngx_ssl_session_ticket_keys() (src/event/ngx_event_openssl.c).