NGINX Fundamentals

01

The big picture

NGINX (“engine-x”) is software that sits in front of your web application and is the first thing every incoming request hits.

It does a handful of front-door jobs — handing out static files itself, passing harder requests to your real application, spreading load across multiple app servers, caching answers, and terminating HTTPS — while juggling a huge number of simultaneous visitors.

                      THE INTERNET  (a crowd of guests arriving)
          browser   phone    API client   browser
             |        |           |           |
             v        v           v           v
   +-----------------------------------------------+
   |                  N G I N X                     |   <- the maitre d'
   |   - hands out static files itself (bread)      |
   |   - routes harder requests to the back         |
   |   - load-balances across kitchens              |
   |   - caches, terminates TLS                      |
   +-----------------------------------------------+
             |             |              |
             v             v              v
      +-----------+  +-----------+  +-----------+
      |  app srv  |  |  app srv  |  |  app srv  |       <- the kitchens / chefs
      |  (Node)   |  |  (Python) |  |  (Ruby)   |
      +-----------+  +-----------+  +-----------+

One-liner: NGINX is the front door and traffic director for a web service.

02

Why NGINX exists — the C10k problem

Rewind to the late 1990s / early 2000s. The dominant web server was Apache HTTP Server, and its classic model handled visitors with one dedicated worker (process, later thread) per connection.

That failure has a name: the C10k problem — can one server handle ten thousand concurrent connections? Coined by Dan Kegel around 1999.

   OLD MODEL  (thread/process per connection - classic Apache)

   guest 1     -->  worker 1   (idle, but holding memory + a stack)
   guest 2     -->  worker 2   (idle, blocked, waiting on the network)
   guest 3     -->  worker 3
     :                 :
   guest 10000 -->  worker 10000   <-- server falls over here
                                        not from CPU - from the
                                        overhead of 10k workers

Igor Sysoev wrote NGINX to solve exactly this for a large Russian site (Rambler); first released 2004. The fix: a tiny number of workers — roughly one per CPU core — each watching thousands of connections and only doing work when a connection actually has something to do.

   NEW MODEL  (event-driven, non-blocking - NGINX)

   guest 1  -+
   guest 2  |
   guest 3  +-->  ONE waiter  --> watches ALL tables at once;
     :      |     (per CPU core)    springs into action only when
   guest N  -+                       a table actually raises a hand

03

The alternatives & trade-offs

NGINX is not the only front door in town. The real contenders, and where each one actually wins:

The honest axes

NGINX vs Apache. NGINX wins on raw concurrency, static-file serving, and low-memory proxying. Apache wins on flexibility: .htaccess lets each directory carry its own config (great for shared hosting), and it can run application code inside the server process. NGINX deliberately has no .htaccess equivalent — all config is centralized. That’s a feature (no per-request disk lookups) and a limitation (less convenient when you can’t touch main config).

NGINX vs HAProxy. HAProxy is a sharper pure load balancer with deeper traffic-shaping, but it won’t serve static files or be a general web server. NGINX is the Swiss Army knife; HAProxy is the specialist scalpel.

NGINX vs Caddy. Caddy gives automatic HTTPS with near-zero config. NGINX is more battle-tested and has a deeper ecosystem, at the cost of more setup.

NGINX vs Envoy/Traefik. In a dynamic container/microservices world where backends appear and vanish, Envoy and Traefik were built for auto-discovery. NGINX can do it but it’s not its native home.

04

When to use NGINX — and when not to

Reach for NGINX when

You want a reverse proxy in front of one or more app servers; you serve a mix of static assets and dynamic responses; you need TLS termination; you want to load-balance across a handful of backends; or you want caching. In short: the default sensible front door for most web stacks.

Pick something else when

05

What .htaccess actually is

.htaccess (“hypertext access”) is an Apache feature: a small config file you drop inside a directory of your site. It applies rules to that directory and everything below — URL rewrites, redirects, password-protecting a folder, blocking IPs, custom error pages.

Why it exists: shared hosting. If you’re one of 500 customers on a provider’s Apache box, you can’t touch the main server config — so .htaccess lets you configure your slice by dropping a file in your folder, no admin access, no restart.

   APACHE with .htaccess enabled - EVERY request for
   /var/www/shop/cart/index.html makes Apache walk the path
   and read a card in each room along the way:

      /var/www/.htaccess           <- read it
      /var/www/shop/.htaccess      <- read it
      /var/www/shop/cart/.htaccess <- read it
                                     ...on EVERY request

06

.htaccess: NGINX vs HAProxy

The twist: neither NGINX nor HAProxy has .htaccess — it’s an Apache concept. But why each lacks it is completely different, and that difference teaches you what each tool fundamentally is.

NGINX = “No cards in rooms. One master rulebook at the door, memorized; re-memorized only when handed an update.” Faster (no per-guest card-reading), less convenient (edit the master rulebook).

HAProxy = the valet/dispatcher on the curb waving cars toward different restaurants. He has no dining room, so “house-rules cards” is a meaningless idea to him. (Tiny caveat: HAProxy can return a few canned error-page files via errorfile, but it has no document root or general static serving — so the .htaccess model still doesn’t apply.)

07

12 real-world use cases: .htaccess → NGINX

Same job, two filing systems. Syntax is illustrative — recognize the shape, look up exact flags when you ship.

Two honest footnotes: #4 isn’t a 1:1 translation — NGINX prefers try_files (does the file exist? else hand to the app) and treats if/rewrite as a last resort (see the famous “If Is Evil” community page). You rethink Apache rewrites into try_files rather than porting them. #7: directory listing is work to disable in Apache but is already off by default in NGINX.

08

File descriptors — the foundation

Before epoll makes sense, you need this brick. When you check a coat, they don’t pass the actual coat back and forth — they give you a numbered ticket, “#42.” From then on you say “42,” not “the navy wool one with the torn pocket.” The number is a handle — a tiny stand-in for a big complicated thing.

A file descriptor (FD) is that ticket, inside a program on Linux. And the surprising part: on Linux almost everything is treated like a “file” — not just disk files, but network connections, your keyboard, the screen, pipes between programs. Each time a program opens one, the OS hands back a small integer (0, 1, 2, 3…). That integer is the file descriptor.

   THE COAT CHECK  (analogy)        -->   YOUR PROGRAM (real)

   "here's ticket #42"              -->   open()/accept() returns FD 7
   you hold ticket #42              -->   program holds the integer 7
   "fetch 42" (not "the navy coat") -->   read(7) / write(7)
   attendant knows what #42 is      -->   kernel knows FD 7 =
                                          "TCP connection to 1.2.3.4"

So when a browser connects, NGINX gets back a file descriptor — say FD 7 — and that number now means “this visitor’s connection.” 10,000 visitors = 10,000 tickets = file descriptors 7, 8, 9, … up into the thousands.

09

epoll vs select/poll — watch many, pay for few

NGINX is holding thousands of file descriptors. The question is: which of them have something ready right now? How you answer that is the whole ballgame.

The naive way: walk the whole room (select / poll)

That’s literally select() / poll(): you hand the kernel your whole set of connections, it scans all of them, and you scan them again to find the ready ones. Cost grows with total connections — O(n) — on every call. (select also has a hard descriptor cap, commonly 1024.)

The smart way: a bell system (epoll)

That’s epoll, Linux’s I/O event-notification mechanism (added in Linux 2.6, ~2002). You register FDs once; the kernel maintains a ready list behind the scenes; epoll_wait returns just the active ones. Cost scales with busy connections, not total.

Watch it: idle FDs are free under epoll

NGINX doesn’t hard-code epoll — it auto-selects the best mechanism per OS:

10

How epoll works — the kernel does the noticing

The crucial thing: epoll is passive. It is not running around poking each connection. The thing doing the noticing is the kernel (the OS itself), while NGINX is busy elsewhere.

   When data comes back on a connection:

   1. data packet arrives at the network card
   2. the kernel's networking code: "this belongs to socket FD 7"
   3. kernel drops the data in FD 7's receive buffer and
      flips a flag: "FD 7 is now READY to read"
   4. because FD 7 is registered with the epoll instance,
      the kernel adds FD 7 to that instance's READY LIST
   5. NGINX calls epoll_wait()  -->  kernel hands back: [ 7 ]
   6. NGINX: "oh, FD 7 has data" and reads it

Steps 1–4 happen on their own while NGINX does nothing. By the time NGINX calls epoll_wait, the answer is already sitting there. NGINX doesn’t search — it collects. The three commands:

11

The complete request round trip

Now the payoff — one full request, browser knocks to browser answered. Notice both the browser’s connection (FD 7) and the backend’s connection (FD 51) live on the same epoll instance. One worker, one board, both directions. Press play to step through 1 → 7.

12

“The board” = an epoll instance

The board is an epoll instance, created with epoll_create1(). The twist that should make you grin: the board is itself a file descriptor. Create one and the kernel hands you back… an FD referring to it. The bell-board gets its own ticket number, just like every connection.

Inside that one instance, the kernel keeps two lists (the real terms):

   ONE epoll instance (one board) = one FD, holding two lists:

   +- epoll instance (itself FD 12) ---------------+
   |  INTEREST LIST  (everything I'm watching)      |
   |     FD 7   FD 8   FD 9 ... FD 51 ... FD 4287   |
   |                                                |
   |  READY LIST  (only what's ringing now)         |
   |     FD 7   FD 51        <- epoll_wait returns these
   +------------------------------------------------+

The interest list is everything you’ve registered via epoll_ctl (“all the tables whose bells I’m wired to watch”). The ready list is the subset ready right now (“the bells currently ringing”) — and epoll_wait pulls from that one.

13

Can there be many boards? Yes — one per worker

Sense 1 (trivial): nothing stops a program from calling epoll_create1() several times; each is an independent instance with its own interest/ready lists.

Sense 2 (the NGINX reality): NGINX runs as one master process + several worker processes, typically one worker per CPU core (worker_processes auto;). Each worker has its own epoll instance.

   4 cores  -->  4 workers  -->  4 boards  (NOT 4000 boards for 4000 connections)

   Worker 1 (core 1)        Worker 2 (core 2)
   +- board A (FD) -+        +- board B (FD) -+
   | FD 7, 9, 22... |        | FD 8, 15, 51...|
   +----------------+        +----------------+

   Worker 3 (core 3)        Worker 4 (core 4)
   +- board C ------+        +- board D ------+
   | FD 11, 30...   |        | FD 13, 41...   |
   +----------------+        +----------------+

14

Here be dragons — edges, wrinkles, open threads

The clean model above is true, but reality has texture. These are the known wrinkles, flagged honestly so you know where to dig later.

15

Quick-reference glossary

16

Recall questions & diffuse-mode seeds

Active recall beats re-reading. Cover the answers and try these cold.

§

References

A verification trail. Prefer tier-1 sources (the spec, official docs) over blogs.