Recipe 5.2 Mapping a URL to a Directory

Problem

You want to serve content out of a directory other than the DocumentRoot directory. For example, you may have an existing directory of documents, which you want to have on your web site that you do not want to move into the Apache document root.

Solution

Alias /desired-URL-prefix /path/to/other/directory

Discussion

The example given maps URLs starting with /desired-URL-prefix to files in the /path/to/other/directory directory. For example, a request for the URL:

http://example.com/desired/something.html

results in the file /path/to/other/directory/something.html being sent to the client.

This same effect could be achieved by simply creating a symbolic link from the main document directory to the target directory and turning on the Options +FollowSymLinks directive.^[1] However, using Alias explicitly allows you to keep track of these directories more easily. Creating symlinks to directories makes it hard to keep track of the location of all of your content. Additionally, a stray symlink may cause you to expose a portion of your filesystem that you did not intend to.

^[1] See the documentation for the Option directive at http://httpd.apache.org/docs/mod/core.html#options.

You may also need to add a few configuration directives to permit access to the directory that you are mapping to. An error message (in your error_log file) saying that the request was "denied by server configuration" usually indicates this condition. It is fairly common—and recommended in the documentation (http://httpd.apache.org/docs/misc/security_tips.html#protectserverfiles)—to configure Apache to deny all access, by default, outside of the DocumentRoot directory. Thus, you must override this for the directory in question, with a configuration block as shown below:

<Directory /path/to/other/directory>
    Order allow,deny
    Allow from all
</Directory>

This permits access to the specified directory.

Note that the Alias is very strict with respect to slashes. For example, consider an Alias directive as follows:

Alias /puppies/ /www/docs/puppies/

This directive aliases URLs starting with /puppies/ but does not alias the URL /puppies. This may result in a trailing slash problem. That is, if a user attempts to go to the URL http://example.com/puppies he gets a 404 error, whereas if he goes to the URL http://example.com/puppies/ with the trailing slash, he receives content from the desired directory. To avoid this problem, create Aliases without the trailing slash on each argument.

Finally, make sure that if you have a trailing slash on the first argument to Alias, you also have one on the second argument. Consider the following example:

Alias /icons/ /usr/local/apache/icons

A request for http://example.com/icons/test.gif results in Apache attempting to serve the file /usr/local/apache/iconstest.gif rather than the expected /usr/local/apache/icons/test.gif.

See Also

• http://httpd.apache.org/docs/mod/mod_alias.html

• http://httpd.apache.org/docs/mod/core.html#options