Rewrite flags (last, break, redirect, permanent) in Nginx - Commands & Configuration

Introduction

Sometimes you want to change the web address a user visits or stop processing further rules. Nginx rewrite flags help control how these changes happen and what the server does next.

When you want to change a URL to a new one temporarily or permanently.

When you want to stop checking other rewrite rules after one matches.

When you want to redirect users to a different page but keep the original URL in the browser.

When you want to rewrite a URL internally without telling the browser.

Config File - nginx.conf

nginx.conf

server {
    listen 80;
    server_name example.com;

    location /old-path/ {
        # Redirect permanently to new path
        rewrite ^/old-path/(.*)$ /new-path/$1 permanent;
    }

    location /temp-redirect/ {
        # Redirect temporarily to another URL
        rewrite ^/temp-redirect/(.*)$ /another-path/$1 redirect;
    }

    location /internal-rewrite/ {
        # Rewrite internally and stop processing other rewrite rules
        rewrite ^/internal-rewrite/(.*)$ /final-path/$1 break;
    }

    location /last-example/ {
        # Rewrite and restart location processing
        rewrite ^/last-example/(.*)$ /last-path/$1 last;
    }

    location /final-path/ {
        # Serve content here
        return 200 "You reached the final path.";
    }

    location /last-path/ {
        # Serve content here
        return 200 "You reached the last path.";
    }

    location /new-path/ {
        # Serve content here
        return 200 "You reached the new path.";
    }

    location /another-path/ {
        # Serve content here
        return 200 "You reached another path.";
    }
}

This configuration shows how to use each rewrite flag:

• permanent: Sends a permanent redirect (HTTP 301) to the browser, changing the URL shown.
• redirect: Sends a temporary redirect (HTTP 302) to the browser.
• break: Stops processing rewrite rules and rewrites the URL internally without redirecting the browser.
• last: Stops processing rewrite rules and restarts location matching with the new URL.

Commands

Check the nginx configuration file for syntax errors before applying changes.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload nginx to apply the new configuration without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

Test the permanent redirect flag by requesting a URL that should redirect permanently to /new-path/page1.

Terminal

curl -i http://example.com/old-path/page1

Expected Output

HTTP/1.1 301 Moved Permanently

Location: http://example.com/new-path/page1

Content-Type: text/html

Content-Length: 178



<html>

<head><title>301 Moved Permanently</title></head>

<body>

<h1>Moved Permanently</h1>

<p>The document has moved <a href="http://example.com/new-path/page1">here</a>.</p>

</body>

</html>

Test the temporary redirect flag by requesting a URL that should redirect temporarily to /another-path/page2.

Terminal

curl -i http://example.com/temp-redirect/page2

Expected Output

HTTP/1.1 302 Found

Location: http://example.com/another-path/page2

Content-Type: text/html

Content-Length: 154



<html>

<head><title>302 Found</title></head>

<body>

<h1>Found</h1>

<p>The document has moved <a href="http://example.com/another-path/page2">here</a>.</p>

</body>

</html>

Test the break flag by requesting a URL that rewrites internally to /final-path/test without redirecting the browser.

Terminal

curl -i http://example.com/internal-rewrite/test

Expected Output

HTTP/1.1 200 OK

Content-Type: text/plain

Content-Length: 24



You reached the final path.

Test the last flag by requesting a URL that rewrites and restarts location matching to /last-path/test.

Terminal

curl -i http://example.com/last-example/test

Expected Output

HTTP/1.1 200 OK

Content-Type: text/plain

Content-Length: 23



You reached the last path.

Key Concept

If you remember nothing else from this pattern, remember: rewrite flags control whether nginx redirects the browser or rewrites URLs internally and how it processes further rules.

Common Mistakes

Using 'redirect' when a permanent redirect is needed.

The browser treats it as temporary and may not update bookmarks or caches properly.

Use 'permanent' flag for permanent URL changes to send HTTP 301 status.

Using 'break' when you want nginx to re-check location blocks.

'break' stops rewrite processing but does not restart location matching, so some rules may be skipped.

Use 'last' flag to restart location matching after rewrite.

Forgetting to reload nginx after changing the config.

Changes won't take effect until nginx reloads the configuration.

Run 'sudo nginx -t' to test and 'sudo systemctl reload nginx' to apply changes.

Summary

Use 'permanent' to send a permanent redirect (HTTP 301) to the browser.

Use 'redirect' to send a temporary redirect (HTTP 302) to the browser.

Use 'break' to rewrite URLs internally and stop further rewrite processing.

Use 'last' to rewrite URLs internally and restart location matching.

Always test your nginx config and reload the server to apply changes.

Practice

1. What does the last flag do in an nginx rewrite directive?

easy

A. Stops processing the current location and restarts the rewrite phase with the new URI

B. Sends a temporary redirect (HTTP 302) to the client

C. Stops processing the rewrite directives and continues with the current location

D. Sends a permanent redirect (HTTP 301) to the client

Solution

1. Step 1: Understand the last flag behavior

   The last flag tells nginx to stop processing current rewrite directives and restart the rewrite phase with the new URI.

2. Step 2: Compare with other flags

   Unlike break which stops rewriting internally, last restarts processing, and unlike redirect or permanent which send redirects, it does not send a client redirect.

3. Final Answer:

   Stops processing the current location and restarts the rewrite phase with the new URI -> Option A

4. Quick Check:

   last = restart rewrite phase [OK]

Hint: Remember: last restarts rewrite, break stops internally [OK]

Common Mistakes:

• Confusing last with break flag
• Thinking last sends a redirect
• Mixing last with permanent redirect

2. Which of the following is the correct syntax to perform a permanent redirect in nginx using the rewrite directive?

easy

A. rewrite ^/old$ /new break;

B. rewrite ^/old$ /new last;

C. rewrite ^/old$ /new permanent;

D. rewrite ^/old$ /new redirect;

Solution

1. Step 1: Identify the flag for permanent redirect

   The permanent flag sends an HTTP 301 status code indicating a permanent redirect.

2. Step 2: Check syntax correctness

   The syntax rewrite ^/old$ /new permanent; correctly applies the permanent redirect flag.

3. Final Answer:

   rewrite ^/old$ /new permanent; -> Option C

4. Quick Check:

   Permanent redirect uses permanent flag [OK]

Hint: Permanent redirect uses 'permanent' flag at end [OK]

Common Mistakes:

• Using 'last' or 'break' instead of 'permanent' for redirects
• Omitting the semicolon at the end
• Confusing 'redirect' with 'permanent'

3. Given the nginx configuration snippet:

location /test {
  rewrite ^/test/(.*)$ /new/$1 redirect;
}

What will happen when a client requests /test/page?

medium

A. The client will receive a 301 permanent redirect to /new/page

B. The rewrite will restart processing with the new URI /new/page

C. The request will be internally rewritten to /new/page without redirect

D. The client will receive a 302 temporary redirect to /new/page

Solution

1. Step 1: Understand the redirect flag

   The redirect flag sends an HTTP 302 temporary redirect to the client.

2. Step 2: Analyze the rewrite rule

   The rewrite matches /test/page and rewrites it to /new/page with a temporary redirect.

3. Final Answer:

   The client will receive a 302 temporary redirect to /new/page -> Option D

4. Quick Check:

   redirect = 302 temporary redirect [OK]

Hint: redirect flag means 302 temporary redirect [OK]

Common Mistakes:

• Confusing redirect with permanent
• Thinking redirect rewrites internally
• Assuming last or break flags here

4. You have this nginx rewrite rule:

rewrite ^/oldpath/(.*)$ /newpath/$1 last

But it causes a 500 Internal Server Error. What is the likely problem?

medium

A. Missing semicolon at the end of the rewrite directive

B. Using 'last' flag instead of 'break' causes infinite loop

C. The regex pattern is invalid

D. Rewrite directive must be inside a location block

Solution

1. Step 1: Check syntax of rewrite directive

   Every nginx directive must end with a semicolon. The given rewrite lacks a semicolon.

2. Step 2: Understand error cause

   Missing semicolon causes nginx to fail parsing config, leading to 500 error.

3. Final Answer:

   Missing semicolon at the end of the rewrite directive -> Option A

4. Quick Check:

   Missing semicolon = syntax error = 500 error [OK]

Hint: Always end rewrite directives with semicolon [OK]

Common Mistakes:

• Assuming last flag causes infinite loop
• Ignoring missing semicolon syntax errors
• Thinking regex pattern is wrong without checking

5. You want to rewrite URLs starting with /app to /app/index.html internally without redirecting the client, and stop further rewrite processing. Which rewrite directive and flag should you use?

hard

A. rewrite ^/app$ /app/index.html last;

B. rewrite ^/app$ /app/index.html break;

C. rewrite ^/app$ /app/index.html redirect;

D. rewrite ^/app$ /app/index.html permanent;

Solution

1. Step 1: Identify internal rewrite without client redirect

   The break flag stops rewrite processing and serves the rewritten URI internally without redirecting the client.

2. Step 2: Match requirement to flag

   Using break with the rewrite stops further rewrites and serves /app/index.html internally.

3. Final Answer:

   rewrite ^/app$ /app/index.html break; -> Option B

4. Quick Check:

   break = internal rewrite stop [OK]

Hint: Use break to rewrite internally and stop further rewrites [OK]

Common Mistakes:

• Using last which restarts rewrite phase
• Using redirect or permanent which send client redirects
• Not stopping rewrite processing causing unexpected behavior