Exact match (=) in Nginx - Deep Dive

Overview - Exact match (=)

What is it?

Exact match (=) is a way to tell nginx to match a URL path exactly as it is written. When you use the equal sign in a location block, nginx will only use that block if the request URL matches the specified path perfectly, without any extra characters. This helps control how nginx handles requests by making sure only exact URLs trigger certain rules.

Why it matters

Without exact match, nginx might use a more general rule that partially matches a URL, causing unexpected behavior or serving the wrong content. Exact match ensures precise control over which requests get handled by which configuration, improving security and performance. It helps avoid confusion when multiple location blocks could match similar URLs.

Where it fits

Before learning exact match, you should understand basic nginx configuration and how location blocks work. After mastering exact match, you can learn about prefix matches, regular expression matches, and how nginx chooses between them to handle requests.

Mental Model

Core Idea

Exact match (=) tells nginx to use a location only when the request URL matches the path exactly, no more, no less.

Think of it like...

It's like having a key that only opens one specific door exactly, not any similar doors nearby.

┌─────────────────────────────┐
│ nginx receives a request URL │
└─────────────┬───────────────┘
              │
      ┌───────▼────────┐
      │ Check location  │
      │ blocks in order │
      └───────┬────────┘
              │
   ┌──────────▼───────────┐
   │ Is there an exact (=) │
   │ match for the URL?   │
   └───────┬──────────────┘
           │Yes                      No
           │                         │
   ┌───────▼────────┐       ┌────────▼─────────┐
   │ Use exact match │       │ Check prefix or  │
   │ location block  │       │ regex location   │
   └─────────────────┘       └─────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding nginx location blocks

Concept: Learn what location blocks are and how nginx uses them to handle different URLs.

In nginx, location blocks define how to respond to different URL paths. For example, a location /images/ block handles requests starting with /images/. These blocks help organize rules for serving files or proxying requests.

Result

You know that location blocks are the main way nginx decides what to do with incoming requests.

Understanding location blocks is essential because exact match is a special kind of location block that changes how nginx matches URLs.

2

Foundation

Basic prefix matching in locations

Concept: Learn how nginx matches URLs by default using prefix matching.

By default, nginx matches URLs by checking if the request path starts with the location path. For example, location /app/ matches /app/page1 and /app/page2. This is called prefix matching.

Result

You see that many URLs can match the same location if they start with the same prefix.

Knowing prefix matching helps you understand why exact match is needed to avoid matching too many URLs.

3

Intermediate

Introducing exact match (=) modifier

🤔Before reading on: do you think nginx uses exact match locations before prefix matches or after? Commit to your answer.

Concept: Learn how to use the = modifier to make nginx match URLs exactly.

You add = before the path in a location block like this: location = /about { ... }. This tells nginx to only use this block if the URL is exactly /about, no extra characters allowed.

Result

Nginx will only use this location block if the request URL is exactly /about.

Understanding that = locations have the highest priority helps you control request handling precisely.

4

Intermediate

Priority order of location matching

🤔Before reading on: which location type do you think nginx checks first: exact match (=), prefix, or regex? Commit to your answer.

Concept: Learn the order nginx uses to pick a location block when multiple could match.

Nginx first checks for exact match (=) locations. If none match, it checks prefix locations. Finally, it checks regex locations. This order ensures exact matches override other rules.

Result

You understand that exact match locations have the highest priority in nginx's matching process.

Knowing the priority order prevents unexpected matches and helps you design clear nginx configurations.

5

Intermediate

Using exact match for static files

Concept: Learn a common use case: serving a specific static file with exact match.

Example: location = /favicon.ico { root /var/www/html; } This serves the favicon.ico file only when the URL is exactly /favicon.ico, avoiding conflicts with other location blocks.

Result

Requests to /favicon.ico serve the correct file, while other URLs do not match this block.

Using exact match for specific files avoids accidental matches and improves performance by skipping unnecessary checks.

6

Advanced

Combining exact match with other locations

🤔Before reading on: do you think nginx can use both exact match and prefix locations for the same URL? Commit to your answer.

Concept: Learn how nginx chooses between exact and prefix locations when both could match.

If an exact match location exists for a URL, nginx uses it and ignores prefix matches. For example, with location = /test and location /test, a request to /test uses the exact match block.

Result

Nginx uses the exact match location exclusively when it exists for the requested URL.

Understanding this prevents confusion when multiple location blocks seem to match the same URL.

7

Expert

Performance impact and internal matching logic

🤔Before reading on: do you think exact match locations are faster or slower than prefix matches? Commit to your answer.

Concept: Learn how nginx internally optimizes exact match locations for speed.

Nginx stores exact match locations in a hash table for O(1) lookup, making them very fast. Prefix matches use a tree structure and regex matches require evaluation. This design makes exact matches the quickest to resolve.

Result

Exact match locations improve performance for frequently requested exact URLs.

Knowing nginx's internal matching optimizations helps you write efficient configurations and avoid slow regex matches when unnecessary.

Under the Hood

Nginx compiles location blocks into internal data structures. Exact match locations are stored in a hash table keyed by the exact URL path. When a request arrives, nginx first checks this hash for a direct hit. If found, it immediately uses that location block. If not, it falls back to prefix matching using a tree structure, then regex matching if configured. This layered approach balances speed and flexibility.

Why designed this way?

This design was chosen to optimize common cases where exact URLs are requested frequently, such as static files or API endpoints. Hash lookups are very fast, so exact matches minimize processing time. Prefix and regex matches provide flexibility for broader patterns but are slower. The order ensures the fastest possible match is found first.

┌───────────────────────────────┐
│ nginx receives request URL     │
└───────────────┬───────────────┘
                │
      ┌─────────▼─────────┐
      │ Check exact match  │
      │ hash table         │
      └───────┬───────────┘
              │
      ┌───────▼───────────┐
      │ Exact match found? │
      └───────┬───────────┘
          Yes │ No
              │
      ┌───────▼───────────┐
      │ Use exact match    │
      │ location block     │
      └────────────────────┘
              │
              ▼
      ┌───────┴───────────┐
      │ Check prefix match │
      │ tree structure     │
      └───────┬───────────┘
              │
      ┌───────▼───────────┐
      │ Prefix match found?│
      └───────┬───────────┘
          Yes │ No
              │
      ┌───────▼───────────┐
      │ Use prefix match   │
      │ location block     │
      └────────────────────┘
              │
              ▼
      ┌───────┴───────────┐
      │ Check regex match  │
      └───────┬───────────┘
              │
      ┌───────▼───────────┐
      │ Regex match found? │
      └───────┬───────────┘
          Yes │ No
              │
      ┌───────▼───────────┐
      │ Use regex match    │
      │ location block     │
      └────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does location = /path match /path/ or /path? Commit to yes or no.

Common Belief: People often think exact match (=) matches URLs that start with the path, including trailing slashes.

Reality: Exact match (=) only matches the URL exactly as specified, so /path does not match /path/ or /path/extra.

Why it matters: Misunderstanding this causes nginx to serve wrong content or return 404 errors unexpectedly.

Quick: Do you think nginx checks regex locations before exact match? Commit to yes or no.

Common Belief: Some believe regex locations have higher priority than exact match locations.

Reality: Nginx always checks exact match locations first, then prefix, then regex.

Why it matters: Incorrect assumptions about priority lead to confusing configuration bugs and unexpected request handling.

Quick: Does using exact match (=) slow down nginx? Commit to yes or no.

Common Belief: Some think exact match locations are slower because they are more specific.

Reality: Exact match locations are fastest because nginx uses a hash table for O(1) lookup.

Why it matters: Avoiding exact match due to false performance fears can lead to inefficient regex or prefix matches.

Quick: Can you use exact match (=) with regex patterns? Commit to yes or no.

Common Belief: People sometimes think = can be combined with regex in location blocks.

Reality: = is only for exact string matches; regex locations use ~ or ~* modifiers.

Why it matters: Mixing these causes nginx configuration errors or unexpected behavior.

Expert Zone

1

Exact match locations bypass the prefix tree, so placing frequently requested URLs here reduces CPU cycles.

2

When multiple exact match locations exist (rare), nginx uses the first defined in the config, so order matters.

3

Exact match is case-sensitive; to handle case-insensitive exact matches, you must use regex with ~*.

When NOT to use

Avoid exact match when you need to match multiple similar URLs or patterns; use prefix or regex locations instead. For example, to match all URLs starting with /api/, use prefix location /api/ rather than exact match.

Production Patterns

In production, exact match is commonly used for static assets like /favicon.ico, /robots.txt, or health check endpoints to ensure fast, precise routing. It is also used to protect sensitive URLs by isolating them from broader prefix matches.

Connections

Hash Tables

Exact match locations use hash tables internally for fast lookup.

Understanding hash tables explains why exact match lookups are so fast compared to prefix or regex matches.

Regular Expressions

Exact match is an alternative to regex matching for simple, precise URL matches.

Knowing when to use exact match instead of regex improves configuration clarity and performance.

Database Indexing

Exact match in nginx is like using a primary key index in databases for quick data retrieval.

This cross-domain connection helps appreciate how indexing speeds up searches in different systems.

Common Pitfalls

#1 Using exact match (=) but expecting it to match URLs with trailing slashes.

Wrong approach:

location = /about {
# config
}
# Request to /about/ does not match this block

Correct approach:

location = /about {
# config
}
location = /about/ {
# config for trailing slash
}

Root cause:

Misunderstanding that exact match requires the URL to be exactly the same, including trailing slashes.

#2 Placing regex location before exact match and expecting regex to override.

Wrong approach:

location ~ ^/test$ {
# regex config
}
location = /test {
# exact match config
}
# Regex is checked after exact match, so exact match wins.

Correct approach:

location = /test {
# exact match config
}
location ~ ^/test$ {
# regex config
}

Root cause:

Not knowing nginx's location matching priority order.

#3 Trying to use = with regex pattern in location block.

Wrong approach:

location = ~ /api/v1/ {
# invalid config
}

Correct approach:

location ~ /api/v1/ {
# regex config
}
location = /api/v1/ {
# exact match config
}

Root cause:

Confusing exact match modifier (=) with regex modifiers (~, ~*).

Key Takeaways

Exact match (=) in nginx matches URLs exactly as specified, with no extra characters allowed.

Nginx checks exact match locations first, making them the highest priority and fastest to match.

Exact match locations use a hash table internally, providing very fast lookups compared to prefix or regex matches.

Misunderstanding exact match behavior causes common configuration errors, such as missing trailing slashes or wrong priority assumptions.

Use exact match for specific URLs like static files or health checks to improve performance and clarity in nginx configurations.

Practice

1. What does the = sign mean in an nginx location block?

easy

A. It matches URLs ending with the given path.

B. It matches the exact URL path only.

C. It matches URLs containing the given path anywhere.

D. It matches any URL starting with the given path.

Solution

1. Step 1: Understand nginx location matching

   The = sign in nginx location means the URL must match exactly the specified path.

2. Step 2: Compare with other matching types

   Other types like prefix matching use location /path without =, which matches URLs starting with that path.

3. Final Answer:

   It matches the exact URL path only. -> Option B

4. Quick Check:

   Exact match = exact URL [OK]

Hint: Exact match uses = sign, no extra path allowed [OK]

Common Mistakes:

• Thinking = matches URL prefixes
• Confusing = with regex matching
• Assuming = matches URLs containing the path

2. Which of the following is the correct syntax to define an exact match location for URL /about in nginx?

easy

A. location /about { }

B. location /about = { }

C. location ~ /about { }

D. location = /about { }

Solution

1. Step 1: Recall nginx exact match syntax

   Exact match uses location = /path { } syntax, where = comes immediately after location.

2. Step 2: Check other options

   location /about = { } places = after path, which is invalid. location ~ /about { } uses regex (~), not exact match. location /about { } is prefix match.

3. Final Answer:

   location = /about { } -> Option D

4. Quick Check:

   Exact match syntax = location = /path [OK]

Hint: Put = right after location for exact match [OK]

Common Mistakes:

• Placing = after the path
• Using regex (~) instead of = for exact match
• Omitting = for exact match

3. Given this nginx config snippet:

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

What will be the response body when accessing URL /test?

medium

A. Exact match

B. Prefix match

C. 404 Not Found

D. 500 Internal Server Error

Solution

1. Step 1: Identify matching location for /test

   The URL /test matches exactly the location = /test block because of the exact match sign =.

2. Step 2: Understand nginx location priority

   Exact match locations have higher priority than prefix matches, so the first block is used and returns 'Exact match'.

3. Final Answer:

   Exact match -> Option A

4. Quick Check:

   Exact match location wins for exact URL [OK]

Hint: Exact match location overrides prefix for exact URL [OK]

Common Mistakes:

• Choosing prefix match response for exact URL
• Assuming 404 if exact match exists
• Confusing order of location blocks

4. You wrote this nginx config:

location = /home {
  proxy_pass http://backend;
}
location /home {
  proxy_pass http://frontend;
}

But requests to /home are always sent to http://frontend. What is the likely problem?

medium

A. The exact match location block is not matched because of a syntax error.

B. The exact match location block is missing a trailing slash.

C. The exact match location is overridden by prefix match due to order.

D. The exact match location block is ignored because proxy_pass is invalid.

Solution

1. Step 1: Check syntax of exact match location

   The exact match location location = /home { ... } may have a syntax error like missing semicolon after proxy_pass, causing nginx to ignore it.

2. Step 2: Consider nginx matching rules

   Exact match locations have highest priority and should be matched first. If requests go to frontend, likely the exact match block is ignored due to a syntax error or config reload issue.

3. Step 3: Identify common mistake

   Often, missing semicolons or incorrect proxy_pass URL cause nginx to ignore the block silently.

4. Final Answer:

   The exact match location block is not matched because of a syntax error. -> Option A

5. Quick Check:

   Syntax errors cause nginx to ignore blocks [OK]

Hint: Check syntax errors if exact match ignored [OK]

Common Mistakes:

• Assuming order affects exact match priority
• Missing semicolon after proxy_pass
• Confusing trailing slash importance

5. You want to serve a special static page only when the URL is exactly /special. Which nginx config snippet correctly achieves this without affecting other URLs starting with /special?

hard

A. location /special { root /var/www/special; }

B. location ~ /special { root /var/www/special; }

C. location = /special { root /var/www/special; }

D. location ^~ /special { root /var/www/special; }

Solution

1. Step 1: Understand exact match requirement

   To serve only the exact URL /special, use location = /special which matches exactly that path.

2. Step 2: Analyze other options

   location /special { root /var/www/special; } matches any URL starting with /special. location ~ /special { root /var/www/special; } uses regex to match URLs containing /special anywhere. location ^~ /special { root /var/www/special; } uses prefix match with ^~, which matches prefixes but not exact only.

3. Final Answer:

   location = /special { root /var/www/special; } -> Option C

4. Quick Check:

   Exact match = location = /path [OK]

Hint: Use = for exact URL, not prefix or regex [OK]

Common Mistakes:

• Using prefix match for exact URL
• Overcomplicating with regex
• Confusing ^~ with exact match