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.