Skip to main content
Mapagam

Working with Location Blocks

1. Defining Location Block

Directive Values Description
location /, =, ~, ~*, ^~ Defines a location block with specific matching rules
location = /path Exact match, stops processing on match
location ~ /path/.* Case-sensitive regex match
location ~* /path/.* Case-insensitive regex match
location ^~ /path Prefix match, stops processing on match

Example: Basic Location Block

server {
    listen 80;
    server_name example.com;

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

Example: Exact Match Location Block

server {
    listen 80;
    server_name example.com;

    location = / {
        return 200 "Welcome to the homepage";
    }
}

2. Understanding Location Matching

Match Type Pattern Description Example
= = /exact/path Exact match. Only matches the exact path. 
location = / {
    return 200 'Exact match';
}
^~ ^~ /static/ Prefix match, stops location processing if matched. 
location ^~ /static/ {
    alias /var/www/static/;
}
~ ~ /case/sensitive/ Case-sensitive regex match. 
location ~ \.(jpg|jpeg|png)$ {
    expires 1y;
}
~* ~* /case/insensitive/ Case-insensitive regex match. 
location ~* \.(css|js)$ {
    expires 1y;
}
/ / Prefix match for any path, lowest priority. 
location / {
    return 200 'Default location';
}
Note: The = and ^~ types have higher priority than regex matches. The order matters for matching logic.

Example: Location Priority

location = / {
    return 200 'Exact match';
}

location ^~ /static/ {
    alias /var/www/static/;
}

location ~ \.(jpg|jpeg|png)$ {
    expires 1y;
}

3. Using Exact Match

Directive Values Description
location = /exact/path Matches the location exactly. No prefix or suffix matching.

Example: Exact Match Location Block

location = /login {
    return 200 "Exact match for login page";
}
Note: The = operator has the highest priority in location matching and is used for exact matches.

4. Using Prefix Match

Directive Description Example
location Defines a location block with prefix match location /api/ { ... }
location = Exact match (highest priority) location = /index.html { ... }
location ^~ Prefix match with highest priority (no regex) location ^~ /static/ { ... }

Example: Prefix Match Configuration

server {
    listen 80;
    server_name example.com;

    location /api/ {
        proxy_pass http://backend;
    }

    location ^~ /static/ {
        root /var/www;
    }
}
Note: Prefix matches are evaluated in order of declaration, and the most specific match wins.

5. Using Regex Match

Match Type Pattern Syntax Description Example
~ ~<em>pattern</em> Case-sensitive regex match location ~ \.php$ { ... }
~* ~*<em>pattern</em> Case-insensitive regex match location ~* \.(jpg|jpeg|png)$ { ... }
^~ ^~<em>prefix</em> Prefix match, stops regex processing location ^~ /static/ { ... }

Example: Case-sensitive regex match

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Example: Case-insensitive regex match

location ~* \.(jpg|jpeg|png|gif)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}
Note: Regex matches are processed in order of declaration, and the first match wins. Use ^~ to avoid regex processing for prefix matches.

6. Using Case-Insensitive Regex

Directive Usage Description
location ~* Case-insensitive regex match for location blocks

Example: Case-Insensitive Location Match

location ~* \.(jpg|jpeg|png|gif)$ {
    root /var/www/images;
}
Note: The ~* operator matches the location pattern case-insensitively. It is useful for handling file extensions or paths that may vary in case.

7. Understanding Location Priority

Location Block Match Type Priority Notes
location / prefix 1 Matches any URI starting with /
location = / exact 2 Matches exactly /
location ^~ /images/ prefix 3 Matches any URI starting with /images/ and stops searching
location ~ \.(gif|jpg|png)$ regex 4 Matches URIs ending with .gif, .jpg, or .png
location ~* \.(js|css)$ regex (case-insensitive) 5 Matches URIs ending with .js or .css (case-insensitive)

Example: Location Priority in Action

server {
    listen 80;
    server_name example.com;

    # This matches /images/test.jpg and stops further matching
    location ^~ /images/ {
        alias /var/www/images/;
    }

    # This would never be reached for /images/test.jpg
    location ~ \.(gif|jpg|png)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # This matches /test.jpg and is processed
    location ~* \.(js|css)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
Note: The ^~ modifier makes the location block a prefix match that stops further regex matching, even if a regex pattern would otherwise have higher priority.

8. Using Preferential Prefix

Directive Description Example
location Defines a location block with a preferential prefix 
location = / {
    return 200 'Exact match';
}
location Defines a location block with a prefix match 
location /api/ {
    proxy_pass http://backend;
}

Example: Preferential Prefix Usage

server {
    listen 80;
    server_name example.com;

    # Exact match - highest priority
    location = / {
        return 200 'Home page';
    }

    # Prefix match - lower priority
    location /api/ {
        proxy_pass http://backend;
    }

    # Regex match - lowest priority
    location ~ \.php$ {
        fastcgi_pass php;
    }
}
Note: The = operator has the highest priority and matches exactly. Prefix matches with =^~ have higher priority than regex matches.

9. Nesting Location Blocks

Directive Description Example
location Defines a location block for matching URI patterns. 
location /api/ {
    proxy_pass http://backend;
}
location = Matches exactly the given URI. 
location = / {
    return 200 'Home page';
}
location ^~ Matches the URI with prefix and stops processing. 
location ^~ /static/ {
    root /var/www;
}
location ~ Matches the URI with case-sensitive regex. 
location ~ \.(jpg|jpeg|png)$ {
    expires 1y;
}
location ~* Matches the URI with case-insensitive regex. 
location ~* \.(css|js)$ {
    gzip on;
}

Example: Nested Location Blocks

location /api/ {
    location /api/v1/ {
        proxy_pass http://backend_v1;
    }
    
    location /api/v2/ {
        proxy_pass http://backend_v2;
    }
}
Note: Nested location blocks inherit configuration from parent blocks, but can override specific directives.

Matching Priority

  • = (exact match) - Highest priority
  • ^~ (prefix match) - Higher than regex
  • ~* (case-insensitive regex)
  • ~ (case-sensitive regex)
  • Default match (prefix) - Lowest priority

10. Setting Location-specific Directives

Directive Description Example
alias Maps a location to a filesystem path alias /data/images/;
root Defines the root directory for resolving file paths root /var/www/html;
index Specifies the default file to serve for a directory index index.html index.htm;
try_files Checks for files in order and serves the first one found try_files $uri $uri/ /index.html;
return Stops processing and returns a specific response return 301 https://$host$request_uri;
rewrite Changes the URI using regular expressions rewrite ^/old/(.*)$ /new/$1 permanent;
access_by Executes a script or module before access control access_by { return 403; }
error_page Defines custom error pages for specific status codes error_page 404 /404.html;

Example: Using alias and root

location /images/ {
    alias /var/www/images/;
}

location /static/ {
    root /var/www;
}

Example: Using try_files for fallback handling

location / {
    try_files $uri $uri/ /index.html;
}

11. Using Named Locations

Property Description Usage
named location Defines a location with a name, used for internal redirects location = /login { ... }
internal Indicates that the location is for internal use only location /internal { internal; ... }

Example: Redirect to Named Location

location / {
    internal_redirect /login;
}

location = /login {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
}
Note: Named locations are not accessible via external requests and are used for internal redirections.

12. Redirecting to Named Location

Directive Values Description
return 301 or 302 HTTP status code for redirect
location @named_location Named location block to redirect to

Example: Redirecting to Named Location

server {
    listen 80;
    server_name example.com;

    location /old-path {
        return 301 @redirect_to_new;
    }

    location @redirect_to_new {
        return 301 /new-path;
    }
}

Was this article helpful?

Related Cheat Sheets