Process Control and CLI Operations

Managing the Nginx web server involves interacting with the binary directly via the command line interface. On Windows systems, the service can be initiated simply by executing the binary.

start nginx

To Unix-like environments or when controlling an existing instance, various signals and flags are available to manage the lifecycle and validate configurations.

# Start the service with superuser privileges
sudo nginx

# Send signals to the master process
nginx -s reload   # Reload configuration files gracefully
nginx -s reopen   # Reopen log files
nginx -s stop     # Fast shutdown
nginx -s quit     # Graceful shutdown

# Validate configuration syntax
nginx -t

# General command structure
nginx [-?hvVtq] [-s signal] [-c filename] [-p prefix] [-g directives]

# Flag descriptions:
# -?,-h   : Display help menu
# -v      : Print version and exit
# -V      : Print version, compiler, and configure arguments
# -t      : Test configuration syntax without starting
# -q      : Suppress non-error messages during configuration test
# -s      : Send a signal (stop, quit, reopen, reload)
# -p      : Define the prefix path (default varies by installation)
# -c      : Specify a custom configuration file path
# -g      : Set global directives outside the config file

Server Blocck Configuration

Nginx allows routing traffic to different directories based on the requested URI. Within a server block, multiple location contexts can define specific root paths for different URL patterns.

server {
    listen       80;
    server_name  app.example.org;

    # Default location for the domain root
    location / {
        root   /var/www/public;
        index  index.html index.htm;
    }

    # Specific location for resource files
    location /resources {
        root   /srv/data/assets;
        index  index.html;
    }
}

It is critical to note how the root directive interacts with the location path. For the /resources block above, Nginx will append the request URI to the root path. Therefore, a request to /resources/image.png will look for the file at /srv/data/assets/resources/image.png. If the physical directory structure does not match this concatenation, the server will return a 404 Not Found error.

Location Matching Precedence

The core of Nginx routing lies in the location directive. The syntax supports modifiers that determine how the URI is compared against the defined pattern.

location [=|~|~*|^~] /uri/ { … }

• = : Performs an exact match. Only this specific URI will trigger the block.
• ^~ : Matches a prefix string. If this matches, regex checks are skipped.
• ~ : Case-sensitive regular expression match.
• ~* : Case-insensitive regular expression match.
• !~ : Case-sensitive negative regex match.
• !~* : Case-insensitive negative regex match.
• / : Standard prefix match (no modifier).

Execution Order and Priority

Nginx evaluates location blocks in a specific hierarchy to determine which configuration handles a request:

1. Exact Match: Blocks with = are checked first. If found, processing stops immediately.
2. Prefix Match with Skip: Blocks with ^~ are checked next. If the URI starts with this string, regex matching is bypassed.
3. Regular Expressions: Regex blocks (~ and ~*) are evaluated in the order they appear in the configuration file. The first match wins.
4. Standard Prefix: If no regex matches, the longest matching standard prefix (e.g., /images vs /) is selected.
5. Catch-all: The generic / block serves as the fallback.

Practical Matching Scenarios

Consider the following configuraton setup designed to handle health checks, static assets, and dynamic content:

location = /health {
    # Handler 1: Exact match for monitoring
}

location ^~ /static/ {
    # Handler 2: Prefix match for static assets, skips regex
}

location ~ \.(jpg|jpeg|gif|png)$ {
    # Handler 3: Case-sensitive image extension match
}

location ~* \.(webp|svg)$ {
    # Handler 4: Case-insensitive modern format match
}

location !~* \.log$ {
    # Handler 5: Negative match (unlikely to be used standalone)
}

location / {
    # Handler 6: Default fallback
}

Based on the hierarchy above, the routing behavior for specific requests would be:

• GET /health: Matches Handler 1 immediately due to exact match priority.
• GET /static/style.css: Matches Handler 2. Even though it might fit other patterns, the ^~ modifier stops further regex evaluation.
• GET /images/photo.JPG: Matches Handler 6. Handler 3 is case-sensitive and requires lowercase extensions. Handler 4 does not cover .JPG.
• GET /images/logo.PNG: Matches Handler 4. The ~* modifier allows case-insensitive matching for .png (if added to regex) or specifically .webp|.svg in this example. If the regex was \.png$ with ~*, it would match. In this specific config, .PNG falls to Handler 6 unless Handler 4 is adjusted to include png.
• GET /api/user/123: Matches Handler 6. No specific rules apply, so the request is passed to the default backend or root.
• GET /debug.log: Does not match Handler 5 because negative matches generally do not select a block for processing in this manner; it falls through to Handler 6.

When no specific location matches, Nginx typically proxies the request to an upstream application server such as PHP-FPM, Tomcat, or a Node.js instance, acting as a reverse proxy.