Named locations (@) in Nginx - Commands & Configuration

Introduction

Sometimes in nginx, you want to jump to a specific part of your configuration to handle requests differently. Named locations let you create these special spots to send requests internally without changing the URL.

When you want to handle errors or redirects internally without telling the user.

When you need to reuse a block of configuration for different request paths.

When you want to process requests differently based on conditions but keep URLs clean.

When you want to avoid repeating the same configuration in multiple places.

When you want to create a fallback handler for certain requests.

Config File - nginx.conf

nginx.conf

server {
    listen 80;
    server_name example.com;

    location / {
        # Try to serve file, if not found, go to named location @fallback
        try_files $uri $uri/ @fallback;
    }

    location @fallback {
        # This named location handles requests when files are missing
        proxy_pass http://backend_server;
    }

    location /images/ {
        # Directly serve images
        root /var/www/html;
    }
}

The location / block tries to serve files normally. If the file is not found, it internally redirects to the named location @fallback. The @fallback location proxies the request to a backend server. This setup helps handle missing files gracefully without changing the URL seen by the user.

The location /images/ block serves image files directly from the server.

Commands

Check the nginx configuration file for syntax errors before applying changes.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload nginx to apply the new configuration without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

Send a request for a missing file to test if nginx internally redirects to the named location and proxies correctly.

Terminal

curl -I http://example.com/missingfile.html

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Wed, 01 Jan 2025 12:00:00 GMT

Content-Type: text/html

Connection: keep-alive

Key Concept

Named locations let nginx internally redirect requests to special handlers without changing the URL seen by the user.

Common Mistakes

Using named locations with a leading slash like /@fallback instead of @fallback.

Nginx treats named locations starting with @ as special internal locations; adding a slash makes it a normal location and breaks the internal redirect.

Always define and refer to named locations with the @ symbol and no leading slash, like @fallback.

Not testing nginx configuration with 'nginx -t' before reload.

Syntax errors can cause nginx to fail to reload, leading to downtime.

Always run 'sudo nginx -t' to verify configuration syntax before reloading.

Summary

Named locations start with @ and define internal jump points in nginx configuration.

Use try_files or error_page directives to redirect requests internally to named locations.

Always test configuration syntax with 'nginx -t' before reloading nginx to apply changes.

Practice

1. What is the main purpose of a named location starting with @ in nginx configuration?

easy

A. To define an internal jump point for request handling

B. To specify a URL accessible by clients

C. To set environment variables for nginx

D. To configure SSL certificates

Solution

1. Step 1: Understand named locations in nginx

   Named locations start with @ and are used internally by nginx to jump to specific blocks of configuration during request processing.

2. Step 2: Differentiate from client-accessible URLs

   Named locations are not accessible directly by clients; they serve as internal routing points.

3. Final Answer:

   To define an internal jump point for request handling -> Option A

4. Quick Check:

   Named location = internal jump point [OK]

Hint: Named locations start with @ and are internal only [OK]

Common Mistakes:

• Thinking named locations are public URLs
• Confusing named locations with environment variables
• Assuming named locations configure SSL

2. Which of the following is the correct syntax to define a named location in nginx?

easy

A. location @named { ... }

B. location /named { ... }

C. named_location @named { ... }

D. location #named { ... }

Solution

1. Step 1: Recall nginx named location syntax

   Named locations are defined using location @name { ... } where @ prefixes the name.

2. Step 2: Check options for correct syntax

   location @named { ... } uses location @named { ... }, which is the correct syntax. Other options use invalid prefixes or keywords.

3. Final Answer:

   location @named { ... } -> Option A

4. Quick Check:

   Named location syntax = location @name [OK]

Hint: Named locations always start with @ in location block [OK]

Common Mistakes:

• Omitting the @ symbol
• Using # or other symbols instead of @
• Using invalid keywords like named_location

3. Given this nginx config snippet:

location / {
  error_page 404 = @fallback;
}

location @fallback {
  return 200 'Fallback reached';
}

What will be the response body if a client requests a non-existing page?

medium

A. 404 Not Found error page

B. Empty response with status 200

C. Fallback reached

D. 500 Internal Server Error

Solution

1. Step 1: Understand error_page directive with named location

   The error_page 404 = @fallback; tells nginx to internally redirect 404 errors to the named location @fallback.

2. Step 2: Analyze the named location response

   The @fallback location returns status 200 with body 'Fallback reached'. So a missing page triggers this response.

3. Final Answer:

   Fallback reached -> Option C

4. Quick Check:

   404 triggers @fallback = 'Fallback reached' [OK]

Hint: error_page 404 = @name redirects internally [OK]

Common Mistakes:

• Expecting default 404 page instead of fallback
• Confusing status codes returned
• Thinking named locations are client URLs

4. Identify the error in this nginx config snippet:

location / {
  error_page 404 = @notfound;
}

location notfound {
  return 404 'Not Found';
}

medium

A. location / block cannot have error_page

B. Named location missing @ prefix

C. return directive cannot use status 404

D. error_page directive syntax is wrong

Solution

1. Step 1: Check named location definition

   The named location referenced is @notfound, but the location block is defined as location notfound without the @.

2. Step 2: Confirm correct named location syntax

   Named locations must start with @, so it should be location @notfound.

3. Final Answer:

   Named location missing @ prefix -> Option B

4. Quick Check:

   Named location must start with @ [OK]

Hint: Named location blocks must start with @ [OK]

Common Mistakes:

• Defining named location without @
• Misusing error_page syntax
• Thinking return 404 is invalid

5. You want to reuse a block of configuration for multiple error codes (404 and 403) using a named location @error_handler. Which configuration correctly achieves this?

hard

A. error_page 404 403 @error_handler {
return 403 'Access denied';
}

B. error_page 404, 403 = @error_handler;

location @error_handler {
return 403 'Access denied';
}

C. error_page 404 403 @error_handler;

location @error_handler {
return 403 'Access denied';
}

D. error_page 404 = @error_handler;
error_page 403 = @error_handler;

location @error_handler {
return 403 'Access denied';
}

Solution

1. Step 1: Understand error_page syntax for multiple codes

   To assign multiple error codes to the same named location, you can use separate error_page directives for each code pointing to the same named location.

2. Step 2: Validate options

   error_page 404 = @error_handler;
   error_page 403 = @error_handler;
   
   location @error_handler {
     return 403 'Access denied';
   }

   correctly uses two error_page lines for 404 and 403, both redirecting to @error_handler. The named location block is defined properly.

3. Final Answer:

   Separate error_page directives for each code pointing to @error_handler -> Option D

4. Quick Check:

   Use separate error_page lines for multiple codes [OK]

Hint: Use separate error_page lines for multiple codes [OK]

Common Mistakes:

• Trying to list multiple codes with = @location in one line
• Incorrect error_page syntax without =
• Defining location block inside error_page