0
0
Nginxdevops~5 mins

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

Choose your learning style9 modes available
LearnWhyDeepVisualTryChallengeProjectRecallTime
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 OutputExpected
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 OutputExpected
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 OutputExpected
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 OutputExpected
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 OutputExpected
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 OutputExpected
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.