Mapping URLs to Filesystem Locations

Available Languages: en | - ja | - ko | - tr

- -

This document explains how Apache uses the URL of a request - to determine the filesystem location from which to serve a - file.

Related Modules and Directives
DocumentRoot
Files Outside the DocumentRoot
User Directories
URL Redirection
Reverse Proxy
Rewriting Engine
File Not Found

Related Modules and Directives

- -

Related Modules	Related Directives
`mod_alias` `mod_proxy` `mod_rewrite` `mod_userdir` `mod_speling` `mod_vhost_alias`	`Alias` `AliasMatch` `CheckSpelling` `DocumentRoot` `ErrorDocument` `Options` `ProxyPass` `ProxyPassReverse` `Redirect` `RedirectMatch` `RewriteCond` `RewriteMatch` `ScriptAlias` `ScriptAliasMatch` `UserDir`

DocumentRoot

- -

In deciding what file to serve for a given request, Apache's - default behavior is to take the URL-Path for the request (the part - of the URL following the hostname and port) and add it to the end - of the DocumentRoot specified - in your configuration files. Therefore, the files and directories - underneath the DocumentRoot - make up the basic document tree which will be visible from the - web.

- -

Apache is also capable of Virtual - Hosting, where the server receives requests for more than one - host. In this case, a different DocumentRoot can be specified for each - virtual host, or alternatively, the directives provided by the - module mod_vhost_alias can - be used to dynamically determine the appropriate place from which - to serve content based on the requested IP address or - hostname.

Files Outside the DocumentRoot

- -

There are frequently circumstances where it is necessary to - allow web access to parts of the filesystem that are not strictly - underneath the DocumentRoot. Apache offers several - different ways to accomplish this. On Unix systems, symbolic links - can bring other parts of the filesystem under the DocumentRoot. For security reasons, - Apache will follow symbolic links only if the Options setting for the relevant - directory includes FollowSymLinks or - SymLinksIfOwnerMatch.

- -

Alternatively, the Alias directive will map any part - of the filesystem into the web space. For example, with

- -

Alias /docs /var/web

- -

the URL http://www.example.com/docs/dir/file.html - will be served from /var/web/dir/file.html. The - ScriptAlias directive - works the same way, with the additional effect that all content - located at the target path is treated as CGI scripts.

- -

For situations where you require additional flexibility, you - can use the AliasMatch and - ScriptAliasMatch - directives to do powerful regular-expression based matching and - substitution. For example,

- -

ScriptAliasMatch ^/~([a-zA-Z0-9]+)/cgi-bin/(.+) - /home/$1/cgi-bin/$2

- -

will map a request to - http://example.com/~user/cgi-bin/script.cgi to the - path /home/user/cgi-bin/script.cgi and will treat - the resulting file as a CGI script.

User Directories

- -

Traditionally on Unix systems, the home directory of a - particular user can be referred to as - ~user/. The module mod_userdir - extends this idea to the web by allowing files under each user's - home directory to be accessed using URLs such as the - following.

- -

http://www.example.com/~user/file.html

- -

For security reasons, it is inappropriate to give direct - access to a user's home directory from the web. Therefore, the - UserDir directive - specifies a directory underneath the user's home directory - where web files are located. Using the default setting of - Userdir public_html, the above URL maps to a file - at a directory like - /home/user/public_html/file.html where - /home/user/ is the user's home directory as - specified in /etc/passwd.

- -

There are also several other forms of the - Userdir directive which you can use on systems - where /etc/passwd does not contain the location of - the home directory.

- -

Some people find the "~" symbol (which is often encoded on the - web as %7e) to be awkward and prefer to use an - alternate string to represent user directories. This functionality - is not supported by mod_userdir. However, if users' home - directories are structured in a regular way, then it is possible - to use the AliasMatch - directive to achieve the desired effect. For example, to make - http://www.example.com/upages/user/file.html map to - /home/user/public_html/file.html, use the following - AliasMatch directive:

- -

AliasMatch ^/upages/([a-zA-Z0-9]+)/?(.*) - /home/$1/public_html/$2

URL Redirection

- -

The configuration directives discussed in the above sections - tell Apache to get content from a specific place in the filesystem - and return it to the client. Sometimes, it is desirable instead to - inform the client that the requested content is located at a - different URL, and instruct the client to make a new request with - the new URL. This is called redirection and is - implemented by the Redirect directive. For example, if - the contents of the directory /foo/ under the - DocumentRoot are moved - to the new directory /bar/, you can instruct clients - to request the content at the new location as follows:

- -

Redirect permanent /foo/ - http://www.example.com/bar/

- -

This will redirect any URL-Path starting in - /foo/ to the same URL path on the - www.example.com server with /bar/ - substituted for /foo/. You can redirect clients to - any server, not only the origin server.

- -

Apache also provides a RedirectMatch directive for more - complicated rewriting problems. For example, to redirect requests - for the site home page to a different site, but leave all other - requests alone, use the following configuration:

- -

RedirectMatch permanent ^/$ - http://www.example.com/startpage.html

- -

Alternatively, to temporarily redirect all pages on one site - to a particular page on another site, use the following:

- -

RedirectMatch temp .* - http://othersite.example.com/startpage.html

Reverse Proxy

- -

Apache also allows you to bring remote documents into the URL space -of the local server. This technique is called reverse -proxying because the web server acts like a proxy server by -fetching the documents from a remote server and returning them to the -client. It is different from normal proxying because, to the client, -it appears the documents originate at the reverse proxy server.

- -

In the following example, when clients request documents under the -/foo/ directory, the server fetches those documents from -the /bar/ directory on internal.example.com -and returns them to the client as if they were from the local -server.

- -

-ProxyPass /foo/ http://internal.example.com/bar/ -ProxyPassReverse /foo/ http://internal.example.com/bar/ -

- -

The ProxyPass configures -the server to fetch the appropriate documents, while the -ProxyPassReverse -directive rewrites redirects originating at -internal.example.com so that they target the appropriate -directory on the local server. It is important to note, however, that -links inside the documents will not be rewritten. So any absolute -links on internal.example.com will result in the client -breaking out of the proxy server and requesting directly from -internal.example.com.

Rewriting Engine

- -

When even more powerful substitution is required, the rewriting - engine provided by mod_rewrite - can be useful. The directives provided by this module use - characteristics of the request such as browser type or source IP - address in deciding from where to serve content. In addition, - mod_rewrite can use external database files or programs to - determine how to handle a request. The rewriting engine is capable - of performing all three types of mappings discussed above: - internal redirects (aliases), external redirects, and proxying. - Many practical examples employing mod_rewrite are discussed in the - URL Rewriting Guide.

File Not Found

- -

Inevitably, URLs will be requested for which no matching - file can be found in the filesystem. This can happen for - several reasons. In some cases, it can be a result of moving - documents from one location to another. In this case, it is - best to use URL redirection to inform - clients of the new location of the resource. In this way, you - can assure that old bookmarks and links will continue to work, - even though the resource is at a new location.

- -

Another common cause of "File Not Found" errors is - accidental mistyping of URLs, either directly in the browser, - or in HTML links. Apache provides the module - mod_speling (sic) to help with - this problem. When this module is activated, it will intercept - "File Not Found" errors and look for a resource with a similar - filename. If one such file is found, mod_speling will send an - HTTP redirect to the client informing it of the correct - location. If several "close" files are found, a list of - available alternatives will be presented to the client.

- -

An especially useful feature of mod_speling, is that it will - compare filenames without respect to case. This can help - systems where users are unaware of the case-sensitive nature of - URLs and the unix filesystem. But using mod_speling for - anything more than the occasional URL correction can place - additional load on the server, since each "incorrect" request - is followed by a URL redirection and a new request from the - client.

- -

If all attempts to locate the content fail, Apache returns - an error page with HTTP status code 404 (file not found). The - appearance of this page is controlled with the - ErrorDocument directive - and can be customized in a flexible manner as discussed in the - Custom error responses and International Server Error - Responses documents.