nginx: Web Server, Reverse Proxy and Load Balancer
GitHub Repo
BSD-2-Clause
November 19, 2026 at 01:55 PM
0 views

nginx: Web Server, Reverse Proxy and Load Balancer

@nginxProject Author

What nginx is

nginx (pronounced "engine x") is a web server, reverse proxy, load balancer and content cache written in C. The project's own site describes it as "an HTTP web server, reverse proxy, content cache, load balancer, TCP/UDP proxy server, and mail proxy server", originally written by Igor Sysoev. The README calls it "the world's most popular Web Server"; the nginx.org home page attributes that claim to Netcraft.

It sits in front of applications: it terminates TLS, serves static files from disk, forwards everything else to application servers, spreads load across backends, caches responses and limits abusive clients.

The GitHub repository dates from June 2015, but the project is much older: the changelog in the repository starts with version 0.1.0 dated 4 October 2004, and the licence file carries "Copyright (C) 2002-2021 Igor Sysoev" alongside "Copyright (C) 2011-2026 Nginx, Inc.". The licence is BSD-2-Clause. The README points to F5, Inc. for enterprise distributions, commercial support and training (the commercial build is NGINX Plus); several features documented on nginx.org are marked "available as part of our commercial subscription".

For a browser-based way to manage nginx configuration files, see the separate Nginx UI project, which is not part of nginx itself.

How it works

Master and worker processes

nginx runs as a small set of processes rather than one process per connection. The README describes a "master" process that "maintains worker processes, as well as, reads and evaluates configuration files" and one or more "worker" processes that handle requests. The beginner's guide adds that nginx "employs event-based model and OS-dependent mechanisms" (epoll on Linux, kqueue on FreeBSD) so each worker can handle many connections at once. worker_processes auto sizes the pool to the CPU count. Shared state such as rate-limit counters lives in named shared memory zones, which is why limit_req_zone declares a size.

The master also implements zero-downtime operations through signals: HUP re-reads the configuration and starts new workers while old ones finish their requests, USR1 reopens log files for rotation, and USR2 starts a new binary alongside the old one for an in-place upgrade. The "Controlling nginx" page documents the full upgrade and roll-back sequence.

Modules and configuration

Almost every feature is a module, and modules are either compiled in statically at build time or, since 1.9.11, built as dynamic modules loaded with load_module. The set of directives that exists depends on which modules a given binary contains, which is why nginx -V (print the configure arguments) is the first thing to check on an unfamiliar server. Several modules are "not built by default" according to the configure reference, including the SSL, HTTP/2, HTTP/3 and stub_status modules, so a plain source build lacks TLS.

Configuration is a text file of directives: simple ones end with a semicolon, block ones (http, server, location) open a context in braces.

Key features

  • Static file serving. Index files, autoindexing, an open file descriptor cache and sendfile.
  • Reverse proxying with caching. HTTP and HTTPS backends, plus FastCGI, uwsgi, SCGI, memcached and gRPC, with an on-disk response cache. Since 1.29.4 the proxy module can speak HTTP/2 to backends.
  • Load balancing. Round-robin by default, least-connected and IP hash among the documented methods, with passive failure handling. Recent mainline releases added session affinity via the sticky directive (1.29.6) and a least_time method (1.31.0).
  • TLS, HTTP/2 and HTTP/3. TLS with SNI, OCSP and session tickets; HTTP/2; and HTTP/3 over QUIC, which the HTTP/3 module page still labels "experimental, caveat emptor applies".
  • Traffic control. Request rate limiting (limit_req, a leaky-bucket algorithm per key), connection limiting (limit_conn) and response bandwidth limiting (limit_rate).
  • Access control. IP allow/deny, HTTP Basic authentication and authorisation by subrequest, a hook that can put an identity-aware proxy such as OAuth2 Proxy in front of internal tools.
  • TCP/UDP and mail proxying. The stream module load-balances raw TCP and UDP with SSL and SNI support; the mail module proxies IMAP, POP3 and SMTP.
  • Newer mainline additions. The 1.31 line added a tunnel module (1.31.0), and 1.31.5 brought a control API, "predicate locations" and an ngx_http_json_module; the -l control API switch was commercial-only from 1.29.8 until 1.31.5.

Getting started

The README recommends the official nginx.org packages over distribution builds so that installs track current releases and security fixes. On Ubuntu, the nginx.org Linux packages page installs the prerequisites, imports the signing key and adds the repository:

sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring
curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
    | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

Stable packages come from this repository line (a /mainline/ path selects mainline instead):

echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
https://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list
sudo apt update
sudo apt install nginx

The page gives the key fingerprint to check (573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62) and lists Ubuntu 22.04, 24.04 and 26.04 on x86_64 and arm64.

Building from a Git checkout follows the README. It lists the compiler, PCRE and zlib headers, plus OpenSSL for TLS:

sudo apt install gcc make
sudo apt install libpcre3-dev zlib1g-dev
sudo apt install libssl-dev
git clone https://github.com/nginx/nginx.git
auto/configure
make
sudo make install
sudo /usr/local/nginx/sbin/nginx
curl localhost

From a release tarball the script is ./configure rather than auto/configure; the configure reference documents every flag. Once nginx is running, the beginner's guide controls it with the same binary:

nginx -s reload
nginx -s quit

Hands-on: building and running nginx 1.31.9

Run on 19 November 2026 in a cloud VM: Ubuntu 24.04.5 LTS, Linux 6.18, x86_64, 2 vCPUs, about 7.8 GB RAM, GCC 13.3.0, OpenSSL 3.0.13, PCRE2 10.42 and zlib 1.3 development headers. The input was the official nginx-1.31.9.tar.gz (1,388,470 bytes, SHA-256 a11c5eee…6dcb80ad) and its .asc signature. All timings are single-machine, 2 vCPU wall-clock figures and only indicative.

Signature check

gpg --verify reported that the signature was made on 11 November 2026 with RSA key D6786CE303D9A9022998DC6CC8464D549AF75C0A, issuer [email protected], and then stopped with Can't check signature: No public key. Sergey Kandaurov's key is listed on the nginx.org PGP keys page, but neither nginx.org nor public keyservers were reachable from this VM, so the signature could not be verified here.

Configure, compile, install

StepResult
./configure --prefix=<workdir>/install --with-http_ssl_module --with-http_v2_module --with-http_stub_status_module7.1 s, 113 "checking for" probes; summary "using system PCRE2 library", "using system OpenSSL library", "using system zlib library"
make -j218.0 s, no compiler warnings
Binary objs/nginx5,549,272 bytes (PIE, with debug info); 1,181,280 bytes after strip
Default ./configure (no flags) and serial make6.3 s and 20.0 s; 4,317,952-byte binary, no TLS module
Shared libraries (ldd)libcrypt, libpcre2-8, libssl.so.3, libcrypto.so.3, libz, libc

nginx -V printed nginx version: nginx/1.31.9, built by gcc 13.3.0 (Ubuntu 13.3.0-6ubuntu2~24.04.1), built with OpenSSL 3.0.13 30 Jan 2024, TLS SNI support enabled and the configure arguments. The README's dependency line installs libpcre3-dev, the legacy PCRE package, but the build prefers PCRE2, so libpcre2-dev is the package that matters on current Ubuntu.

Running without root

nginx was run as a dedicated unprivileged user with a separate prefix (-p), on ports 8080 to 8082, with two Python http.server processes on ports 9001 and 9002 as upstreams. The first attempts failed instructively:

AttemptOutput
nginx -t with the stock config as a normal user[emerg] bind() to 0.0.0.0:80 failed (13: Permission denied), after "syntax is ok"
Same, without -p[alert] could not open error log file: open() ".../install/logs/error.log" failed (13: Permission denied), then a failure on nginx.pid

nginx -t is not only a syntax check: the switches page says it "tries to open files referred in the configuration", and it binds listen sockets too. The compiled-in error log path is opened before the configuration is read, which the -e switch (1.19.5) avoids. With -p, -e and listen 8080 the test passed and a master plus two workers started. Idle memory was small: resident set size about 2.0 MB for the master and 2.7 MB per worker, rising to about 3.1 MB and 4.0 MB after the load tests below.

Static files and gzip

Port 8080 had gzip on with gzip_types text/plain application/json, port 8081 gzip off, and port 8082 (added during a live reload) gzip_comp_level 9. Requests sent Accept-Encoding: gzip.

Filegzip offgzip on, level 1 (default)gzip level 9
index.html (welcome page)896 bytes526 bytes-
changes.txt (nginx CHANGES file)359,612 bytes95,324 bytes77,266 bytes
data.json (2,000 small objects)150,780 bytes10,820 bytes10,618 bytes
200 KB random binary200,000 bytes200,000 bytes (not in gzip_types)-

Level 9 shaved another 19% off the text file but 200 sequential fetches of it took 3.68 s against 1.87 s at level 1. Compressed responses changed the headers: Content-Length and Accept-Ranges disappeared and the ETag became weak (W/"6afefbd1-24cfc" instead of "6afefbd1-24cfc"). No Vary header was sent, since gzip_vary defaults to off. Adding a Via: 1.1 cdn request header made nginx return the full 150,780 bytes: gzip_proxied defaults to off, and any request carrying Via counts as proxied, so compression can silently stop behind a CDN. The gzip docs also warn that compressed responses over TLS "may be subject to BREACH attacks".

Reverse proxy and the trailing-slash rule

All locations proxied to an upstream backend block holding both Python servers, which echoed the raw request line. Requests used curl --path-as-is.

Location and proxy_passClient requestUpstream received
location /api/, proxy_pass http://backend/;/api/users/1GET /users/1 HTTP/1.1
same/api/a%20b/../c?q=1GET /c?q=1 (normalised)
same/apinginx itself answered 301 to http://localhost:8080/api/
location /api-noslash/, proxy_pass http://backend;/api-noslash/users/1GET /api-noslash/users/1 (prefix kept)
same/api-noslash/a%20b/../cGET /api-noslash/a%20b/../c (passed exactly as sent)
location /api-loc (no trailing slash), proxy_pass http://backend/;/api-loc/users/1GET //users/1
same/api-locusersGET /users

This is the documented behaviour of proxy_pass: with a URI part (even just /), "the part of a normalized request URI matching the location is replaced by a URI specified in the directive"; without one, the URI is passed "in the same form as sent by a client". The last two rows are the classic mistake: a location without a trailing slash plus a proxy_pass with one produces double slashes and also captures unrelated paths such as /api-locusers. The documentation's own example pairs the slashes:

location /name/ {
    proxy_pass http://127.0.0.1/remote/;

A testing gotcha: Python's http.server collapses a leading // in self.path, so the double slash only appeared once the upstream logged its raw request line.

Two more defaults showed up in every proxied request. The upstream saw Host: backend, the name of the upstream block, because proxy_set_header Host defaults to $proxy_host; backends that route on the host name need proxy_set_header Host $host. And no Connection header arrived at all. Twenty requests split 10/10 between the servers over just four TCP connections (two workers times two servers), confirming 1.29.7's switch to HTTP/1.1 with upstream keepalive by default. The proxy_set_header reference still lists Connection close as a default, which no longer matches this behaviour or the keepalive page.

What nginx -t says about common mistakes

MistakeOutput
Missing semicolon after root html (line 29)[emerg] invalid number of arguments in "root" directive in .../bad.conf:30; the line number points at the next line, because root swallowed gzip on
proxy_pass http://backend/x/; in a regex location[emerg] "proxy_pass" cannot have URI part in location given by regular expression, or inside predicate location, or inside named location, or inside "if" statement, or inside "limit_except" block
limit_req zone=two with no matching limit_req_zone"syntax is ok", then [emerg] zero size shared memory zone "two", with no line number
Missing closing brace[emerg] "server" directive is not allowed here at the next server block
Misspelt upstream name in proxy_pass[emerg] host not found in upstream "backnd"
Two servers on the same port, no server_nameOnly [warn] conflicting server name "" on 0.0.0.0:8080, ignored, and the test passes; the second server block is unreachable

Rate limiting: 503 unless told otherwise

With limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s:

Location configSix or ten rapid requests
limit_req zone=one;200 503 503 503 503 503
plus limit_req_status 429;200 429 429 429 429 429 ("429 Too Many Requests" page)
limit_req zone=one burst=5 nodelay;200 200 200 200 200 200 503 503 503 503
Separate zone at 2r/s, burst=3 (no nodelay), six parallel requestsone 200 at once, three 200s delayed to 0.51 s, 1.01 s and 1.50 s, two immediate 503s

The default rejection is "503 Service Temporarily Unavailable", which clients and monitoring tend to read as a server fault; limit_req_status 429 fixes that. Each rejection was logged at error level, for example limiting requests, excess: 5.819 by zone "one"; limit_req_log_level adjusts that. Locations sharing a zone share its budget. The module page documents the base pattern:

limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
limit_req zone=one burst=5;

Reloading under load

Four requests to a 3-second upstream endpoint were started; one second later a new server on port 8082 was added and nginx -s reload issued. The reload command returned in about 10 ms. ps immediately showed one old worker as "worker process is shutting down" next to two new workers, port 8082 answered 200 straight away, and all four slow requests completed with 200 after 3.00 s. The old worker exited with code 0 once its last request finished.

Failed reloads were also safe. With gzip_comp_level 10 in the file, nginx -s reload printed [emerg] value must be between 1 and 9 and exited with status 1 without signalling the master. Sending HUP directly with kill made the master log "reconfiguring" and the same error, then carry on with the old configuration and the same worker PIDs, matching the documented roll-back behaviour.

A fresh 1.31.9 change, observed

The 1.31.9 changelog says "header lines without a colon are rejected". A raw request containing the line X-Broken-Header got HTTP/1.1 400 Bad Request; the same request without it got 200. An HTTP/1.1 request without Host also got 400.

Quick load test

autocannon 8.0.0 (run with npx) drove 50 connections for 10 seconds per target, from the same 2 vCPU VM, so client and server competed for CPU. Compare rows, not absolute numbers.

TargetRequests/s (avg)Latency avg / p99Notes
Static index.html (896 bytes)37,7785.1 ms / 16 ms377,780 requests, all 2xx
data.json, no gzip (port 8081)6,7349.4 ms / 37 msabout 1 GB/s over loopback
data.json, gzip level 13,21916.2 ms / 110 mscompression roughly halved throughput, but cut bytes about 14-fold
Proxy to Python upstreams1,05346.9 ms / 51 msbounded by the Python servers
Python upstream directly98850.0 ms / 51 msbaseline for the row above

autocannon counted 24 socket errors in the static index.html run and 5 in the gzip run while nginx's error log stayed empty, most likely connections cut when each run ended. nginx was then stopped with nginx -s quit; the log showed both workers exiting and the master's exit.

Stable, mainline and release cadence

Per the README, stable builds "only contain critical fixes backported from the mainline version", while mainline is built from master with the latest features and fixes. In practice odd minor numbers have been mainline and even ones stable: the stable branch's changelog opens its 1.30.0 entry (14 April 2026) with "1.30.x stable branch", and the mainline changelog jumps from 1.29.8 (7 April 2026) to 1.31.0 (13 May 2026).

On 18 November 2026 both lines were released: mainline 1.31.9 and stable 1.30.7. The mainline release fixes ten CVEs, among them HTTP/2, HTTP/3, resolver and mail-proxy memory-safety bugs and a try_files plus alias buffer overflow. Stable 1.30.7 carries nine of them; the missing one concerns PROXY protocol version 2 with dynamic certificates, which the security advisories list as affecting only 1.31.4 to 1.31.8. The previous mainline, 1.31.8, came out on 21 October 2026. master already reports 1.31.10.

The mainline changelog shows 14 releases in 2026 so far, against 7 in 2025, and the nginx.org security advisories page lists 36 advisories with 2026 CVE identifiers against 2 for 2025. The security policy recommends running the latest mainline or stable release.

Use cases

  • Front door for application servers. TLS termination, static assets and proxy_pass to Node.js, Python, Go or Java services; FastCGI to PHP-FPM. For PHP, FrankenPHP is an all-in-one alternative built on Caddy.
  • Load balancer. An upstream group with round-robin, least-connected or IP-hash balancing in front of several instances, with keepalive to backends now on by default.
  • API rate limiting and auth gating. limit_req per client or key, and auth_request subrequests to an external authorisation service.
  • TCP/UDP proxying. The stream module for databases, message brokers or DNS, including TLS termination and SNI-based routing with ssl_preread.
  • Basic metrics. stub_status exposes connection and request counters; monitoring stacks such as Prometheus typically collect them through a separate exporter.

How nginx compares

The table compares what each project's own README or licence file says, as fetched on 19 November 2026. Only nginx was tested here, and none of the alternatives were benchmarked.

ProjectHow it describes itselfConfiguration modelAutomatic HTTPSLicence
nginxWeb server, load balancer, reverse proxy, API gateway and content cacheStatic text files, applied by graceful reload; a control API arrived in mainline 1.31.5Via the separate nginx-acme module (Rust, HTTP-01 only per its README), not built inBSD-2-Clause
Caddy"An extensible server platform that uses TLS by default", written in GoCaddyfile, native JSON and a JSON API for dynamic changesYes, by default (Let's Encrypt and ZeroSSL, local CA)Apache-2.0
Traefik"A modern HTTP reverse proxy and load balancer that makes deploying microservices easy"Discovers routes from Docker, Kubernetes, Consul, ECS and others; "Continuously updates its configuration (No restarts!)"Yes, via Let's EncryptMIT
Envoy"Cloud-native high-performance edge/middle/service proxy", hosted by the CNCFREADME points to its universal data-plane API definitions for dynamic configurationNot described in its READMEApache-2.0
HAProxy"A free, very fast and reliable reverse-proxy offering high availability, load balancing, and proxying for TCP and HTTP-based applications"Configuration file; README defers to its documentationNot described in its READMEGPL-2.0 core with LGPL headers and an OpenSSL exception
Apache HTTP Server"A powerful, flexible, HTTP/1.1 and HTTP/2 compliant, and widely deployed web server", developed since 1995Configuration files; README defers to its documentationNot described in its READMEApache-2.0

In broad terms, nginx and Apache httpd are general-purpose web servers that also proxy. Caddy competes on ease of use, with certificates handled automatically. Traefik and Envoy target environments where routes come from an orchestrator or control plane, which nginx's file-and-reload model handles less naturally without extra tooling. HAProxy is a dedicated load balancer rather than a file server, and the only copyleft project in the table.

Limits and when not to use it

  • No built-in certificate automation. TLS certificates are files that something else must obtain and renew. The ACME module exists but is a separate build with a Rust toolchain requirement, or a separate package. If automatic HTTPS is the main need, Caddy or Traefik do it out of the box.
  • Configuration footguns. As the tests showed, proxy_pass trailing slashes silently change URIs, a duplicate listen produces only a warning, rate limiting returns 503 by default, gzip stops behind any proxy that sets Via, and the upstream sees the upstream block name as its Host. nginx -t catches syntax errors but not these logic errors.
  • Static, reload-driven configuration. Every route change means editing files and reloading. Reloads are graceful, but highly dynamic service discovery needs templates, an Ingress controller or the new control API, which is only in the 1.31 mainline line.
  • Open-core split. Some documented capabilities are marked as part of F5's commercial subscription, for example variables in the limit_req_zone rate (1.31.3) and the zone sync parameter. Read the notes on each directive page before planning around a feature.
  • Heavy 2026 security load. 36 advisories with 2026 CVEs, many of them memory-safety bugs in HTTP/2, HTTP/3 and other modules, mean nginx needs prompt patching; distribution packages that lag behind are a real risk.
  • HTTP/3 is experimental by the module's own description and is not built by default.
  • Windows is not for production. The README calls the Windows build "Proof-of-Concept", for "development and testing purposes"; the Windows page calls it a "beta version" limited to select and poll, effectively one worker, and no UDP or QUIC. The labels differ; the advice does not.
  • Trust model. The security policy treats configuration files, modules, certificates, njs code and local files as trusted, and says nginx "inherently trusts the content and instructions from upstream servers". It also warns that debug logs and core files can contain private keys.

Project activity

Checked 19 November 2026: latest mainline release 1.31.9 and latest stable release 1.30.7, both dated 18 November 2026 in the mainline and stable changelogs; previous mainline 1.31.8 on 21 October 2026; licence BSD-2-Clause; 32,239 stars and 8,408 forks on the nginx/nginx repository. Pull requests require the F5 Contributor License Agreement. The repository is written in C, develops mainline on master with stable work on stable-1.x branches, and was created on GitHub on 23 June 2015, more than a decade after the first changelog entry. Documentation and downloads are at nginx.org; questions go to the community forum or GitHub Discussions, bugs to GitHub issues, and vulnerabilities privately to F5. The security policy's targets are acknowledgement within 1 to 3 days and fixes within 90 days.

Enjoying this project?

Discover more amazing open-source projects on TechLogHub. We curate the best developer tools and projects.

Project
nginx
Created
November 19
Last Updated
November 19, 2026 at 01:55 PM

Maintain nginx: Web Server, Reverse Proxy and Load Balancer? Add the badge to your README

Show that the project is featured on TechLogHub and send readers to this write-up.

Featured on TechLogHub
[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/nginx?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)

Find more projects like this

One email a week: new and trending developer tools, fresh comparisons, and what shipped. Unsubscribe in one click.