# 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:**

```nginx
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:**

```nginx
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:**

```nginx
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:**

```nginx
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:**

```nginx
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:**

```nginx
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:**

```nginx
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:**

```nginx
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

{% code fullWidth="true" %}

```nginx
###############################################################################
# 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;
    }
}

```

{% endcode %}

***

### **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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wisdom.gitbook.io/gyan/nginx/deep-dive-on-nginx-configuration-blocks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.