nginx.conf

The nginx.conf file is the primary configuration file for the Nginx web server.

What nginx.conf Controls

The nginx.conf file defines how the Nginx web server handles incoming connections, routes requests, serves files, and communicates with upstream backends. Every server block, location block, SSL/TLS certificate path, logging directive, and proxy rule lives in this file or in files it includes.

Nginx reads nginx.conf once at startup and again on each reload signal. A syntax error in nginx.conf prevents Nginx from starting or reloading. Run nginx -t to validate the configuration before applying changes.

Default Location of nginx.conf

The nginx.conf file resides at /etc/nginx/nginx.conf on most Linux distributions. Other possible locations depend on the installation method:

• /usr/local/nginx/conf/nginx.conf-- compiled from source
• /usr/local/etc/nginx/nginx.conf-- macOS (Homebrew)

nginx.conf File Structure

The nginx.conf file organizes directives into nested contexts. Each context controls a different scope of Nginx behavior.

Main Context

The main context sits at the top level of nginx.conf, outside all block directives. Directives in the main context control process-level behavior for the entire Nginx instance. Key directives include worker_processes, user, error_log, and pid.

user www-data;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

Events Context

The events context configures how Nginx handles network connections at the system level. The worker_connections directive sets the maximum number of simultaneous connections each worker process can handle.

events {
    worker_connections 1024;
    multi_accept on;
}

HTTP Context

The http context contains all configuration for HTTP and HTTPS traffic. Server blocks, upstream blocks, and shared directives such as log_format, gzip, and include reside inside the http context.

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    sendfile on;
    keepalive_timeout 65;

    include /etc/nginx/conf.d/*.conf;
}

Server Context

The server context defines a virtual host that responds to requests matching a specific domain name or IP address. Each server block specifies a listen port, a server_name, and a document root. Multiple server blocks can exist inside the http context.

server {
    listen 80;
    server_name example.com;
    root /var/www/example.com;
    index index.html;
}

Location Context

The location context matches a specific URI pattern within a server block. Nginx evaluates location blocks to determine proxy rules, access restrictions, caching headers, and file-serving behavior for each request path.

location /api/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
}

Core Concepts of nginx.conf

Directives and Blocks in nginx.conf

The nginx.conf file uses two types of directives. Simple directives consist of a name, parameters, and a terminating semicolon. Block directives group related simple directives inside curly braces { } and create a new context.

# Simple directive
server_tokens off;

# Block directive
server {
    listen 80;
    server_name example.com;
}

Directive Inheritance in nginx.conf

Nginx inherits directives from parent contexts to child contexts. A directive set in the http context applies to all server and location blocks unless a child block overrides it. This inheritance reduces duplication in large configurations.

The include Directive in nginx.conf

The nginx.conf include directive loads external configuration files into the current context. Most package-managed Nginx installations split server blocks into separate files under /etc/nginx/conf.d/ or /etc/nginx/sites-enabled/ and include them from the main nginx.conf file.

Common Configuration Tasks

nginx.conf Troubleshooting