Named locations (@) in Nginx - Mini Project: Build & Apply

Using Named Locations (@) in Nginx Configuration

📖 Scenario: You are setting up a simple Nginx web server. You want to handle requests differently based on the URL path. Sometimes, you want to redirect users to a special internal page without exposing the URL change.

🎯 Goal: Build an Nginx configuration that uses named locations (starting with @) to internally redirect requests to a custom error page.

📋 What You'll Learn

Create a server block listening on port 80

Define a location / that checks if a file exists

If the file does not exist, internally redirect to a named location @custom_404

Define the named location @custom_404 to serve a custom 404 error page

Print the final Nginx configuration

💡 Why This Matters

🌍 Real World

Named locations in Nginx help redirect requests internally without changing the URL seen by users. This is useful for custom error handling, maintenance pages, or complex routing.

💼 Career

Understanding named locations is important for DevOps roles managing web servers, enabling better control over request handling and improving user experience with custom error pages.

1

Create the basic server block

Create an Nginx server block listening on port 80 with a root directory set to /var/www/html.

Nginx

server {
    # Your code here
}

Hint

Use listen 80; to listen on port 80 and root /var/www/html; to set the root directory.

2

Add location / with try_files and named location redirect

Inside the server block, add a location / block that uses try_files $uri $uri/ @custom_404; to check if the requested file or directory exists, and if not, redirect internally to the named location @custom_404.

Nginx

server {
    listen 80;
    root /var/www/html;

    # Your code here
}

Hint

The try_files directive tries the listed files or directories, and if none exist, it redirects internally to the named location.

3

Define the named location @custom_404

Add a named location @custom_404 inside the server block that returns a 404 status and serves the file /var/www/html/custom_404.html using internal and root directives.

Nginx

server {
    listen 80;
    root /var/www/html;

    location / {
        try_files $uri $uri/ @custom_404;
    }

    # Your code here
}

Hint

The internal directive makes the named location accessible only by internal redirects, not by direct client requests.

4

Print the complete Nginx configuration

Print the entire Nginx configuration you have created so far.

Nginx

# Your code here

Hint

Use a print statement to output the full configuration text exactly as written.

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