Working with Configuration Structure

1. Understanding Main Context

Directive	Description	Scope	Example
main	Top-level context for global settings	Global	`user nginx;`
http	Context for HTTP server configuration	Global	`http { include /etc/nginx/mime.types; }`
server	Context for virtual host configuration	HTTP	`server { listen 80; }`
location	Context for URL path matching and handling	Server	`location / { root /var/www; }`

Note: The context hierarchy in Nginx is crucial for proper configuration. Each block defines a scope where specific directives can be applied.

2. Locating Configuration Files

File	Location	Description
nginx.conf	`/etc/nginx/nginx.conf`	Main Nginx configuration file
conf.d/*.conf	`/etc/nginx/conf.d/`	Directory for additional configuration files
sites-available/*.conf	`/etc/nginx/sites-available/`	Available site configurations (often symlinked to sites-enabled)
sites-enabled/*.conf	`/etc/nginx/sites-enabled/`	Enabled site configurations (symlinks to sites-available)
ssl/*.conf	`/etc/nginx/ssl/`	SSL/TLS configuration files (if used)

Example: Default nginx.conf location

ls -l /etc/nginx/nginx.conf

Note: The exact paths may vary depending on the OS and installation method (e.g., package manager vs. compiled from source).

3. Using Include Directive

Directive	Description	Usage
include	Includes configuration from another file	`include /path/to/config/file.conf;`

Example: Including a Server Block Configuration

server {
    listen 80;
    server_name example.com;
    include /etc/nginx/conf.d/ssl.conf;
    include /etc/nginx/conf.d/logging.conf;
}

Note: The include directive can be used at any level of the Nginx configuration hierarchy, including inside http, server, and location blocks.

Warning: If the included file does not exist or cannot be read, Nginx will log an error and fail to start.

4. Organizing Configuration Files

Example: Main nginx.conf structure

# Main nginx.conf
user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log;
pid        /run/nginx.pid;

include /etc/nginx/modules-enabled/*.conf;

events {
    worker_connections  1024;
}

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

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

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

    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

Directive	Description	Usage
http	Defines HTTP server configuration block	Required for HTTP handling
include	Includes other configuration files	Used to modularize config
worker_processes	Number of worker processes	Set to `auto` for optimal performance
error_log	Log file for errors	Set to `/var/log/nginx/error.log`
pid	Path to PID file	Set to `/run/nginx.pid`

Configuration Organization Best Practices

Use include directives to split configuration into manageable files
Keep main nginx.conf minimal and focused on global settings
Use /etc/nginx/conf.d/ for server blocks and HTTP settings
Use /etc/nginx/sites-enabled/ for site-specific configurations
Use /etc/nginx/modules-enabled/ for module loading

Note: The include directive supports wildcards like *.conf to load multiple files.

Steps to Organize Configuration Files

Create a directory structure like /etc/nginx/conf.d/ and /etc/nginx/sites-enabled/
Move server blocks to /etc/nginx/conf.d/ or /etc/nginx/sites-enabled/
Use include in the main nginx.conf to load these files
Test configuration with nginx -t
Reload Nginx with systemctl reload nginx

5. Setting Global Directives

Directive	Description	Values	Default
user	Sets the user and group for worker processes	`user` `group`	nobody
worker_processes	Number of worker processes	`auto`, `number`	1
error_log	Path to error log file	`path`	logs/error.log
pid	Path to PID file	`path`	logs/nginx.pid
worker_connections	Max number of connections per worker	`number`	512
worker_rlimit_nofile	Maximum number of file descriptors	`number`	unlimited

Example: Setting Global Directives

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

events {
    worker_connections 1024;
}

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

6. Configuring Events Block

Directive	Values	Description
worker_connections	`1024`	Maximum number of simultaneous connections that can be opened by a worker process
multi_accept	`on` \| `off`	Allow the worker process to accept multiple connections at once (default: `off`)
use	`epoll` \| `kqueue` \| `select`	Event model to use for handling connections (default: `epoll` on Linux)

Example: Basic Events Block Configuration

events {
    worker_connections 1024;
    multi_accept on;
    use epoll;
}

7. Understanding Configuration Hierarchy

Level	File	Description
Main	`nginx.conf`	Primary configuration file; includes main context and global settings
HTTP	`nginx.conf`	Contains `http` block with server and location blocks
Server	`nginx.conf`	Defines virtual hosts; can include `server` blocks inside `http`
Location	`nginx.conf`	Matches URI paths; can be inside `server` or `http`
Include	`nginx.conf`	Allows modularization; includes external config files using `include`

Example: Configuration Hierarchy

# Main context
user nginx;
worker_processes auto;

# HTTP context
http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    # Server context
    server {
        listen       80;
        server_name  example.com;

        # Location context
        location / {
            root   /var/www/html;
            index  index.html;
        }
    }
}

Note: The configuration hierarchy is processed in a top-down manner, with each level inheriting and extending settings from its parent.

8. Using Configuration Variables

Variable	Definition	Usage	Notes
variables_hash_bucket_size	`128`	Size of hash bucket for variables	Must be set before any variable definitions
variables_hash_max_size	`1024`	Maximum size of hash table for variables	Controls memory usage for variable storage

Example: Defining and Using Variables

server {
    set $my_var "Hello World";
    location / {
        echo $my_var;
    }
}

Example: Using Variables in Conditions

server {
    set $user_agent $http_user_agent;
    if ($user_agent ~ "MSIE") {
        return 403;
    }
}

Note: Variables in Nginx are evaluated at runtime and can be used in various contexts like location blocks, conditions, and proxy headers.

9. Commenting Configuration

In Nginx configuration files, comments are used to document and explain the purpose of various directives and blocks. Comments start with the # character and extend to the end of the line.

Feature	Description	Example
Comment Syntax	Comments begin with `#`	`# This is a comment server { listen 80; # Server name configuration server_name example.com; }`
Multiline Comments	Each line must start with `#`	`# This is the first line of a comment # This is the second line of a comment`

Example: Using Comments in Nginx Config

# Define the server block for example.com
server {
    # Listen on port 80 for HTTP requests
    listen 80;
    
    # Set the server name
    server_name example.com;

    # Redirect all traffic to HTTPS
    return 301 https://$server_name$request_uri;
}

10. Splitting Configuration into Modules

Directive	Description	Usage
include	Includes configuration from another file	`include /etc/nginx/conf.d/*.conf;`
http	Defines HTTP server configuration blocks	`http { ... }`
server	Defines a virtual server configuration	`server { ... }`
location	Defines how to handle requests based on URI	`location / { ... }`

Example: Including a Module

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

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

Example: Server Configuration Module

server {
    listen 80;
    server_name example.com;

    location / {
        root /var/www/html;
        index index.html;
    }
}

11. Validating Configuration Syntax

Example: Basic syntax validation

nginx -t

Example: Test with specific config file

nginx -t -c /etc/nginx/custom.conf

Option	Values	Description
-t	`boolean`	Test the configuration file for syntax errors
-c	`path`	Specify the path to the configuration file to test
-g	`directive`	Set global directives (e.g., `daemon off;`)

Note: If the configuration is valid, Nginx will output nginx: the configuration file /etc/nginx/nginx.conf syntax is ok and nginx: configuration file /etc/nginx/nginx.conf test is successful.

Warning: Invalid configurations will cause Nginx to report syntax errors and refuse to reload or start.

12. Understanding Directive Inheritance

Directive	Context	Inheritance Behavior	Notes
listen	server, stream	Inherited by `location` blocks	Can be overridden in `location` blocks
root	http, server, location	Inherited by nested contexts	Overrides parent `root` in child blocks
index	http, server, location	Inherited by nested contexts	Can be overridden in `location` blocks
access_log	http, server, location	Inherited by nested contexts	Can be disabled with `off`
error_log	http, server, location	Inherited by nested contexts	Can be overridden with different log levels
client_max_body_size	http, server, location	Inherited by nested contexts	Can be overridden in `location` blocks

Example: Inheritance in Action

http {
    client_max_body_size 10M;
    server {
        listen 80;
        root /var/www;

        location /api {
            # Inherits client_max_body_size from http block
            # Inherits root from server block
        }

        location /static {
            # Inherits client_max_body_size from http block
            root /var/static;
            # Overrides root from server block
        }
    }
}

Note: Directive inheritance follows a hierarchical structure where child contexts can override parent settings. The location context is particularly important as it can override directives from parent contexts.

Key Points

Directives are inherited from parent contexts in a hierarchical structure.
Child contexts can override inherited directives with their own values.
Some directives like root, client_max_body_size, and access_log can be overridden at any level.
Understanding inheritance helps in managing configuration complexity and avoiding unintended behavior.