Rewrite directive in Nginx - Deep Dive

Overview - Rewrite directive

What is it?

The rewrite directive in nginx is a command used to change the URL of a request before it is processed. It allows you to modify URLs by matching patterns and replacing them with new ones. This helps control how users and browsers access resources on your server. It works inside server or location blocks in nginx configuration.

Why it matters

Without the rewrite directive, managing URLs would be rigid and complicated. It solves the problem of redirecting users, cleaning URLs, or handling legacy links without changing the actual files. This improves user experience, SEO, and server organization. Without it, websites would have broken links or confusing addresses, making navigation harder.

Where it fits

Before learning rewrite, you should understand basic nginx configuration and how server blocks and location blocks work. After mastering rewrite, you can explore advanced URL routing, redirects, and security rules in nginx. It fits into the journey of controlling web traffic and customizing server responses.

Mental Model

Core Idea

The rewrite directive changes incoming URLs by matching patterns and replacing them with new paths before nginx processes the request.

Think of it like...

It's like a traffic officer who stops cars on a road and directs them to a different street based on their license plate pattern, ensuring they reach the right destination.

┌───────────────┐
│ Incoming URL  │
└──────┬────────┘
       │ matches pattern?
       ▼
┌───────────────┐    yes    ┌───────────────┐
│ Rewrite Rule  ├──────────▶│ New URL Path  │
└──────┬────────┘          └──────┬────────┘
       │ no                      │
       ▼                         ▼
┌───────────────┐          ┌───────────────┐
│ Original URL  │          │ nginx serves  │
│ used as-is    │          │ content      │
└───────────────┘          └───────────────┘

Build-Up - 7 Steps

1

Foundation

Basic syntax of rewrite directive

Concept: Learn the basic structure of the rewrite directive and how to write a simple rule.

The rewrite directive uses this syntax: rewrite [flag]; - : a regular expression to match the URL. - : the new URL to use. - [flag]: optional, controls behavior (like last, break, redirect). Example: rewrite ^/oldpath/(.*)$ /newpath/$1 last; This changes URLs starting with /oldpath/ to /newpath/.

Result

When a user visits /oldpath/page, nginx rewrites it to /newpath/page internally.

Understanding the syntax is key because every rewrite rule follows this pattern, making it easy to create custom URL changes.

2

Foundation

How rewrite affects request processing

Concept: Understand when and how nginx applies rewrite rules during request handling.

Rewrite rules run during the request phase before content is served. The flag controls what happens next: - last: stops processing rewrite rules and searches for a new location with the rewritten URL. - break: stops rewrite processing but continues in the current location. - redirect: sends a 302 redirect to the client. - permanent: sends a 301 redirect to the client. Example: rewrite ^/old$ /new permanent; This tells the browser to go to /new permanently.

Result

The URL is changed internally or the client is redirected based on the flag.

Knowing how flags control flow prevents unexpected behavior like infinite loops or wrong redirects.

3

Intermediate

Using capture groups in rewrite patterns

🤔Before reading on: do you think capture groups can be reused in the replacement string? Commit to your answer.

Concept: Learn how to capture parts of the original URL and reuse them in the new URL.

Parentheses () in the pattern create capture groups. You can reference them in the replacement using $1, $2, etc. Example: rewrite ^/user/(\d+)/profile$ /profile.php?id=$1 last; If the URL is /user/123/profile, it rewrites to /profile.php?id=123.

Result

Dynamic parts of URLs can be preserved and passed to new URLs.

Capture groups make rewrites flexible and powerful, enabling dynamic URL transformations.

4

Intermediate

Difference between rewrite and return directives

🤔Before reading on: do you think rewrite and return directives both change URLs the same way? Commit to your answer.

Concept: Understand when to use rewrite for internal URL changes and return for sending HTTP status codes or redirects.

The rewrite directive changes URLs internally or redirects with flags. The return directive immediately sends a response with a status code and optional URL. Example: return 301 /newpage; This sends a permanent redirect without rewriting. Use rewrite for complex URL changes, return for simple redirects.

Result

Choosing the right directive affects server behavior and client experience.

Knowing the difference avoids misconfigurations that cause slow redirects or broken links.

5

Intermediate

Common flags and their effects

🤔Before reading on: which flag stops rewrite processing and restarts location search: last or break? Commit to your answer.

Concept: Learn the meaning of common flags: last, break, redirect, permanent.

Flags control rewrite behavior: - last: stops rewrite and restarts location search with new URL. - break: stops rewrite but stays in current location. - redirect: sends 302 redirect to client. - permanent: sends 301 redirect to client. Example: rewrite ^/old$ /new last; rewrite ^/temp$ /temp2 break; rewrite ^/go$ /redirected redirect; rewrite ^/perm$ /permanent permanent;

Result

Flags determine if rewrite is internal or client-visible redirect.

Understanding flags helps control request flow and avoid redirect loops or wrong content serving.

6

Advanced

Avoiding rewrite loops and performance tips

🤔Before reading on: do you think rewrite rules can cause infinite loops if not carefully written? Commit to your answer.

Concept: Learn how to prevent rewrite loops and optimize rewrite rules for performance.

Rewrite loops happen when rewritten URLs match the same pattern repeatedly. To avoid loops: - Use conditions (if statements) to limit rewrites. - Use flags like last or break correctly. - Test rules carefully. Performance tips: - Place rewrite rules in server block if possible. - Avoid complex regex when simpler location blocks work. Example: if ($request_uri !~ ^/newpath/) { rewrite ^/oldpath/(.*)$ /newpath/$1 last; }

Result

Stable, efficient rewrite rules that do not cause server errors or slowdowns.

Knowing how loops happen and how to prevent them is crucial for reliable nginx setups.

7

Expert

Internal nginx rewrite processing order and pitfalls

🤔Before reading on: does nginx process rewrite directives before or after location matching? Commit to your answer.

Concept: Understand the internal order nginx processes rewrite directives and how it affects configuration design.

Nginx processes rewrite directives in phases: - In server block: rewrites run before location matching. - In location block: rewrites run after location is chosen. This means rewrites in server block can change which location is selected. Pitfall: placing rewrite in location may cause unexpected behavior if you expect location change. Example: server { rewrite ^/old/(.*)$ /new/$1 last; location /new/ { # serves content } } Here rewrite changes URL before location selection.

Result

Better control over URL routing and avoiding confusing rewrite effects.

Understanding nginx's internal rewrite order prevents subtle bugs and helps design clear configurations.

Under the Hood

Nginx uses a request processing pipeline where rewrite directives are evaluated during the rewrite phase. When a request arrives, nginx first matches the server block, then applies rewrite rules in the server context to possibly change the URI. If the 'last' flag is used, nginx restarts location matching with the new URI. Rewrite rules in location blocks run after location selection and can modify the URI without changing location. Flags control whether nginx sends redirects to clients or rewrites internally. Internally, nginx uses efficient regex engines and a finite state machine to match patterns quickly.

Why designed this way?

The rewrite directive was designed to allow flexible URL manipulation without changing backend code or file structure. Separating rewrite phases between server and location blocks gives fine control over routing. The flag system balances internal rewrites and client redirects, optimizing performance and user experience. Alternatives like hardcoded redirects or application-level routing were less efficient or flexible. This design allows nginx to handle millions of requests with minimal overhead.

┌───────────────┐
│ Client Request│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Server Block  │
│ rewrite rules │
└──────┬────────┘
       │ (last flag restarts)
       ▼
┌───────────────┐
│ Location Match│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Location Block│
│ rewrite rules │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Content Serve │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does the rewrite directive always send a redirect to the client? Commit to yes or no.

Common Belief: Rewrite always sends a redirect to the user's browser.

Reality: Rewrite can change URLs internally without notifying the client, unless flags like redirect or permanent are used.

Why it matters: Misunderstanding this causes confusion when URLs change but the browser address bar does not, leading to debugging delays.

Quick: Can rewrite directives in location blocks change which location handles the request? Commit to yes or no.

Common Belief: Rewrite directives in location blocks can change the location selection.

Reality: Rewrite in location blocks runs after location is chosen and cannot change the location.

Why it matters: Expecting location changes here leads to broken routing and unexpected content serving.

Quick: Does the break flag restart location matching after rewrite? Commit to yes or no.

Common Belief: The break flag restarts location matching after rewrite.

Reality: The break flag stops rewrite processing but does not restart location matching; only last does that.

Why it matters: Using break when last is needed causes rewrites to be ignored or misapplied.

Quick: Can complex regex in rewrite hurt nginx performance? Commit to yes or no.

Common Belief: Regex complexity in rewrite has no impact on performance.

Reality: Complex regex can slow down request processing, especially under high load.

Why it matters: Ignoring this can cause slow response times and server overload.

Expert Zone

1

Rewrite rules in server blocks can change the URI and cause nginx to re-select location blocks, but rules in location blocks cannot, which affects routing design.

2

Using the last flag causes nginx to restart location matching, which can lead to subtle infinite loops if not carefully controlled with conditions.

3

The order of rewrite directives matters; multiple rewrites can stack and interact in unexpected ways if flags are not chosen properly.

When NOT to use

Avoid using rewrite for simple redirects where the return directive is clearer and more efficient. Also, do not use rewrite for complex application routing logic better handled by backend frameworks. For static file serving, prefer location blocks without rewrites to improve performance.

Production Patterns

In production, rewrite is often used to: - Clean URLs by removing file extensions. - Redirect old URLs to new ones after site restructuring. - Implement SEO-friendly URLs. - Route requests to backend services or scripts. - Handle language or region-based URL prefixes. Experts combine rewrite with conditional statements and caching headers for optimal results.

Connections

Regular Expressions

Rewrite patterns use regular expressions to match URLs.

Understanding regex deeply improves the precision and efficiency of rewrite rules.

HTTP Status Codes

Rewrite flags like redirect and permanent send HTTP status codes to clients.

Knowing HTTP codes helps configure correct client redirects and SEO-friendly responses.

Traffic Routing in Networking

Rewrite directs web traffic internally like routers direct network packets.

Seeing rewrite as traffic routing clarifies how requests flow through nginx and reach destinations.

Common Pitfalls

#1 Creating infinite rewrite loops by rewriting URLs to patterns that match the same rule repeatedly.

Wrong approach:

rewrite ^/path/(.*)$ /path/$1 last;

Correct approach:

if ($request_uri !~ ^/path/) {
rewrite ^/oldpath/(.*)$ /path/$1 last;
}

Root cause:

Not limiting rewrites with conditions causes nginx to repeatedly apply the same rule.

#2 Using break flag expecting location to change after rewrite.

Wrong approach:

rewrite ^/old$ /new break;

Correct approach:

rewrite ^/old$ /new last;

Root cause:

Misunderstanding that break stops rewrite but does not restart location matching.

#3 Using rewrite for simple redirects instead of return, causing unnecessary processing.

Wrong approach:

rewrite ^/old$ /new permanent;

Correct approach:

return 301 /new;

Root cause:

Not knowing return is simpler and more efficient for direct redirects.

Key Takeaways

The rewrite directive lets nginx change URLs by matching patterns and replacing them before serving content.

Flags like last, break, redirect, and permanent control whether rewrites happen internally or send redirects to clients.

Capture groups in patterns allow dynamic parts of URLs to be preserved and reused in new URLs.

Rewrite rules in server blocks can change location selection; those in location blocks cannot.

Careful design of rewrite rules prevents loops, improves performance, and ensures correct routing.