Important Nginx Location Directive Modifiers

Nginx is a powerful web server that can be used to handle a variety of different types of web requests. As you may be aware, Nginx separates configuration into the blocks of the server, which is useful for working in a hierarchical fashion. The “location” directive found inside the server block of Nginx, which facilitates handling various requests based on the URL that the client entered and directing them to certain locations in the file system, is one of the most essential components of the web server.

In this article, we will look at different examples of how to use the Nginx location directive modifiers to handle different types of requests in Nginx.

Prerequisites

To use the Nginx location directive we need to install Nginx in our system. I’m assuming, in this article that Nginx is already installed on your system. If not you can refer to my previous article regarding Nginx Best Practices on Initial Setup.

Nginx Location Directive Syntax

The Nginx location block can be inserted inside another location block or a server block, as I described earlier. Primarily, the location directive syntax contains a modifier and location_match sections. Below shows the general structure of an Nginx location block.

Note: The modifier is optional and the location_match below defines what will be checked against the request URI.

server {
    location [modifier] [location_match] {
      ...
      ...
    }
}

Having a modifier in the location block will change the way that Nginx matches the request URI differently. The most important modifiers are:

• No modifiers: The requested URI will be matched against the beginning of the requested URI to determine a correct match.
• = : The equal sign is used to match a location block exactly against a requested URI. When this modifier is matched, the search stops right here.
• ~ : The tilde sign is used for case-sensitive regular expression match against a requested URI.
• ~* : The tilde followed by an asterisk sign is used for case-insensitive regular expression match against a requested URI.
• ^~ : The tilde led by the carat sign is used to perform the longest non-regular expression match against the requested URI. If the requested URI hits such a location block, no further matching will takes place.

Nginx Location Directive Processing Order

For each request, Nginx goes through the following steps to choose the best location block against the URI which was requested.

1. The Nginx starts with looking for an exact match. If a = modifier exactly matches the request URI, this specific location the block is served right away.
2. If there are no such exact location blocks (meaning no = modifier), then Nginx will proceed to match the longest non-exact prefixes. Once it determines the longest prefix location that matches the request’s URI, then it will perform the following evaluations:
   • If the longest matching prefix location has the ^~ modifier, Nginx will stop its search right away and choose this location.
   • If the longest matching prefix location doesn’t contain the ^~ modifier, then it will store the match temporarily and it will proceed for the following steps as follows.
3. Now Nginx will continue to evaluate the case-sensitive and case-insensitive regular expression locations which is containing ~ and ~* modifiers. If the first regular expression location that matches the URI is selected right away to process the request.
4. If there are no regular expressions found in the above step that can be matched against the requested URI, then the previously stored prefix location is selected to serve the request.

The order in which the location blocks are defined will determine how Nginx checks them, and the first match will be used to process the request.
It’s crucial to keep this in mind while organizing your location blocks and to exercise caution when using regular expressions because improperly written ones can result in unexpected behavior.

Examples of Nginx location Directives

To handle various requests, Nginx’s “location” directive can be combined with a wide range of alternative matching patterns. Here are a few examples of location blocks used in Nginx that combine modifiers and location match directives. You can adapt these examples to meet your needs and use them in your own Nginx configuration.

Matching all Requests

In the following example, the location without any modifier with prefix location / will match all requests but that will be used as a last resort if no best matches are searched then.

location / {
    ...
}

The example below will match all requests made in the location block that begins with “/images/” and will then look for a more specific match against the requested URI. The location block will be chosen directly if Nginx does not look for a more specific match.

The location block will be the selection to respond to a URI of a request in the form of /images, /images/site/logo.png, or /images/logo.png.

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

Exact Match

Nginx first tries to match the most specific prefix location. Therefore, the equal sign (“=”) in the following location block will exactly match the path requested and then stops searching for the rest of the matches.

location = /about {
    root /var/www/about;
}

In the above example, the ‘=’ location modifier will exactly match against the URL ‘/about‘. The URLs like ‘/about/index.html‘ or ‘/about/‘ will not match the condition.

Prefix Match

The modifier caret-tilda (^~) is used to perform the case-sensitive regular expression match against the requested URL. Therefore, if the matching URI will be matched in the /images or /images/logo.png, but it stops searching as soon as a match is found.

location ^~ /images/ {
    root /var/www/images;
}

Case-Sensitive Regular Expression Match

The modifier tilda (~) in the following location block performs in a case-sensitive regular expression match against the requested URI and doesn’t stop searching for a better match.

For example, the following block could not handle requests for /logo.PNG. However, it will handle requests for /logo.png.

location ~ \.(png|gif|ico|jpg|jpeg)$ {
    root /var/www/images;
}

Case-Insensitive Regular Expression Match

The modifier tilde sign with an asterisk (~*) in the following location block results in a case-insensitive regular expression match but the searching doesn’t stop here for a better match. In this case, the block could handle both /logo.png and /logo.PNG.

location ~* \.(png|gif|ico|jpg|jpeg)$ {
    root /var/www/images;
}

Conclusion

When dealing with Nginx, the location directives modifiers are crucial and very helpful as it enables you to handle various request types based on the URL that the client has requested. We can set up Nginx to handle a range of requests and offer required content by utilizing various matching patterns and directives. You can quickly start using Nginx location directives by following the examples mentioned in this article.

Further, you can test out if your location directives are working as expected with the given URL using this link.