Handling URL Migrations with Apache mod_rewrite

The Cost of Broken Links

When you restructure a website's directory or change a naming convention for your URLs, you risk creating a wave of 404 Not Found errors. This doesn't just frustrate users; it erodes your search engine ranking because link equity—the value search engines assign to a page based on incoming links—is lost when a destination disappears.

The solution is mod_rewrite, an Apache module that allows you to map old URL patterns to new ones dynamically. The goal is to move from a fragile, file-based URL structure to a flexible, rule-based system where the server handles the routing logic before the request ever hits the filesystem.

Internal Rewrites vs. External Redirects

Before configuring rules, you must decide if the user should see the change in their browser. Apache handles this through two distinct behaviors:

• Internal Rewrites: The server changes the request path internally. The user sees /products/blue-widget in the address bar, but Apache serves the content from /archive/widgets.php?id=123. This is ideal for creating "pretty URLs."
• External Redirects: The server sends an HTTP response (like a 301 Moved Permanently) telling the browser to request a different URL. The address bar updates, and search engines are told to index the new location.

Building a Rule Set

The rewrite engine operates on a simple logic: If [Condition] is met, then [Rule] applies.

The RewriteCond directive acts as a filter. You can check for specific browser agents, referrers, or whether a file actually exists on the disk. The RewriteRule then uses regular expressions to capture parts of the old URL and inject them into the new one.

To prevent the server from wasting cycles, the [L] (Last) flag is critical. It tells Apache to stop processing further rules if the current one matches, preventing accidental double-rewrites.

Worked Example: Migrating a Legacy Category Structure

Imagine you are moving your blog from a dated /category/name.html structure to a modern /blog/category/name/ format. You want to ensure all old bookmarks still work and that SEO value is preserved.

Add the following to your server configuration file (typically httpd.conf or a virtual host file). Avoid using .htaccess if you have access to the main config, as it reduces filesystem I/O overhead.

# Enable the rewrite engine
RewriteEngine On

# 1. Redirect legacy .html category pages to new folder structure
# Pattern: /category/something.html -> /blog/category/something/
RewriteRule ^/category/([^/]+)\.html$ /blog/category/$1/ [R=301,L]

# 2. Internal rewrite for a custom profile page
# Pattern: /user/john -> /profiles.php?user=john
RewriteRule ^/user/([^/]+)$ /profiles.php?user=$1 [L]

Implementation Details

• Permissions: You must have root or sudo access to modify the main Apache configuration files.
• Placeholders: ([^/]+) is a regular expression that captures any character except a forward slash. The $1 in the substitution string refers back to that first captured group.
• Expected Result: A request to /category/tech.html should return a 301 Moved Permanently header pointing to /blog/category/tech/.

Performance Trade-offs and Risks

While powerful, mod_rewrite can become a bottleneck if mismanaged. Every request must be evaluated against your list of rules. Complex regular expressions with heavy backtracking can increase CPU usage per request.

The most dangerous risk is the infinite redirection loop. This happens when a rule redirects a URL to a destination that then matches the same rule again, causing the browser to throw a "Too many redirects" error. Always ensure your destination URL does not satisfy the conditions of the rule that created it.

Verification and Rollback

To verify the module is active, run the following command on your server terminal:

httpd -M | grep rewrite_module

To test a specific rule without a browser, use curl to inspect the headers:

curl -I http://yourdomain.com/category/test.html

Check that the HTTP/1.1 301 Moved Permanently status and the Location: header are correct.

Rollback: Since these changes modify the server state, the only way to revert is to comment out the rules in the configuration file using the # symbol and restart the Apache service: sudo systemctl restart httpd (or apache2).