Offensive Security Researcher & Quantum Cryptography Analyst

How to Use mod_alias for URL Redirection in Apache

Abdul Wahab Junaid
How to use mod_alias for URL redirection in Apache

How to use mod_alias for URL redirection in Apache

Every site I’ve ever managed eventually needs some kind of URL redirection — a page gets moved, a domain gets rebranded, or I just need to map a friendly URL to a folder buried somewhere else on disk. mod_rewrite tends to get all the attention for this kind of thing, but honestly, for straightforward redirects and aliases, mod_alias is simpler, faster to configure, and does the job without needing to think in regular expressions.

What Is mod_alias

mod_alias is a core Apache module that provides directives for mapping URLs to different locations, either on the filesystem or to entirely different URLs. It handles two main jobs:

  1. Aliasing — mapping a URL path to a different filesystem directory (via Alias, ScriptAlias)
  2. Redirection — sending clients to a different URL entirely (via Redirect, RedirectMatch, RedirectPermanent, RedirectTemp)

It’s included with Apache by default, so in most cases you don’t even need to install anything — just make sure it’s enabled.

Prerequisites

Step 1: Verify mod_alias Is Enabled

On Debian/Ubuntu, it’s enabled by default, but confirm with:

apachectl -M | grep alias

If it’s missing:

sudo a2enmod alias
sudo systemctl restart apache2

On CentOS/RHEL, it’s built into the base Apache install and loaded via httpd.conf or conf.modules.d/ by default.

Using Alias

Alias maps a URL path to a directory outside your document root. I use this constantly for things like serving uploaded files or shared assets from a separate location.

Alias /downloads /var/www/shared/downloads

<Directory /var/www/shared/downloads>
    Require all granted
</Directory>

Now, a request to http://example.com/downloads/report.pdf actually serves /var/www/shared/downloads/report.pdf, even though that folder isn’t inside your document root at all.

ScriptAlias for CGI Scripts

ScriptAlias works the same way but also tells Apache the target directory contains executable scripts:

ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/

Using Redirect

Redirect is the simplest way to send visitors from one URL to another. Basic syntax:

Redirect [status] URL-path target-URL

Permanent Redirect (301) — What I Use for SEO-Sensitive Changes

Redirect permanent /old-page.html https://example.com/new-page.html

Or explicitly with a status code:

Redirect 301 /old-page.html https://example.com/new-page.html

I use 301 redirects whenever content has permanently moved — it tells search engines to transfer ranking signals to the new URL.

Temporary Redirect (302)

Redirect 302 /maintenance-page.html https://example.com/we-are-back-soon.html

Useful for temporary situations — maintenance windows, A/B tests, or short-term promotions — where you don’t want search engines to treat the move as permanent.

Redirecting an Entire Site

If I’m migrating a whole domain, this one line handles it:

Redirect permanent / https://newdomain.com/

Using RedirectMatch for Pattern-Based Redirects

When I need to redirect based on a pattern rather than an exact path, RedirectMatch uses regular expressions:

RedirectMatch 301 ^/blog/(.*)$ https://example.com/articles/$1

This redirects every URL under /blog/ to the equivalent path under /articles/, preserving whatever came after /blog/.

Another common one — redirecting all requests for an old file extension:

RedirectMatch 301 ^/(.*)\.html$ https://example.com/$1

This strips .html from every URL, useful when migrating to a framework that uses extension-less URLs.

RedirectPermanent and RedirectTemp Shortcuts

Apache also offers shorthand versions:

RedirectPermanent /old-path https://example.com/new-path
RedirectTemp /temp-path https://example.com/temp-target

I don’t use these much since Redirect 301/Redirect 302 are more explicit and easier for other people reading my config to understand at a glance, but they’re functionally identical.

Using AliasMatch for Pattern-Based Aliasing

Just like RedirectMatch gives you regex-based redirects, AliasMatch gives you regex-based aliasing. I reach for this when a simple prefix-based Alias isn’t flexible enough:

AliasMatch ^/images/(.*)\.(jpg|jpeg|png|gif)$ /var/www/shared/media/$1.$2

This maps any image request under /images/ to a shared media directory, regardless of the specific filename, as long as the extension matches. It’s a handy middle ground between the simplicity of Alias and the full power of mod_rewrite.

Order of Precedence Matters

One thing that trips people up when they first start combining these directives is that mod_alias processes rules in the order they appear in the configuration, and it stops at the first match. If you have a broad Alias defined before a more specific one, the broad rule wins and the specific one never gets evaluated. I always put my most specific rules first and broader catch-alls last, which saves a lot of head-scratching later.

It’s also worth knowing that mod_alias directives are evaluated before request handling reaches directory-level Options and Require logic for the target path, so an Alias pointing at a restricted directory will still require the appropriate <Directory> permissions to actually serve content.

Combining Aliases and Redirects in a Virtual Host

Here’s a realistic example combining a few of these together:

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/example.com/public_html

    # Serve shared assets from outside the document root
    Alias /assets /var/www/shared/assets
    <Directory /var/www/shared/assets>
        Require all granted
    </Directory>

    # Redirect an old blog path
    RedirectMatch 301 ^/blog/(.*)$ https://example.com/articles/$1

    # Redirect a retired page
    Redirect 301 /old-promo.html https://example.com/
</VirtualHost>

Using AliasMatch for Pattern-Based Aliasing

Just as RedirectMatch extends Redirect with regex support, AliasMatch extends Alias. I use this when I need to map a pattern of URLs to a filesystem path with a captured segment:

AliasMatch ^/user-files/([0-9]+)/(.*)$ /var/www/shared/user-uploads/$1/$2

This maps /user-files/42/photo.jpg to /var/www/shared/user-uploads/42/photo.jpg — handy for multi-tenant setups where each user’s files live in a numbered subdirectory outside the main document root, without needing to hardcode a separate Alias line per user.

Testing and Reloading

Always test config syntax before reloading:

sudo apachectl configtest
sudo systemctl reload apache2   # Debian/Ubuntu
sudo systemctl reload httpd     # CentOS/RHEL

Verifying Redirects Actually Work

I always check redirects with curl -I to see the raw headers rather than trusting the browser (which can cache redirects aggressively):

curl -I https://example.com/old-page.html

Look for:

HTTP/1.1 301 Moved Permanently
Location: https://example.com/new-page.html

Real-World Use Cases

Troubleshooting Tips

Common Mistakes to Avoid

  1. Using 301 for temporary changes — search engines treat this as permanent and may be slow to “undo” it later.
  2. Forgetting the trailing slash consistency between Alias and the actual directory path — mismatches cause broken links.
  3. Creating redirect chains (A → B → C) instead of redirecting straight to the final destination — each hop adds latency and dilutes SEO value slightly.
  4. Not testing with curl -I, relying on browser behavior which can mask actual server responses due to caching.
  5. Overlapping Alias and DocumentRoot paths, causing unpredictable file resolution.

Security Best Practices

Performance Optimization

Frequently Asked Questions

Q: What’s the difference between mod_alias and mod_rewrite? A: mod_alias handles simple path mapping and redirects; mod_rewrite handles complex, condition-based URL rewriting using regular expressions and rewrite rules. For simple cases, mod_alias is easier and faster.

Q: Does Redirect support regular expressions? A: The plain Redirect directive does prefix matching only. For full regex support, use RedirectMatch.

Q: How do I redirect an entire domain to a new one? A: Use Redirect permanent / https://newdomain.com/ in the old domain’s virtual host.

Q: Will a 301 redirect pass SEO ranking to the new URL? A: Yes, 301 redirects are the standard way to transfer link equity and ranking signals to a new URL in search engines.

Q: Can I use mod_alias inside .htaccess files? A: Yes, as long as AllowOverride includes FileInfo for that directory, since Alias itself isn’t allowed in .htaccess (it must be in the main config), but Redirect and RedirectMatch are.

Summary and Key Takeaways

mod_alias covers a huge portion of the redirect and aliasing needs I run into day to day, without the complexity of regex-heavy rewrite rules. To recap:

References

Exit mobile version