> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nginx Overview

> Overview of NGINX configuration, nginx.conf structure, server blocks, directory layout, modules, and essential administration commands and operational tips for managing NGINX on Linux systems

This guide covers the essential NGINX configuration concepts, important files and directories, and the most useful commands for administering NGINX on Linux systems. It focuses on the primary configuration file (`nginx.conf`), how server blocks (virtual hosts) are structured, and practical operational tips for testing and reloading configurations.

Let's dive into `nginx.conf`, the main configuration file typically located at `/etc/nginx/nginx.conf` on most Linux distributions. The file is organized into a few top-level sections:

* Global settings — directives that affect the entire NGINX process (user, worker processes, PID file, etc.).
* `events` block — controls connection handling and the event model.
* `http` block — top-level container for HTTP-related configuration (server blocks, compression, logging, MIME types, timeouts).
* `server` blocks — virtual hosts that define how NGINX should respond to requests for specific domains or IPs.

![A slide-style infographic titled "Structure of nginx.conf" showing a "Global Settings" box linked to the note "Set up configurations that affect the entire Nginx server." Below are icons and labels for user privileges, number of worker processes, and rate limiting settings.](https://mintcdn.com/kodekloud-c4ac6d9a/ij3FNIPjp1w0Myd0/images/Nginx-for-Beginners/Install-Config/Nginx-Overview/nginx-conf-structure-global-settings-infographic.jpg?fit=max\&auto=format\&n=ij3FNIPjp1w0Myd0\&q=85\&s=5e4058cd09d0b5679163c81717932362)

## Global settings

Global directives typically appear at the top of `nginx.conf`. Example:

```nginx theme={null}
user www-data;
worker_processes auto;
pid /run/nginx.pid;
```

* `user` — the system user NGINX worker processes run as (e.g., `www-data` on Debian/Ubuntu or `nginx` on CentOS/RHEL).
* `worker_processes` — number of worker processes. Use `auto` to let NGINX select based on CPU cores.
* `pid` — path to the master process PID file used for signaling (reloads, stops).

## Events block

The `events` block configures connection handling and should align with `worker_processes`. The theoretical maximum simultaneous connections is approximately `worker_processes * worker_connections`.

```nginx theme={null}
events {
    worker_connections 1024;
    # optionally: use epoll; use kqueue on BSD/macOS
    # use epoll;
}
```

Example: if `worker_processes` is 4 and `worker_connections` is 1024, the theoretical maximum is 4 \* 1024 = 4096 simultaneous connections.

## HTTP block

The `http` block contains settings for logging, compression, timeouts, MIME types, and includes for server blocks. It pulls together shared directives used across virtual hosts.

```nginx theme={null}
http {
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    gzip on;

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

    keepalive_timeout 65;
    types_hash_max_size 2048;

    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # Server blocks (virtual hosts) and additional configs
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}
```

Note: `include` directives are how `nginx.conf` pulls in server block files and configuration snippets. This modular approach keeps the main config clean and allows per-site or per-feature configs.

## Server blocks (virtual hosts)

Server blocks are NGINX’s virtual host mechanism. They tell NGINX how to handle requests for particular domains, IPs, and ports. You can host multiple sites on one server by defining multiple server blocks.

![A slide titled "Creating and Editing Server Blocks (Virtual Hosts)" showing a user icon sending a "Request" to an NGINX logo. Below are labels for "server\_name" and "IP address" implying virtual host configuration.](https://mintcdn.com/kodekloud-c4ac6d9a/ij3FNIPjp1w0Myd0/images/Nginx-for-Beginners/Install-Config/Nginx-Overview/nginx-server-blocks-virtual-hosts.jpg?fit=max\&auto=format\&n=ij3FNIPjp1w0Myd0\&q=85\&s=4ba9e33b775e433060225e1b42d0dd1c)

Example simple server block:

```nginx theme={null}
server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/example.com/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}
```

Key directives:

* `listen` — IP and/or port to listen on (commonly `80` for HTTP and `443` for HTTPS).
* `server_name` — domain(s) or hostnames this block responds to (used to match incoming `Host` headers).
* `root` — directory from which files are served for this server block.
* `index` — default index file(s) for directory requests.
* `location /` — location block for the site root. `try_files $uri $uri/ =404;` checks the filesystem and returns `404` if no match.

Notes on `try_files`:

* `$uri` and `$uri/` are built-in variables representing the requested path and the path treated as a directory.
* The `=404` fallback instructs NGINX to return an HTTP 404 status if a file or directory isn't found.

## NGINX modules

NGINX functionality is implemented via modules (core, HTTP, stream, etc.). Each module exposes directives you can use in configuration files. Refer to the official module documentation when adding features like caching, rewriting, proxying, or load balancing.

![A presentation slide titled "Nginx Modules" showing a screenshot of the ngx\_http\_core\_module documentation — a long list of directives and links in a rounded, bordered box with the NGINX logo. The slide also includes a small "© Copyright KodeKloud" credit.](https://mintcdn.com/kodekloud-c4ac6d9a/ij3FNIPjp1w0Myd0/images/Nginx-for-Beginners/Install-Config/Nginx-Overview/nginx-modules-ngx-http-core-docs.jpg?fit=max\&auto=format\&n=ij3FNIPjp1w0Myd0\&q=85\&s=42c8c3fea5b17d352b129f685cf59682)

## Directory structure and important files

Common paths (Debian/Ubuntu layout shown):

| Path | Purpose |
| - | - |
| `/etc/nginx/nginx.conf` | Main configuration file |
| `/etc/nginx/sites-available/` | Store site (server block) config files |
| `/etc/nginx/sites-enabled/` | Symlinks to enabled site configs from `sites-available` |
| `/etc/nginx/conf.d/` | Additional config fragments (SSL, upstreams, shared snippets) |
| `/var/www/` | Website files (e.g., `/var/www/example.com/html`) |
| `/usr/share/nginx/html` | Alternative website root on some distributions (CentOS/RHEL) |
| `/etc/nginx/mime.types` | MIME type mappings |
| `/run/nginx.pid` or `/var/run/nginx.pid` | Master process PID file |
| `/var/log/nginx/` | Access and error logs |

![A slide titled "Directory Structure and Important Configuration Files" that lists Nginx config paths and short descriptions. It shows /etc/nginx/nginx.conf (main config), /etc/nginx/sites-available (site/virtual host configs), /etc/nginx/sites-enabled (symlinks to enabled sites) and /etc/nginx/conf.d (additional config files).](https://mintcdn.com/kodekloud-c4ac6d9a/ij3FNIPjp1w0Myd0/images/Nginx-for-Beginners/Install-Config/Nginx-Overview/nginx-config-paths-directory-structure.jpg?fit=max\&auto=format\&n=ij3FNIPjp1w0Myd0\&q=85\&s=606c04d93628f65afd5be27f93799672)

Administration tips:

* Place site configs in `sites-available/` and enable them by creating a symlink in `sites-enabled/` (this pattern mirrors Apache’s `a2ensite` workflow).
* Use `conf.d/` for smaller reusable fragments or service-specific configuration (e.g., load balancing, SSL snippets).
* Verify your website document root (e.g., `/var/www/`) and permissions when troubleshooting file serving issues.

## Essential NGINX commands

Below are the most common NGINX commands for checking version, testing configuration, and sending signals to the master process.

| Command | Purpose |
| - | - |
| `nginx -h` | Show help and options |
| `nginx -v` | Print NGINX version |
| `nginx -V` | Show version plus compile-time options and modules |
| `nginx -t` | Test configuration for syntax errors |
| `nginx -T` | Dump full merged config to stdout and test |
| `nginx -s signal` | Send a signal to the master process (e.g., `reload`, `stop`) |

Examples:

Test configuration syntax:

```bash theme={null}
sudo nginx -t
```

Expected success output:

```text theme={null}
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
```

Apply config changes safely:

1. Edit or add config files (e.g., create a site in `/etc/nginx/sites-available`).
2. Test configuration:

```bash theme={null}
sudo nginx -t
```

3. If the test passes, reload NGINX to apply changes without dropping connections:

```bash theme={null}
# Option A: NGINX signal-based reload
sudo nginx -s reload

# Option B: systemd-based reload on systems using systemd
sudo systemctl reload nginx
```

### Reload vs restart

* `reload` (recommended) tells NGINX to re-open files and apply config changes without stopping the master process — less disruptive to active connections.
* `restart` stops and then starts the service; it can briefly interrupt active connections.

Always run `sudo nginx -t` (or `sudo nginx -T` when you need the full merged configuration) before reloading NGINX. This prevents applying invalid configurations that would break the web server.

## Common diagnostic commands

* Check service status:

```bash theme={null}
sudo systemctl status nginx
```

* Follow logs in real time:

```bash theme={null}
# Access log (HTTP requests)
sudo tail -f /var/log/nginx/access.log

# Error log (errors and warnings)
sudo tail -f /var/log/nginx/error.log
```

Use `nginx -T` to produce the full merged configuration when you need to share or debug the exact configuration NGINX is using (after includes and merges). This is especially useful when support teams ask for a complete configuration dump.

## Summary

* `nginx.conf` is organized into Global settings, `events`, `http`, and `server` blocks.
* Use `sites-available` and `sites-enabled` to manage virtual hosts; use `conf.d/` for reusable fragments.
* Test changes with `nginx -t` (or `nginx -T` for full config) before reloading.
* Prefer `reload` to apply configuration changes without downtime.
* Check `/var/log/nginx/` for access and error logs when troubleshooting.

## Links and references

* Official NGINX documentation: [https://nginx.org/en/docs/](https://nginx.org/en/docs/)
* NGINX configuration guide: [https://nginx.org/en/docs/beginners\_guide.html](https://nginx.org/en/docs/beginners_guide.html)
* [Kubernetes Basics](https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/) (if deploying behind Kubernetes Ingress controllers)

That wraps up this overview of NGINX configuration, directory structure, and essential commands.

> **[Watch Video](https://learn.kodekloud.com/user/courses/nginx-for-beginners/module/0de43784-b08d-4ce0-8470-a7541b78fe58/lesson/7b0d11fb-1a0d-4765-a49d-8b9ec4d97b11)**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.