NGINX Location Directives: A Comprehensive Guide

Navigating the world of NGINX, a popular open-source web server, can often be complex without a proper understanding of its various elements. One such pivotal component that plays a crucial role in routing requests to the correct location within your filesystem is the NGINX location directive. This guide aims to provide a comprehensive look at NGINX location directives, aiming to empower you with the knowledge to utilize them effectively in your configuration.

Table of Contents

Prerequisites

This tutorial assumes that you already have NGINX installed on your system. It is a fundamental prerequisite as the location directives are a part of the NGINX configuration, hence requiring an operational instance of NGINX.

Understanding the NGINX Location Directive Syntax

A location block in NGINX can be nested within a server block or even within another location block, subject to certain restrictions. Here’s the basic syntax for constructing a location block:

location [modifier] [URI] {
  ...
  ...
}

The modifier in the location block, while optional, offers a way to customize how NGINX interacts with the URL. Some of the most frequently used modifiers are:

none: In the absence of a modifier in a location block, the requested URI is matched against the start of the requested URI.
= : This is used for an exact match between the location block and the requested URI.
~ : This is employed for a case-sensitive regular expression match against a requested URI.
~ :* This is for a case-insensitive regular expression match against a requested URI.
^~ : This is used for the longest non-regular expression match against a requested URI. When a requested URI hits such a location block, no further matching occurs.

How Does NGINX Choose a Location Block?

A location can be defined using either a prefix string or a regular expression. Case-insensitive regular expressions are denoted by a preceding “*” modifier, while the “” modifier signifies case-sensitive regular expressions. To find a location match for a URI, NGINX first scans the locations defined using prefix strings (without regular expressions). Following this, locations with regular expressions are checked in the order of their declaration in the configuration file.

NGINX follows these steps to select a location block against a requested URI:

NGINX begins by seeking an exact match specified with location = /some/path/. If a match is found, this block is served right away.
If no exact location blocks are found, NGINX proceeds to match the longest non-exact prefixes. If a match is found where the ^~ modifier is used, NGINX halts its search. The matched location block is then selected to serve the request.
If the matched longest prefix location doesn’t contain the ^~ modifier, this match is stored temporarily and the process moves to the next steps.
NGINX then shifts its search to location blocks containing the ~ and ~* modifiers, selecting the first location block that matches the requested URI.
If no location is found in the above step, the previously stored prefix location is used to serve the request.

Delving into NGINX Location Block Examples

Below, we delve into various examples of NGINX location blocks using different modifiers and URIs.

Handling All Requests in NGINX

In our first example, we illustrate the use of the root location block /, which acts as a catch-all for any requests that do not find a match elsewhere in the configuration.

location / {
    ...
}

The preceding location block serves as a safety net, stepping in to handle any requests that have not been matched by any other location blocks. Although it technically matches all requests, it will only be invoked as a last resort, if no other matches are found.

Mapping an Exact URL in NGINX

NGINX operates on a strategy that prioritizes the most specific prefix location during its search process. Let’s explore how to leverage this behavior with an equal sign (=) modifier in a location block:

location = /images { 
    ...
}

This location block will match exactly with the URL https://domain.com/images. However, it’s worth noting that this will not match the URLs https://domain.com/images/index.html or https://domain.com/images/, as the = modifier requires an exact match, and does not account for additional URI elements.

NGINX Location Block for Directory Matching

The following example showcases a location block that matches any request starting with /images/, but doesn’t stop the search for more specific blocks pertaining to the requested URI:

location /images/ {
     ...
     ...
}

This location block represents a balance between specificity and flexibility. It will match any request beginning with /images/, but it doesn’t preclude the possibility of finding more specific matches. If NGINX fails to find any more specific matches, this location block is selected to handle the request.

NGINX Location Block: Case-Sensitive Regular Expression

The ^~ modifier in the following location block allows for a case-sensitive regular expression match:

location ^~ /images {
   ...
   ...
}

In this example, the URIs /images or /images/logo.png will be matched. However, the ^~ modifier ensures that the search ceases as soon as a match is found, thus enhancing the efficiency of the configuration.

NGINX Location Block for Specific File Types

The ~* modifier in the following location block is designed to match (in a case-insensitive manner) any request ending with a range of file extensions:

location ~* .(png|ico|gif|jpg|jpeg|css|js)$ {
    ...
    ...
}

This versatile block is especially useful for handling static assets, matching any request ending with the extensions png, ico, gif, jpg, jpeg, css, or js. Note, however, that any requests to the /images/ folder will be prioritized by any preceding location block.

NGINX Location Block: Case-Sensitive Regular Expression Match

The ~ modifier allows for a case-sensitive regular expression match, as shown in the following location block:

location ~ /images {
    ...
    ...
}

Unlike the ^~ modifier, the ~ modifier continues the search for a more specific match even after finding a match.

NGINX Location: Case-Insensitive Regular Expression Match Example

The ~* modifier can also be used to establish a case-insensitive regular expression match, as demonstrated in the location block below:

location ~* /images {
     ...
     ...
}

In this case, a match will be found irrespective of the case of the requested URI. However, similar to the previous case-sensitive example, the search will not cease, and NGINX will continue searching for a better match.

Adding a Fallback Location in NGINX

Sometimes, there might be a need to set up a default or fallback location. This can be achieved with the following configuration:

location = / {
    ...
    ...
}

This location block matches the root URL exactly and can be used as a default page or fallback location. For instance, it can serve a custom 404 error page if a requested page is not found.

Conclusion

Understanding the location directives of NGINX is essential for accurately tracing the endpoints of requested URIs within your filesystem. By examining the role of modifiers, the steps involved in selecting a location block, and various examples, this guide aims to provide a solid foundation for you to get started with location blocks in NGINX.

Remember, a correct and optimized configuration is the cornerstone of a robust and efficient NGINX deployment. This knowledge will enable you to create configurations tailored to your needs and requirements, further enhancing your proficiency in working with NGINX.

Share This Post: