Deep Dive on NGINX Configuration Blocks

NGINX is a highly configurable web server and reverse proxy, and its power comes from its configuration blocks. These blocks define how requests are processed, connections are managed, and traffic is handled in various scenarios.

Here is the list of the configuration blocks :

• Main (Global) Context

• Events Block

• HTTP Block

• Server Block

• Location Block

• Upstream Block

• Mail Block (for email proxying)

• Stream Block (for TCP/UDP load balancing)

---

1. Main (Global) Context

The global or main context sets global directives for the entire NGINX process, including worker processes, error logging, and module loading. It is placed outside any specific block.

Key Directives in Main Context

Directive	Purpose
worker_processes	Defines the number of worker processes (usually set to auto in production).
error_log	Specifies the location and level of error logs.
pid	Defines the file where NGINX stores its process ID.
include	Allows importing additional configuration files.

Example:

worker_processes auto;         # Auto-detects CPU cores for optimal performance
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

Production Tip:

Set worker_processes auto; to utilize all available CPU cores.

---

2. Events Block

The events block configures how NGINX handles client connections.

Key Directives in Events Block

Directive	Purpose
worker_connections	Defines the max simultaneous connections per worker process.
multi_accept	Allows a worker to accept multiple new connections at once.
use	Specifies the event-driven model (e.g., epoll for Linux).

Final Example:

events {
    worker_connections 1024;   # Handles 1024 connections per worker
    multi_accept on;           # Accept multiple connections at once
    use epoll;                 # Use efficient event model (Linux)
}

Production Tip:

For high-traffic applications, increase worker_connections based on server resources.

---

3. HTTP Block

The HTTP block is where web server configurations, caching, compression, and proxy settings are defined.

Key Directives in HTTP Block

Directive	Purpose
sendfile	Enables optimized file transfers.
tcp_nopush	Reduces TCP overhead.
keepalive_timeout	Defines how long persistent connections stay open.
resolver	Specifies DNS resolvers for dynamic upstream handling. especially important when using domain names in upstream blocks. Here it will work as global for all
log_format	Customizes the access log format.
include	Include MIME types and other HTTP-level configurations.
client_max_body_size	Defines the maximum allowed size of the client request body.

Example:

http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    tcp_nopush      on;
    keepalive_timeout 65;
    
    client_max_body_size 16M;

    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" "$http_user_agent"';

    access_log /var/log/nginx/access.log main;

    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;
}

Production Tip:

Enable Gzip compression (gzip on;) to improve page load times.

---

4. Server Block

The server block defines individual virtual hosts that listen for incoming requests.

Key Directives in Server Block

Directive	Purpose
listen	Defines the port (e.g., 80 for HTTP, 443 for HTTPS).
server_name	Specifies domains for this server block.
root	Sets the root directory for static files.
index	Defines the default files to serve.
error_page	Customize the error responses.
resolver	Specifies DNS resolvers for dynamic upstream handling. especially important when using domain names in upstream blocks. Here it will work as server level not global.

Final Example:

server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/html;
    index index.html index.htm;
    
    resolver 10.0.0.2 ipv6=off valid=300s;
    resolver_timeout 5s;

    error_page 404 /404.html;
}

Production Tip:

Use separate server {} blocks for HTTP and HTTPS.

---

5. Location Block

The location block defines how specific request paths are handled.

Key Directives in Location Block

Directive	Purpose
location	Defines URL patterns for request handling.
proxy_pass	Forwards requests to an upstream server.
proxy_set_header	To farward header to upstream server
rewrite	Modifies request URIs dynamically.

Example:

location /api/ {
    proxy_pass http://backend_servers;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    
    rewrite ^/old/(.*)$ /new/$1 permanent;
}

Production Tip:

Use try_files $uri $uri/ =404; for serving static content.

---

6. Upstream Block

The upstream block defines backend servers for load balancing.

Key Directives in Upstream Block

Directive	Purpose
server	Specifies backend servers.
weight	Assigns load balancing priority.

Final Example:

upstream backend_servers {
    server backend1.example.com weight=2;
    server backend2.example.com;
}

Production Tip:

Use ip_hash; for session persistence.

---

7. Mail Block

The mail block enables NGINX to act as an email proxy.

Key Directives in Mail Block

Directive	Purpose
server	Defines mail servers.
protocol	Specifies email protocols (IMAP, POP3, SMTP).

Final Example:

mail {
    server {
        listen 143;
        protocol imap;
        server_name mail.example.com;
    }
}

Production Tip:

Secure email connections using SSL.

---

8. Stream Block

The stream block allows NGINX to handle TCP/UDP traffic (e.g., databases).

Key Directives in Stream Block

Directive	Purpose
proxy_pass	Forwards TCP/UDP traffic.
upstream	Defines backend servers.

Final Example:

stream {
    upstream db_servers {
        server db1.example.com:3306;
        server db2.example.com:3306;
    }

    server {
        listen 3306;
        proxy_pass db_servers;
    }
}

Production Tip:

For database connections, enable proxy_timeout to prevent idle disconnections.

Final Configuration Example

###############################################################################
# Global (Main) Context
###############################################################################
# These settings apply to the entire NGINX process.
worker_processes auto;                        # Auto-detects CPU cores for optimal performance.
error_log /var/log/nginx/error.log warn;        # Log errors with a level of 'warn' for production.
pid /var/run/nginx.pid;                         # Store the master process PID.

# Include additional configuration files (e.g., dynamic modules or custom settings).
include /etc/nginx/modules-enabled/*.conf;

###############################################################################
# Events Block
###############################################################################
# The events block configures how NGINX handles connections.
events {
    worker_connections 1024;                    # Maximum simultaneous connections per worker.
    multi_accept on;                            # Accept all new connections at once.
    use epoll;                                  # Use the epoll event model (recommended for Linux).
}

###############################################################################
# HTTP Block
###############################################################################
# This block manages web (HTTP/HTTPS) traffic.
http {
    # Include MIME types and set a default content type.
    include       mime.types;
    default_type  application/octet-stream;
    
    # File transfer and TCP optimizations.
    sendfile        on;
    tcp_nodelay     on;
    tcp_nopush      on;
    
    # Connection and request settings.
    keepalive_timeout 65;                       # Timeout for persistent connections.
    client_max_body_size 16M;                   # Maximum allowed size of client request bodies.
    
    # Logging configuration with custom variables.
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
                    'Request URI: $uri, Query: $query_string';
    access_log /var/log/nginx/access.log main;
    
    # Resolver settings to control DNS resolution.
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;
    
    ###############################################################################
    # Upstream Block
    ###############################################################################
    # Defines a group of backend servers for load balancing.
    upstream backend_servers {
        server backend1.example.com weight=2;   # Weighted balancing (backend1 gets double traffic).
        server backend2.example.com;
    }
    
    ###############################################################################
    # Server Block (HTTP)
    ###############################################################################
    # Defines virtual hosts for handling specific domain requests.
    server {
        listen 80 default_server;               # Listen on port 80 for HTTP traffic.
        server_name example.com www.example.com;  # Domain names this server responds to.
        
        root /var/www/example;                  # Root directory for static files.
        index index.html index.htm;             # Default files to serve.
        
        # Custom error page configuration.
        error_page 404 /404.html;
        location = /404.html {
            internal;                         # Ensure direct access is not allowed.
        }
        
        ###############################################################################
        # Location Blocks within Server
        ###############################################################################
        
        # Location block for static content.
        location /static/ {
            try_files $uri $uri/ =404;         # Check file existence, return 404 if not found.
        }
        
        # Location block for PHP processing using FastCGI.
        location ~ \.php$ {
            fastcgi_pass unix:/run/php/php7.4-fpm.sock;
            fastcgi_index index.php;
            include fastcgi_params;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        }
        
        # Location block for API proxying to upstream backend servers.
        location /api/ {
            proxy_pass http://backend_servers;
            proxy_set_header Host $host;        # Forward the original host header.
            proxy_set_header X-Real-IP $remote_addr;  # Forward client’s IP address.
            proxy_redirect off;                 # Disable automatic redirection.
        }
        
        # Example of URI rewrite for permanent redirection.
        location /old/ {
            rewrite ^/old/(.*)$ /new/$1 permanent;
        }
    }
    
    ###############################################################################
    # Additional Server Block (HTTPS Example)
    ###############################################################################
    # Demonstrates how to configure a secure server with SSL/TLS.
    server {
        listen 443 ssl;
        server_name secure.example.com;
        
        root /var/www/secure;
        index index.html index.htm;
        
        ssl_certificate /etc/nginx/ssl/secure.example.com.crt;
        ssl_certificate_key /etc/nginx/ssl/secure.example.com.key;
        
        # Example of HTTP basic authentication for sensitive areas.
        location /secure/ {
            auth_basic "Restricted Content";
            auth_basic_user_file /etc/nginx/.htpasswd;
        }
    }
}

###############################################################################
# Optional Mail Block
###############################################################################
# For email proxying (IMAP, POP3, SMTP). Uncomment and configure as needed.
# mail {
#     server {
#         listen     143;
#         protocol   imap;
#         server_name mail.example.com;
#         # Additional mail-specific directives go here.
#     }
# }

###############################################################################
# Optional Stream Block
###############################################################################
# For TCP/UDP load balancing (e.g., databases, other non-HTTP services).
stream {
    upstream db_servers {
        server db1.example.com:3306;
        server db2.example.com:3306;
    }
    
    server {
        listen 3306;
        proxy_pass db_servers;
    }
}

---

Conclusion

Each NGINX configuration block plays a crucial role in handling traffic efficiently. Understanding these blocks and their production best practices ensures a secure, scalable, and high-performance setup.

By applying these blocks correctly, you can optimize static content delivery, API routing, load balancing, email proxying, and database handling, making NGINX a powerful tool for any production environment.