The <Location> directive
limits the scope of the enclosed directives by URL. It is similar to the
<Directory>
directive, and starts a subsection which is terminated with a
</Location> directive. <Location> sections are processed in the
order they appear in the configuration file, after the <Directory> sections and
.htaccess files are read, and after the <Files> sections.
<Location> sections operate
completely outside the filesystem. This has several consequences.
Most importantly, <Location>
directives should not be used to control access to filesystem
locations. Since several different URLs may map to the same
filesystem location, such access controls may by circumvented.
The enclosed directives will be applied to the request if the path component
of the URL meets any of the following criteria:
- The specified location matches exactly the path component of the URL.
- The specified location, which ends in a forward slash, is a prefix
of the path component of the URL (treated as a context root).
- The specified location, with the addition of a trailing slash, is a
prefix of the path component of the URL (also treated as a context root).
In the example below, where no trailing slash is used, requests to
/private1, /private1/ and /private1/file.txt will have the enclosed
directives applied, but /private1other would not.
<Location "/private1">
# ...
</Location>
In the example below, where a trailing slash is used, requests to
/private2/ and /private2/file.txt will have the enclosed
directives applied, but /private2 and /private2other would not.
<Location "/private2/">
# ...
</Location>
When to use <Location>
Use <Location> to apply
directives to content that lives outside the filesystem. For
content that lives in the filesystem, use <Directory> and <Files> . An exception is
<Location "/"> , which is an easy way to
apply a configuration to the entire server.
For all origin (non-proxy) requests, the URL to be matched is a
URL-path of the form /path/ . No scheme, hostname,
port, or query string may be included. For proxy requests, the
URL to be matched is of the form
scheme://servername/path , and you must include the
prefix.
The URL may use wildcards. In a wild-card string, ? matches
any single character, and * matches any sequences of
characters. Neither wildcard character matches a / in the URL-path.
Regular expressions
can also be used, with the addition of the ~
character. For example:
<Location ~ "/(extra|special)/data">
#...
</Location>
would match URLs that contained the substring /extra/data
or /special/data . The directive <LocationMatch> behaves
identical to the regex version of <Location> , and is preferred, for the
simple reason that ~ is hard to distinguish from
- in many fonts.
The <Location>
functionality is especially useful when combined with the
SetHandler
directive. For example, to enable status requests but allow them
only from browsers at example.com , you might use:
<Location "/status">
SetHandler server-status
Require host example.com
</Location>
Note about / (slash)
The slash character has special meaning depending on where in a
URL it appears. People may be used to its behavior in the filesystem
where multiple adjacent slashes are frequently collapsed to a single
slash (i.e., /home///foo is the same as
/home/foo ). In URL-space this is not necessarily true.
The <LocationMatch>
directive and the regex version of <Location> require you to explicitly specify multiple
slashes if that is your intention.
For example, <LocationMatch "^/abc"> would match
the request URL /abc but not the request URL
//abc . The (non-regex) <Location> directive behaves similarly when used for
proxy requests. But when (non-regex) <Location> is used for non-proxy requests it will
implicitly match multiple slashes with a single slash. For example,
if you specify <Location "/abc/def"> and the
request is to /abc//def then it will match.
See also
- How <Directory>, <Location>
and <Files> sections work for an explanation of how these
different sections are combined when a request is received.
-
LocationMatch
