{"canonical_url":"https://engineer.company/glossary/nginx/","content_markdown":"# nginx\n\n## What it is\n\nnginx is an open-source program that accepts HTTP connections and, for each\nrequest, either answers it from files on disk or hands it to another server and\nrelays the reply. The name is pronounced \"engine x\", and the project's own\npages also write it NGINX. Igor Sysoev wrote it, and the first public version,\n0.1.0, came out on 4 October 2004. It is free to use under a 2-clause BSD\nlicence, and F5, Inc. sells enterprise distributions, support and training.\n\nThe project lists six roles: HTTP server, reverse proxy, content cache, load\nbalancer, TCP and UDP proxy, and mail proxy. On a web host it usually holds one\nor both of two jobs: serving static files from disk, and standing in front of\nan application server, where it terminates TLS and forwards each request\ninward.\n\nWhen it starts, nginx runs a single master process and a number of worker\nprocesses. The master reads and checks the configuration and looks after the\nworkers. The workers run as an unprivileged user and do all of the request\nhandling. Each one uses an event-based loop, built on epoll on Linux and kqueue\non FreeBSD, so a handful of workers can keep thousands of connections open at\nonce. The worker_processes directive sets how many there are, either as a fixed\nnumber or as auto for one per CPU core, and the project's feature list puts\n10,000 idle keep-alive connections at about 2.5 MB of memory.\n\nThe configuration is a text file of directives. A simple directive is a name\nand its parameters, ending in a semicolon. A block directive wraps other\ndirectives in braces, and a block that can hold directives is called a context.\nThe events and http contexts sit at the top level. Inside http, each server\nblock describes one virtual server, picked by the address and port it listens\non and then by the host name the client asked for. Inside a server block, each\nlocation block says what to do with a family of request paths.\n\n## Why it matters\n\nThe web server is the one program every visitor touches, so its behaviour under\nload and its defaults reach everyone. Two properties make the case for nginx.\n\nThe first is how cheaply it carries slow connections. Response buffering from a\nproxied server is on by default: nginx takes the backend's answer as fast as\nthe backend can produce it, spilling to a temporary file when it outgrows\nmemory, and then feeds it to the client at whatever pace the client manages.\nThe application server is free for its next request while a phone on a weak\nsignal is still downloading the last one.\n\nThe second is that configuration changes go out without dropping requests.\nConfiguration edits take effect only on a reload or a restart. On a reload the\nmaster checks the new configuration and tries to apply it. When that works, new\nworkers start with it, while the old ones stop accepting connections, finish\nthe requests they hold and exit. When it fails, the master rolls back and keeps\nserving with the configuration it already had. The project also lists upgrading\nthe binary itself without interrupting clients.\n\nThe price is paid in the configuration language, whose rules on precedence and\ninheritance are where most surprises live. For a request path, nginx first\nfinds the longest matching prefix location and remembers it, then tries the\nregular-expression locations in the order they appear in the file and takes the\nfirst that matches. The remembered prefix is used when the regular expressions\nall fail. A location marked `=` matches the path exactly and ends the search at\nonce, and `^~` on the longest prefix tells nginx to skip the regular\nexpressions. Some directives, add_header and proxy_set_header among them, are\ninherited from the enclosing level only if the current level defines none of\nits own.\n\nCertificates long came from an ACME client running beside nginx. The project\nnow also offers ngx_http_acme_module, shipped separately from the core build.\n\n## What it looks like in practice\n\nTwo pieces of hosting work from the founder's earlier roles involve nginx, and\nin both it shared the servers with Apache rather than replacing it.\n\nThe first was\n[forty client websites that had to be quick and always reachable](/portfolio/administered-40-websites-on-apache-and-nginx/),\nwhich ran on Ubuntu Linux servers where Apache and nginx were both in use. The\njob was writing their configuration, tuning them for speed and looking after\nthem while real visitors were on them, and all forty stayed highly available.\nTwo web servers on one fleet means every rule in two dialects: an Apache\nvirtual host is an nginx server block, and a fix found for one must be\ntranslated for the other.\n\nThe second ran from 2015 to 2022.\n[An ACME workflow took over certificates for a hundred Docker applications](/portfolio/automated-ssl-tls-certs-for-100-docker-apps/),\nissuing each one, renewing it before expiry and installing it on the Ubuntu\nhosts with no person in the loop, and Apache and nginx were again both in use\non those hosts. On the nginx side, a renewed file on disk is half of such a\nchange. A certificate named by a plain path is read when nginx loads its\nconfiguration, and the documentation notes that only a file name built from\nvariables makes it load the certificate again on each TLS handshake. A renewal\nthat writes new files therefore reaches visitors only after a reload, so any\nautomated renewal for nginx has to end with one.\n\n## Where it goes wrong\n\n**A header set for the whole site vanishes on one path.** A location that has\nany add_header of its own inherits none from the server or http level, so one\ncache header added to a single location silently drops every security header\nabove it. proxy_set_header follows the same rule. add_header also applies only\nto success and redirect codes such as 200, 301 and 304 unless given `always`,\nso error pages go out bare. Keep shared\nheaders in one file pulled in with include at every level that sets its own,\nor from 1.29.3 set `add_header_inherit merge;`, add `always` where error\nresponses need them, and check each path with `curl -sI`.\n\n**Requests for one site are answered by another.** nginx matches the address\nand port first, then the Host header against server_name. When the name is\nunknown to every server block on that port, the request goes to the default\nserver, which is the first one listed unless another is marked default_server.\nA typo in a new site's server_name quietly serves an old neighbour's pages.\nDeclare an explicit default server that answers unknown names with\n`return 444`, which closes the connection, so a mistake shows up as an error\nrather than as the wrong site.\n\n**Uploads fail with 413 Request Entity Too Large.** client_max_body_size\ndefaults to 1 MB, and nginx rejects a larger request body before the\napplication sees it. Raise the limit in the location that accepts uploads\nrather than for the whole server, and keep it in step with the application's\nown limit.\n\n**The backend builds links to the wrong host or receives the wrong path.**\nUnless told otherwise, nginx sends the proxied server a Host header made from\nthe address in proxy_pass, such as `127.0.0.1:8080`, so the application\ngenerates redirects and absolute links to that address. Set\n`proxy_set_header Host $host;` in the proxying location. Paths change with the\nform of proxy_pass: written with a URI, even a single `/`, it replaces the part\nof the path that matched the location, while written without one it passes the\npath through unchanged, so test a nested path after any change.\n\n**Clients still get the old configuration or the old certificate.** An edited\nfile, or a certificate renewed overnight, has no effect on a running nginx\nuntil a reload, and a reload of a broken configuration leaves the old one in\nplace. Test before every reload, then read the error log and check what\nclients actually receive:\n\n```sh\nnginx -t \u0026\u0026 nginx -s reload\nopenssl s_client -connect example.com:443 \\\n  -servername example.com \u003c/dev/null |\n  openssl x509 -noout -enddate\n```\n\n## Further reading\n\n- [nginx documentation](https://nginx.org/en/docs/)\n  — the project's index of guides and per-module directive references.\n- [Beginner's Guide](https://nginx.org/en/docs/beginners_guide.html)\n  — master and worker processes, reloading, and the configuration's structure.\n- [How nginx processes a request](https://nginx.org/en/docs/http/request_processing.html)\n  — how a server block is chosen by address, port and Host header.\n- [Module ngx_http_core_module](https://nginx.org/en/docs/http/ngx_http_core_module.html)\n  — location matching order, server_name and client_max_body_size.\n- [Module ngx_http_proxy_module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html)\n  — proxy_pass, header defaults, timeouts and response buffering.\n- [Module ngx_http_headers_module](https://nginx.org/en/docs/http/ngx_http_headers_module.html)\n  — add_header, its response codes and its inheritance rule.\n\n\u003chttps://engineer.company/glossary/nginx/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"How nginx picks a server block and a location for each request, why a reload leaves running requests alone, and the defaults behind its surprises.","formats":{"gemtext":"https://engineer.company/glossary/nginx/index.gmi","gopher":"https://engineer.company/glossary/nginx/gophermap","html":"https://engineer.company/glossary/nginx/","json":"https://engineer.company/glossary/nginx/index.json","markdown":"https://engineer.company/glossary/nginx/index.md","pdf":"https://engineer.company/glossary/nginx/index.pdf"},"kind":"page","language":"en","title":"What is nginx?","url":"https://engineer.company/glossary/nginx/","version":1}