Understanding Nginx Architecture, Modules, Process Model, and Performance Optimization

NGINX is a high‑performance load balancer, cache, and web server that powers over 40% of the busiest websites. While the default configuration works for most scenarios, achieving optimal performance often requires tuning the server, its modules, and the underlying Linux system.

Key Features

Event‑driven architecture and asynchronous non‑blocking processing for high concurrency.

Reverse proxy, static file serving, dynamic content handling, caching, SSL/TLS support, and a modular extensible design.

Module Classification

Modules are divided into three structural groups:

Core modules: HTTP, EVENT, MAIL.

Standard modules: HTTP Access, FastCGI, Proxy, Rewrite.

Third‑party modules: Upstream Request Hash, Notice, Access Key.

From a functional perspective, modules fall into Handlers (process requests), Filters (modify response content), and Proxies (communicate with upstream services).

Process Model

NGINX starts a master process that manages multiple worker processes. The master handles signals, monitors workers, and performs graceful restarts. Workers are single‑threaded, each handling network events using an asynchronous I/O model (epoll on Linux, kqueue on BSD).

When a worker accepts a connection, it reads, parses, processes, and returns the response. Workers compete equally for connections, and the number of workers is typically set to the number of CPU cores.

Event Handling Loop (simplified)

while (true) {
    for t in run_tasks:
        t.handler();
    update_time(&now);
    timeout = ETERNITY;
    for t in wait_tasks: /* sorted already */
        if (t.time <= now) {
            t.timeout_handler();
        } else {
            timeout = t.time - now;
            break;
        }
    nevents = poll_function(events, timeout);
    for i in nevents:
        task t;
        if (events[i].type == READ) {
            t.handler = read_handler;
        } else { /* events[i].type == WRITE */
            t.handler = write_handler;
        }
        run_tasks_add(t);
}

FastCGI and PHP‑FPM Integration

NGINX does not execute external scripts directly; it forwards PHP requests to a FastCGI process manager (PHP‑FPM or spawn‑fcgi). The typical configuration uses a location ~ \.php$ block that sets fastcgi_pass , fastcgi_param SCRIPT_FILENAME , and includes fastcgi_params .

location ~ \.php$ {
    root html;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME /scripts$fastcgi_script_name;
    include fastcgi_params;
}

PHP‑FPM provides better performance and stability than spawn‑fcgi, offering process management, graceful reloads, and configurable limits (start_servers, max_children, rlimit_files, etc.).

Configuration and Optimization Tips

Set worker_processes to the number of CPU cores and bind workers to specific CPUs using worker_cpu_affinity .

Use worker_connections and worker_rlimit_nofile to increase the maximum concurrent connections.

Enable epoll (Linux) or kqueue (BSD) for efficient I/O.

Adjust TCP kernel parameters (e.g., net.ipv4.tcp_max_tw_buckets , net.core.somaxconn ) to handle high traffic.

Configure client_max_body_size , client_header_buffer_size , and large_client_header_buffers to avoid 400/413 errors.

Use gzip , expires , and open_file_cache to improve static content delivery.

Fine‑tune proxy and FastCGI buffers ( proxy_buffer_size , fastcgi_buffers ) to prevent incomplete responses.

Enable access log buffering ( access_log /var/log/nginx/access.log buffer=64k flush=5m; ) and rate limiting ( limit_conn , limit_req ) for security and performance.

Error Troubleshooting

400 Bad Request – increase client_header_buffer_size and large_client_header_buffers .

413 Request Entity Too Large – raise client_max_body_size and corresponding PHP post_max_size / upload_max_filesize .

502 Bad Gateway – check upstream service health, PHP‑FPM process count, and FastCGI timeout settings ( fastcgi_connect_timeout , fastcgi_read_timeout ).

504 Gateway Timeout – increase upstream timeouts or reduce backend processing time.

upstream sent too big header – enlarge proxy_buffer_size , proxy_buffers , or fastcgi_buffers .

Security Note

A known NGINX vulnerability allowed arbitrary files to be interpreted as PHP when cgi.fix_pathinfo was enabled. Mitigation includes disabling cgi.fix_pathinfo or adding a location rule that returns 403 for suspicious $fastcgi_script_name patterns.

Overall, understanding NGINX’s modular architecture, process model, and Linux kernel tuning enables administrators to build highly scalable, secure, and efficient web services.