Named locations (@) in Nginx - Step-by-Step Execution

Process Flow - Named locations (@)

Client Request Received

↓

Check URI Match

↓

If match normal location

→Serve Content

↓

If match named location @name

↓

Internal Redirect to @name

↓

Execute @name block

↓

Serve Content or Further Redirect

When nginx receives a request, it checks if the URI matches a named location starting with '@'. If yes, it internally redirects to that named location block to handle the request.

Execution Sample

Nginx

location / {
    try_files $uri @fallback;
}

location @fallback {
    proxy_pass http://backend;
}

This config tries to serve files normally, but if not found, internally redirects to the named location '@fallback' which proxies to a backend server.

Process Table

Step	Request URI	Condition Checked	Action Taken	Result
1	/index.html	Does /index.html exist?	Yes - serve file	Content served directly
2	/missing.html	Does /missing.html exist?	No - redirect to @fallback	Internal redirect to @fallback
3	@fallback	Execute @fallback block	proxy_pass to backend	Request forwarded to backend
4	Response from backend	Return response	Send response to client	Client receives backend content
5	-	No more actions	End processing	Request complete

💡 Request completes after serving content or proxying via named location

Status Tracker

Variable	Start	After Step 2	After Step 3	Final
Request URI	/missing.html	@fallback	@fallback	Response content
Current Location	/	@fallback	@fallback	Done
Response Source	File system	N/A	Backend server	Client

Key Moments - 3 Insights

Why does nginx use '@' before a location name?

The '@' prefix marks a named location that is not directly accessible by clients but used for internal redirects, as shown in execution_table step 2 and 3.

What happens if the requested file exists?

Nginx serves the file directly without redirecting to the named location, as seen in execution_table step 1.

Can named locations be accessed directly by clients?

No, named locations are internal only and cannot be accessed directly, only via internal redirects like in step 2.

Visual Quiz - 3 Questions

Look at the execution table, what action does nginx take when /missing.html does not exist?

A Serve the file directly

B Return 404 error

C Redirect internally to @fallback

D Proxy to backend without redirect

💡 Hint

See execution_table row 2 where /missing.html triggers internal redirect to @fallback

At which step does nginx proxy the request to the backend server?

A Step 3

B Step 1

C Step 4

D Step 5

💡 Hint

Check execution_table row 3 where @fallback block proxies to backend

If the file /index.html exists, what is the final response source?

A Backend server

B File system

C Named location @fallback

D 404 error page

💡 Hint

Refer to variable_tracker row 'Response Source' after step 1

Concept Snapshot

Named locations in nginx start with '@' and are used for internal redirects.
They are not accessible directly by clients.
Use them to handle fallback or special routing logic.
Example: try_files $uri @fallback; redirects missing files internally.
Named location blocks can proxy or serve content internally.
This helps organize complex routing cleanly.

Full Transcript

Named locations in nginx are special blocks starting with '@' used for internal redirects. When a client request comes in, nginx checks if the requested URI matches a normal location or if it should internally redirect to a named location. For example, if a requested file does not exist, nginx can redirect internally to a named location like '@fallback' which can proxy the request to a backend server. Named locations cannot be accessed directly by clients; they only serve as internal routing points. This mechanism helps handle fallback scenarios or complex routing in a clean way. The execution table shows step-by-step how nginx processes a request, checks file existence, redirects internally if needed, and finally serves content either from the file system or backend.

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