Nginx Location Directive Explained

If you're familiar with web development, you've likely come across the popular web server software Nginx. Nginx has gained a lot of popularity in recent years due to its high performance, scalability, and flexibility. One of the features that make Nginx so versatile is its location directive.

Nginx location directives are essential when working with Nginx. They can be located within server blocks or other location blocks. This article will help explain how location directives are used to process the URI of client requests.

What is the Nginx location directive?

The Nginx location directive is used to specify different configuration blocks for different URLs or URIs. This means that you can configure Nginx to handle requests differently based on the URL or URI that is being requested.

The location directive can be used in two ways:

1. To specify a location block that matches a specific URL or URI
2. To specify a regular expression that matches multiple URLs or URIs

The location directive is used within the server block of the Nginx configuration file. Here's an example of how it might look:

server {
    listen       80;
    server_name  example.com;

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

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

    location ~ \.php$ {
        root           /var/www/html;
        fastcgi_pass   127.0.0.1:9000;
        fastcgi_index  index.php;
        fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include        fastcgi_params;
    }
}

In this example, we've defined three location blocks. The first location block matches any URL or URI that starts with a forward slash (/), which is essentially every URL or URI that will be requested. The second location block matches any URL or URI that starts with /images/. The third location block matches any URL or URI that ends with .php.

Regular expressions (RE) or literal strings can be used to define the modifier. If a modifier in present in the location block, this will change the way that Nginx matches the location block. The most important modifiers are:

• No modifier at all means that the location is interpreted as a prefix. To determine a match, the location will now be matched against the beginning of the URI.
• = The equal sign can be used if the location needs to match the exact request URI. When this modifier is matched, the search stops right here.
• ~ Tilde means that this location will be interpreted as a case-sensitive RE match.
• ~* Tilde followed by an asterisk modifier means that the location will be processed as a case-insensitive RE match.
• ^~ Assuming this block is the best non-RE match, a carat followed by a tilde modifier means that RE matching will not take place.

How does the Nginx location directive work?

When Nginx receives a request from a client, it will check the request URI against each location block in the order that they appear in the configuration file. The first location block that matches the request URI will be used to handle the request.

Let's take a closer look at our example configuration file to see how this works.

When Nginx receives a request for http://example.com/index.html, it will first check the request URI (/index.html) against the location block that starts with a forward slash (/). Since this location block matches any URL or URI, it will be used to handle the request. Nginx will use the root and index directives specified in this location block to serve the file /var/www/html/index.html.

If Nginx receives a request for http://example.com/images/logo.png, it will first check the request URI (/images/logo.png) against the location block that starts with /images/. Since this location block matches any URL or URI that starts with /images/, it will be used to handle the request. Nginx will use the root and index directives specified in this location block to serve the file /var/www/images/logo.png.

If Nginx receives a request for http://example.com/test.php, it will first check the request URI (/test.php) against the third location block that matches URLs or URIs that end with .php. Since this location block matches the request URI, it will be used to handle the request. Nginx will use the fastcgi_pass and fastcgi_param directives specified in this location block to execute the PHP script.

The process of choosing Nginx location blocks

For each request, Nginx goes through a process to choose the best location block that will be used to serve that request. Nginx does this by comparing the request URI against each location block that has been setup in the configuration. To achieve this, the following process is used:

• Prefix-based Nginx location matches (no regular expression). Each location will be checked against the request URI.
• Nginx searches for an exact match. If a = modifier exactly matches the request URI, this specific location block is chosen right away.
• If no exact (meaning no = modifier) location block is found, Nginx will continue with nonexact prefixes. It starts with the longest matching prefix location for this URI, with the following approach:
  • In case the longest matching prefix location has the ^~ modifier, Nginx will stop its search right away and choose this location.
  • Assuming the longest matching prefix location doesn't use the ^~ modifier, the match is temporarily stored and the process continues.
• As soon as the longest matching prefix location is chosen and stored, Nginx continues to evaluate the case-sensitive and insensitive regular expression locations. The first regular expression location that fits the URI is selected right away to process the request.
• If no regular expression locations are found that match the request URI, the previously stored prefix location is selected to serve the request.

Examples of Nginx location directives

The following section provides a few examples of Nginx location blocks using a combination of modifiers and location match directives. These examples can be used in your own Nginx configuration and can be modified to suit your needs.

location  = / {
    # Only matches the / query.
}

location /data/ {
    # Any query beginning with /data/ but the process continues searching.
    # Will only be matched if regular expressions don't find a match.
}

location ^~ /img/ {
    # Queries beginning with /img/ and then stops searching.
}

location ~* .(png|gif|ico|jpg|jpeg)$ {
    # Matches requests ending in png, gif, ico, jpg or jpeg.
    # Any request to the /img/ directory are handled by the location block above.
}

Example how to prevent hotlinking of images:

location ~ .(png|gif|jpe?g)$ {
    valid_referers none blocked yourwebsite.com *.yourwebsite.com;
    if ($invalid_referer) {
        return   403;
    }
}

Reject scripts inside writable directories:

location ~* /(media|images|cache|tmp|logs)/.*.(php|jsp|pl|py|asp|cgi|sh)$ {
    return 403;
}

For more details and examples pertaining to the Nginx location directive, visit the official Nginx website.

Nginx location directive best practices

When using the Nginx location directive, there are a few best practices to keep in mind.

Order of location blocks

The order of location blocks is important because Nginx will use the first location block that matches the request URI to handle the request. Make sure to order your location blocks in a way that makes sense for your application.

Specificity of location blocks

Be as specific as possible with your location blocks to ensure that Nginx is using the correct configuration directives for each request. For example, if you have a location block that matches /user/123 and a location block that matches /user/(.), make sure that the /user/123 location block is listed before the /user/(.) location block.

Regular expression performance

Be careful when using regular expressions in your location blocks, as they can be slower than exact or prefix matches. If possible, use exact or prefix matches instead of regular expressions to improve performance.

Conclusion

The Nginx location directive is a powerful tool that allows you to specify different configuration blocks for different URLs or URIs. By understanding how the location directive works and following best practices, you can ensure that your Nginx configuration is efficient and effective. Remember to order your location blocks correctly, be as specific as possible, and use regular expressions sparingly to improve performance. With these tips in mind, you can take advantage of the flexibility and versatility that Nginx has to offer.