Apache’s mod_rewrite is often described as the Swiss Army knife of URL manipulation – and for good reason. This powerful module allows you to transform ugly, complex URLs into clean, user-friendly ones, redirect traffic based on sophisticated conditions, and implement advanced routing rules for your web applications.

This guide is perfect for web developers and system administrators who want to harness the full potential of URL rewriting in Apache. Whether you’re looking to create SEO-friendly URLs or implement complex routing rules, this tutorial will help you master mod_rewrite.

We’ll cover everything from basic concepts to advanced techniques, focusing solely on mod_rewrite functionality and usage. While we won’t cover Apache installation (as that’s beyond our scope), we’ll assume you have a working Apache server ready to go.

Understanding mod_rewrite Basics

Definition and Core Functionality

mod_rewrite is a URL manipulation engine built into Apache that uses rules to rewrite requested URLs on the fly. It operates at the server level, intercepting requests before they’re processed by your web applications, and can transform them based on various conditions.

How mod_rewrite Processes URLs

When a request arrives, mod_rewrite processes it through a series of rules, each potentially modifying the URL based on pattern matching using regular expressions (PCRE). This happens transparently to the end-user, making it perfect for maintaining clean URLs while keeping your internal structure flexible.

When to Use mod_rewrite

mod_rewrite is ideal for:

• Creating clean, SEO-friendly URLs
• Implementing URL shortening
• Managing legacy URLs after site restructuring
• Enforcing security rules
• Handling complex routing requirements

However, for simple redirects, consider using Apache’s Redirect or RedirectMatch directives instead, as they’re more efficient for basic tasks.

Getting Started with mod_rewrite

Verifying mod_rewrite is Enabled

First, ensure mod_rewrite is enabled in your Apache configuration:

# Check if the module is loaded
LoadModule rewrite_module modules/mod_rewrite.so

Choosing Between .htaccess and Server Config

You can implement rewrite rules in two places:

1. Server configuration file (httpd.conf or similar)
2. .htaccess files in individual directories

The server configuration approach offers better performance but requires server restart for changes. .htaccess files provide flexibility and don’t require restarts, but slightly impact performance.

Basic Configuration Requirements

To use mod_rewrite in .htaccess files, ensure your Apache configuration includes:

<Directory "/var/www/html">
    AllowOverride All
    Require all granted
</Directory>

The Anatomy of Rewrite Rules

Basic RewriteRule Syntax

A RewriteRule consists of three parts:

RewriteRule Pattern Substitution [Flags]

• Pattern: Regular expression matching the desired URL
• Substitution: Replacement URL or path
• Flags: Optional modifiers affecting rule behavior

Understanding Regular Expressions in mod_rewrite

Common patterns include:

• ^ – Start of string
• $ – End of string
• (.*) – Match anything
• ([0-9]+) – Match one or more digits

Example:

RewriteRule ^article/([0-9]+)$ /articles.php?id=$1 [L]

Essential RewriteRule Flags

• [L] – Last rule, stop processing further rules
• [R=301] – Permanent redirect
• [R=302] – Temporary redirect
• [NC] – Case-insensitive matching
• [QSA] – Append query string
• [F] – Return forbidden response

Working with RewriteCond

Purpose and Functionality

RewriteCond adds conditional logic to your rewrite rules, allowing you to check various server variables, HTTP headers, or other conditions before applying a rule.

Syntax Breakdown

RewriteCond TestString CondPattern [Flags]

Common Server Variables

• %{HTTP_HOST} – Requested hostname
• %{REQUEST_URI} – URL path
• %{QUERY_STRING} – Query parameters
• %{HTTP_USER_AGENT} – Browser information
• %{REMOTE_ADDR} – Client IP address

Pattern Matching with RewriteCond

Example testing multiple conditions:

RewriteCond %{HTTP_HOST} ^example\.com$ [NC]
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://example.com/$1 [L,R=301]

Practical Examples and Use Cases

Redirecting www to non-www

RewriteCond %{HTTP_HOST} ^www\.(.+)$ [NC]
RewriteRule ^(.*)$ http://%1/$1 [R=301,L]

This rule captures the domain without www and performs a permanent redirect, ensuring consistent domain usage across your site.

Forcing HTTPS

RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

This essential security measure redirects all HTTP traffic to HTTPS, protecting user data during transmission.

Creating Clean URLs

# Transform article.php?id=123 to /article/123
RewriteRule ^article/([0-9]+)$ article.php?id=$1 [L]

# Transform category.php?name=tech to /category/tech
RewriteRule ^category/([^/]+)$ category.php?name=$1 [L]

These rules create user-friendly URLs while maintaining your existing PHP scripts.

Blocking Unwanted Traffic

# Block specific IP addresses
RewriteCond %{REMOTE_ADDR} ^123\.456\.789\.0$
RewriteRule .* - [F]

# Block specific user agents
RewriteCond %{HTTP_USER_AGENT} ^BadBot [NC]
RewriteRule .* - [F]

Best Practices and Optimization

Rule Organization and Structure

• Place most specific rules first
• Group related rules together
• Use comments to document complex rules
• Keep rules modular and maintainable

Performance Considerations

• Minimize the number of rules
• Use the [L] flag to prevent unnecessary processing
• Avoid complex regular expressions when simple ones will do
• Consider using RewriteMap for large lookup tables

Security Best Practices

• Validate input patterns strictly
• Protect sensitive directories
• Use appropriate HTTP status codes
• Implement rate limiting when necessary
• Always escape special characters

Troubleshooting and Debugging

Setting up Rewrite Logging

Enable detailed logging for debugging:

LogLevel alert rewrite:trace3
RewriteLog "/var/log/apache2/rewrite.log"
RewriteLogLevel 3

Common Issues and Solutions

1. Infinite Loops
   • Check for circular redirects
   • Verify rule termination with [L] flag
   • Test with curl to trace redirects
2. Rule Conflicts
   • Review rule order
   • Check for overlapping patterns
   • Verify RewriteBase settings
3. Performance Problems
   • Monitor server load
   • Optimize regular expressions
   • Consider caching solutions

Debugging Tools and Techniques

• Use curl with -I and -L flags
• Monitor Apache error logs
• Employ online regex testers
• Utilize browser developer tools

Conclusion

Mastering mod_rewrite opens up powerful possibilities for URL manipulation and request handling in Apache. While the learning curve can be steep, understanding the fundamentals of patterns, conditions, and flags allows you to implement sophisticated URL schemes and routing rules.

To continue learning, experiment with different rule combinations, study the Apache documentation, and practice regular expressions. Remember to always test your rules thoroughly in a development environment before deploying to production.

Quick Reference

Common Rule Patterns

# Basic redirect
RewriteRule ^old-page\.html$ new-page.html [L]

# Parameter handling
RewriteRule ^article-([0-9]+)$ article.php?id=$1 [L]

# Path transformation
RewriteRule ^blog/(.*)$ /wordpress/$1 [L]

Frequently Used Flags

• [L] – Last rule
• [R=301] – Permanent redirect
• [NC] – Case-insensitive
• [QSA] – Query string append
• [F] – Forbidden
• [P] – Proxy

Essential Server Variables

• %{HTTP_HOST}
• %{REQUEST_URI} – %{HTTPS}
• %{REMOTE_ADDR}
• %{HTTP_USER_AGENT}
• %{QUERY_STRING}

Debugging Checklist

1. Verify mod_rewrite is enabled
2. Check Apache error logs
3. Enable rewrite logging
4. Test rules with curl
5. Verify file permissions
6. Check regular expressions
7. Confirm RewriteBase setting
8. Monitor for infinite loops
9. Validate rule order
10. Test in development environment