Apache: Aliasing and Redirection

It's common for a client to send a request for a file that either does not exist on the server, or exists in a different location. This can occur for a variety of reasons. You might move your files around the server (or to a completely different server), or you may want to present a logical file system structure to connecting clients.

Normally, these actions result in error message, but Apache's aliasing and redirection capabilities, available thanks to the mod_alias module, allow you to handle these scenarios by directing clients to the new resource location.

mod_alias also allows you to inform clients that the requested URL is incorrect.

Aliases allow the server to take one URL and translate it into a different one. They then transparently deliver the new resource to the client, without it even realizing that any sort of redirection took place. This can be quite useful, when changing your website's links to friendly URLs.

Aliases can also access files outside of the public document root by mapping any part of the file system into the web space, making them visible on the web, but not to certain shell accounts and CGI scripts, for example. On the other hand, sometimes you want to inform the client of the new content location, and ask them to make a new request for that location. This is where Apache's redirection-related directives come into play.

Alias Directive

The Alias directive takes a URL path and seamlessly substitutes it with a file or directory path on the system (i.e. it maps a resource's URL to its physical location in the file system, regardless of its location):

Alias /images/ /ftp/public/images/

Aliases can also access files outside the public document root.

The above example maps the /images/ URL prefix to the /ftp/public/images/ directory prefix; so a request to http://www.example-domain.com/images/example-image.jpg automatically translates to /ftp/public/images/example-image.jpg.

Note that, if you include a trailing / on the URL path, then the server requires a trailing / in order to expand the alias. For example, a URL path of /images will not alias in the above example. Likewise, omitting the slash on the URL path requires you to also omit the slash from the file path.

AliasMatch Directive

The AliasMatch directive works the same way as Alias, but it allows you to use regular expressions to match a URL pattern with a file or directory path. The supplied regular expression matches against the requested URL:

AliasMatch /images/(.*)$ /ftp/public/images/$1

This example allows you to simply and easily refer to image files from any direct subdirectory under the requested document's relative path. The $1 refers to the value of the matched string in the requested URL. Hence, a request for www.example-site.com/some_dir/images/img1.jpg maps to /ftp/public/images/img1.jpg. This also allows you to store all of your images in one place, regardless of where they are accessed.

One subtle difference between Alias and AliasMatch is that Alias automatically copies any additional part of the URI onto the end of the file path on the right. AliasMatch does not.

In other words, changing Alias to AliasMatch will not have the same effect. At a minimum, you need to add ^ to the beginning of the regular expression and $ to the end, and add $1 to the end of the replacement. For example, the following statement:

Alias /images/ /ftp/public/images/

Is not equivalent to:

AliasMatch /images/ /ftp/public/images/

Which sends all requests that contain /images/ in the URL to /ftp/public/images/. In order for AliasMatch to achieve the same results, you need to use the following:

AliasMatch ^/images/(.*)$ /ftp/public/images/$1

ScriptAlias Directive

The ScriptAlias directive exhibits the same functionality as the Alias directive, but it also marks the target directory as being a CGI-capable folder. That is, Apache assumes all files contained within the directory are CGI scripts, and it will attempt to execute those files as CGI scripts, when it receives a request for one of the files.

CGI (Common Gateway Interface) scripts are basically external, stand-alone, content-generating programs, which allow you to create dynamic content for your website.

ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/

The above example causes a request for http://www.example-site.com/cgi-bin/some_cgi_script to mark the /usr/local/apache2/cgi-bin/ directory as a CGI script directory, therefore executing the script /usr/local/apache2/cgi-bin/some_cgi_script. This has the exact same effect as the following alternative configuration:

Alias /cgi-bin/ /usr/local/apache2/cgi-bin/
<Location /cgi-bin>
    SetHandler cgi-script
    Options +ExecCGI
</Location>

ScriptAliasMatch Directive

The ScriptAliasMatch directive behaves similarly to ScriptAlias, except it accepts a regular expression as a source URL instead of simple prefix matching.

Redirect Directive

mod_alias also allows you to inform clients that the requested URL is incorrect, causing the client to make another request for a different resource. This is accomplished, using the Redirect directive.

The Redirect directive works in a very similar way to the Alias directive, except that it maps a given URL prefix to a different URL (which is basically why the client is aware of the redirection). It can also accept an optional status argument.

Redirect permanent /images http://www.another-example-site.com/images

In the above example, a request for www.example-site.com/images/img1.gif would redirect to http://www.another-example-site.com/images/img1.gif.

If the request URL comes with a query string, the query is left intact, unless the Redirect directive specifies a destination URL that specifies a new query string.

For example, a request for www.example-site.com/images?img-name=1.gif will map to http://www.another-example-site.com/images?img-name=1.gif in the example above. If, however, we change the rule to:

Redirect permanent /images http://www.another-example-site.com/images?q=new-value

Then a request for www.example-site.com/images?img-name=1.gif will map to http://www.another-example-site.com/images?q=new-value.

Aliases allow the server to take one URL and translate it into a different URL.

When performing a redirection, the server sends an HTTP response with a status code specific to the redirection type (as opposed to a 200 or 404, for example).

The Redirect directive allows one of the following status codes (the corresponding symbolic names are between brackets) to be specified, and thus returned along with the response:

Redirects are processed before aliases, if they are found within the same context.

301 (permanent): The resource has been permanently moved to a new location. Clients with caches and proxies need to update their data to point to the new URI, unless a Cache-Control or Expires response header states otherwise. This status also tells proxies to automatically perform the redirection on their own for future requests without getting back to the server.
302 (temp): The resource has been temporarily moved to a new location. Clients with caches and proxies need NOT update their data, but should continue to use the same URL for future requests, unless a Cache-Control or Expires response header states otherwise. This status also tells proxies to check with the server before performing the redirection for future requests.
303 (seeother): The response can be found under another URL and needs to be retrieved using a GET request, regardless of the original request method used. This indicates that the resource has been replaced.
410 (gone): The resource is no longer available; it has been permanently removed.

If the status argument is omitted, a default HTTP status 302 (temporary redirection) will be assumed.

Of course, you can use any (valid!) HTTP status, other than the four listed above, but, in that case, you will need to use the corresponding status code values because mod_alias only defines symbolic names for the above redirection types. If you use a status code that is not in the range of 300-399, then the second URL argument (i.e. the replacement URL) must be omitted.

RedirectMatch Directive

RedirectMatch works in the same manner as the Redirect directive does, but, as you probably guessed, it uses a regular expression instead of a prefix as the source URL. This gives you a more flexible means of matching URLs.

For example, to redirect all requests for GIF images to another server, you can use the following rule:

RedirectMatch (.*)\.gif$ http://www.example-site.com$1.gif

And, like Redirect, RedirectMatch allows you to use a status argument to specify the type of redirection. Since the above example does not explicitly set a status parameter, a temporary redirection (302) is assumed.

You also have two more directives, namely: RedirectPermanent and RedirectTemp, both of which work in the same way as Redirect permanent ... and Redirect temp ..., respectively.

Directive Processing Order

To avoid unexpected results, it is important to note that all redirects are processed before aliases, if they are found within the same context (for example, the same <Directory> or <VirtualHost> container).

If a server receives a request that matches a Redirect or RedirectMatch directive, it will apply that redirect before processing any aliases.

This means that, if you have matching aliases already configured, they will never get the chance to apply, because the necessary redirection will have already occurred.

Second, aliases and redirects are applied in the order they appear in the server configuration files (first in, first processed). For this reason, make sure you list the most specific rule first. For example, the following configuration:

Alias /sub-dir1/sub-dir2 /dir3
Alias /sub-dir1 /dir4

Has a different effect than:

Alias /sub-dir1 /dir4
Alias /sub-dir1/sub-dir2 /dir3

Where Alias /sub-dir1 /dir4 will always match before Alias /sub-dir1/sub-dir2 /dir3.

Conclusion

Today, we looked at the capabilities and options you have with mod_alias, allowing you to easily and quickly perform simple URL-mapping and redirection tasks with minimal effort. It is a great and light-weight utility that gets the job done with no hassle and minimum resource consumption.

The next post in the series will review mod_rewrite, a very powerful and flexible tool used for URL handling. mod_rewrite allows you to specify an unlimited number of rules and conditions, including server variables, environment variables, HTTP headers, database look-ups and much more to control URL manipulation on a whole different level. Stay tuned!

HIGHLIGHTS OF THE DAY