<Location> Directive - Apache HTTP Server

http://httpd.apache.org/docs/current/mod/core.html#location

 

 

<Location> Directive

Description:	Applies the enclosed directives only to matching URLs
Syntax:	<Location URL-path|URL> ... </Location>
Context:	server config, virtual host
Status:	Core
Module:	core

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

<LocationMatch> Directive

Description:	Applies the enclosed directives only to regular-expression matching URLs
Syntax:	<LocationMatch regex> ... </LocationMatch>
Context:	server config, virtual host
Status:	Core
Module:	core

The <LocationMatch> directive limits the scope of the enclosed directives by URL, in an identical manner to <Location>. However, it takes a regular expression as an argument instead of a simple string. For example:

<LocationMatch "/(extra|special)/data">
    # ...
</LocationMatch>

would match URLs that contained the substring /extra/data or /special/data.

See also

• How <Directory>, <Location> and <Files> sections work for an explanation of how these different sections are combined when a request is received