Bundled HTTP modules

Active contributors: Sergey Kandaurov, Maxim Dounin, Roman Arutyunyan

Purpose

src/http/modules/ ships ~60 modules that hook into the HTTP request engine to provide everything from authentication and rate limiting to gzip, image processing, and FastCGI. Each is an independent ngx_module_t of type NGX_HTTP_MODULE. They are individually opt-in/out at build time via auto/configure flags (see tooling).

Module groups

Content handlers (assigned to r->content_handler per location)

Module	Directive trigger	Purpose
ngx_http_static_module	(default)	Serve files from disk
ngx_http_index_module	index	Pick index.html etc. for directory requests
ngx_http_autoindex_module	autoindex on;	Generate directory listings
ngx_http_random_index_module	random_index on;	Serve a random file from a directory
ngx_http_dav_module	dav_methods	WebDAV (PUT, MKCOL, COPY, MOVE, DELETE)
ngx_http_empty_gif_module	empty_gif;	1×1 transparent GIF — for tracking pixels
ngx_http_stub_status_module	stub_status;	The /nginx_status health endpoint
ngx_http_flv_module	flv;	Pseudo-streaming Flash video
ngx_http_mp4_module	mp4;	Pseudo-streaming MP4 with ?start= seek
ngx_http_proxy_module	proxy_pass	HTTP reverse proxy (see upstream)
ngx_http_proxy_v2_module	proxy_protocol_v2;	PROXY-protocol-aware variant
ngx_http_fastcgi_module	fastcgi_pass	FastCGI proxy
ngx_http_uwsgi_module	uwsgi_pass	uwsgi proxy
ngx_http_scgi_module	scgi_pass	SCGI proxy
ngx_http_grpc_module	grpc_pass	gRPC over HTTP/2
ngx_http_memcached_module	memcached_pass	memcached protocol
ngx_http_mirror_module	mirror	Side-channel request mirroring

Phase handlers

Modules attach to specific phases (see request-lifecycle):

Phase	Module	Effect
POST_READ	ngx_http_realip_module	Rewrite $remote_addr from a trusted header
SERVER_REWRITE	ngx_http_rewrite_module	rewrite, set, if, return, break
REWRITE	ngx_http_rewrite_module	(location scope)
PREACCESS	ngx_http_limit_conn_module	Cap concurrent connections by key
PREACCESS	ngx_http_limit_req_module	Token-bucket request rate limiting
PREACCESS	ngx_http_degradation_module	Return 204/444 under memory pressure
ACCESS	ngx_http_access_module	allow/deny by IP / CIDR
ACCESS	ngx_http_auth_basic_module	HTTP Basic auth
ACCESS	ngx_http_auth_request_module	Subrequest-based auth
PRECONTENT	ngx_http_try_files_module	try_files
LOG	ngx_http_log_module	Access log

Output filters

Filters chain themselves at module init time. Listed roughly in the order bytes flow:

Module	Effect
ngx_http_postpone_filter_module	Order subrequest output
ngx_http_ssi_filter_module	Server-Side Includes (<!--# include -->)
ngx_http_charset_filter_module	charset / source_charset recoding
ngx_http_addition_filter_module	add_after_body, add_before_body
ngx_http_image_filter_module	Resize / crop / rotate via libgd
ngx_http_xslt_filter_module	Transform XML responses with libxslt
ngx_http_sub_filter_module	String substitution (sub_filter find replace;)
ngx_http_gunzip_filter_module	Decompress upstream gzip for downstream non-gzip clients
ngx_http_userid_filter_module	Issue / track an identity cookie
ngx_http_headers_filter_module	add_header, expires, Cache-Control
ngx_http_not_modified_filter_module	Conditional GET / 304
ngx_http_range_filter_module	Range requests
ngx_http_slice_filter_module	Split big requests into byte ranges for caching
ngx_http_gzip_filter_module	Compress response body
ngx_http_gzip_static_module	Serve a precomputed .gz if available
ngx_http_chunked_filter_module	Add Transfer-Encoding: chunked for HTTP/1.1

(Plus the canonical ngx_http_header_filter_module that writes the status + headers and ngx_http_write_filter_module at the very bottom.)

Variable producers

Some modules exist mostly to add variables and config-time data structures:

Module	What it adds
ngx_http_geo_module	geo $address $value { ... } over a radix tree
ngx_http_geoip_module	MaxMind GeoIP (legacy MMDB)
ngx_http_map_module	map $a $b { ... }
ngx_http_split_clients_module	Percentile-based variable
ngx_http_secure_link_module	secure_link MD5-based URL signing
ngx_http_referer_module	valid_referers + $invalid_referer
ngx_http_browser_module	Stale UA fingerprinting ($ancient_browser)

Upstream-side

Module	Purpose
ngx_http_upstream_round_robin_module	Default LB
ngx_http_upstream_ip_hash_module	Stable LB on first three octets
ngx_http_upstream_hash_module	Consistent hash on a key
ngx_http_upstream_least_conn_module	Pick fewest in-flight
ngx_http_upstream_random_module	Random / "two least_conn"
ngx_http_upstream_keepalive_module	Per-worker idle pool to backends
ngx_http_upstream_sticky_module	Sticky sessions
ngx_http_upstream_zone_module	Shared-memory upstream peer state

TLS / Auth

Module	Purpose
ngx_http_ssl_module	TLS 1.2/1.3 via OpenSSL (the listen ... ssl; half)
ngx_http_v2_module	HTTP/2 directives + connection init
ngx_http_v3_module	HTTP/3 directives + bridging
ngx_http_auth_basic_module	HTTP Basic
ngx_http_auth_request_module	External-subrequest auth

Perl

src/http/modules/perl/ is a small XS module that lets nginx embed Perl handlers via perl_set and perl. Built only when --with-http_perl_module is passed; rare in modern deployments.

How modules hook in

Two mechanisms:

1. Phase handlers — register in postconfiguration:

   h = ngx_array_push(&cmcf->phases[NGX_HTTP_ACCESS_PHASE].handlers);
   *h = ngx_http_my_handler;

2. Filter chain — capture and override:

   ngx_http_next_body_filter = ngx_http_top_body_filter;
   ngx_http_top_body_filter = ngx_http_my_body_filter;

The order of filter installation determines the chain order. The build system (specifically auto/modules) is what decides registration order — auto/modules writes objs/ngx_modules.c such that the ngx_modules[] array reflects the documented ordering.

File pointers (a few examples)

File	Notable size
src/http/modules/ngx_http_proxy_module.c	~5,400 lines — the big one
src/http/modules/ngx_http_grpc_module.c	~5,000 lines — gRPC over H2
src/http/modules/ngx_http_mp4_module.c	~4,000 lines — MP4 atom parsing
src/http/modules/ngx_http_fastcgi_module.c	~3,800 lines — FastCGI protocol
src/http/modules/ngx_http_ssl_module.c	~1,500 lines — directives only; the heavy lifting is in event/
src/http/modules/ngx_http_log_module.c	~1,800 lines — access log + log_format engine

Adding a module

The standard skeleton:

1. Create src/http/modules/ngx_http_my_module.c.
2. Declare commands[], ngx_http_module_t ctx, ngx_module_t.
3. Decide hook: phase handler (set in postconfiguration), filter (capture top), content handler (set in directive's setter).
4. Register with auto/modules so the build system picks it up.
5. Add a sources line in auto/sources if needed.

For dynamic modules, repeat steps 1–3 and configure with --add-dynamic-module=... instead of --add-module=....

See primitives/module for the full struct layout.