From: pcs Date: Sun, 24 Aug 1997 14:16:04 +0000 (+0000) Subject: Add document explaining how Directory, Location and Files sections X-Git-Tag: APACHE_1_3b1~24 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2228b8d6c679a1edd9025740c25c7fd7c9268a1f;p=apache Add document explaining how Directory, Location and Files sections are merged. Based on Dean's explanation from PR#586. Link to this doc from the directive descriptions in core.html. PR: 586 git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@79051 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/core.html b/docs/manual/mod/core.html index daa6467917..55e6252da9 100644 --- a/docs/manual/mod/core.html +++ b/docs/manual/mod/core.html @@ -413,7 +413,13 @@ page for more details. The directory sections typically occur in the access.conf file, but they may appear in any configuration file. <Directory> directives cannot nest, and cannot appear in a <Limit> section. -

+ +See also: How Directory, +Location and Files sections work for an explanation of how these +different sections are combined when a request is received + +

<DirectoryMatch>

Syntax: <DirectoryMatch regex> ... </DirectoryMatch>
@@ -435,7 +441,11 @@ argument a regular expression. For example:

See Also: <Directory> for a description of how -regular expressions are mixed in with normal <Directory>s.

+regular expressions are mixed in with normal <Directory>s. +
+See also: How Directory, +Location and Files sections work for an explanation of how these +different sections are combined when a request is received

@@ -573,7 +583,13 @@ file-by-file level. When used in an .htaccess file, if the filename does not begin with a / character, the directory being applied will be prefixed automatically. -

+ +See also: How Directory, +Location and Files sections work for an explanation of how these +different sections are combined when a request is received + +

<FilesMatch>

Syntax: <FilesMatch regex> @@ -593,6 +609,10 @@ does. However, it accepts a regular expression. For example:

would match most common Internet graphics formats.

+See also: How Directory, +Location and Files sections work for an explanation of how these +different sections are combined when a request is received +

Group directive

@@ -919,6 +939,12 @@ from browsers at foo.com, you might use: allow from .foo.com </Location> + +

+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>

@@ -942,6 +968,10 @@ expression as an argument instead of a simple string. For example:

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 +

LockFile directive

@@ -1681,7 +1711,10 @@ href="#listen">Listen. See also: In-depth description of Virtual Host matching
See also: -Setting which addresses and ports Apache uses +Setting which addresses and ports Apache uses
+See also: How Directory, +Location and Files sections work for an explanation of how these +different sections are combined when a request is received

diff --git a/docs/manual/sections.html b/docs/manual/sections.html new file mode 100644 index 0000000000..a145a56531 --- /dev/null +++ b/docs/manual/sections.html @@ -0,0 +1,139 @@ + + +How Directory, Location and Files sections work + + + + + +

How Directory, Location and Files sections work

+ +The sections <Directory>, <Location> and <Files> can contain +directives which only apply to specified directories, URLs or files +respectively. Also htaccess files can be used inside a directory to +apply directives to that directory. This document explains how these +different sections differ and how they relate to each other when +Apache decides which directives apply for a particular directory or +request URL. + +

Directives allowed in the sections

+ +Everything that is syntactically allowed in +<Directory> is also allowed in +<Location> (except a sub-<Files> +section, but the code doesn't test for that, Lars has an open bug +report on that). Semantically however some things, and the most +notable is AllowOverrides, make no sense in +<Location>. The same for +<Files> -- syntactically everything is fine, but +semantically some things are different. + +

How the sections are merged

+ +The order of merging is: + +

+ + <Directory> (except regular expressions) and + .htaccess done simultaneously (with .htaccess overriding + <Directory>) + +
+ <DirectoryMatch>, and + <Directory> with regular expressions + +
<Files> and <FilesMatch> done simultaneously +
<Location> and <LocationMatch> done simultaneously +

+ +Apart from <Directory>, each group is processed in +the order that they appear in the configuration +files. <Directory> (group 1 above) is processed in +the order shortest directory component to longest. If multiple +<Directory> sections apply to the same directory +they they are processed in the configuration file order. The +configuration files are read in the order httpd.conf, srm.conf and +access.conf. Configurations included via the Include +directive will be treated as if they where inside the including file +at the location of the Include directive. + +

+ +Sections inside <VirtualHost> sections are applied +after the corresponding sections outside the virtual host +definition. This allows virtual hosts to override the main server +configuration. (Note: this only works correctly from 1.2.2 and 1.3a2 +onwards. Before those releases sections inside virtual hosts were +applied before the main server). + +

Notes about using sections

+ +The general guidelines are: + +

+ +

+ If you are attempting to match objects at the filesystem level + then you must use <Directory> and/or + <Files>. +
+ If you are attempting to match objects at the URL level then you + must use <Location> +

+ +But a notable exception is: + +

+ proxy control is done via <Directory>. This is + a legacy mistake because the proxy existed prior to + <Location>. A future version of the config + language should probably switch this to + <Location>. +

+ +Note also that modifying .htaccess parsing during Location doesn't do +anything because .htaccess parsing has already occured. + +

+ +Another note: +

+ +

+ There is actually a + <Location>/<LocationMatch> + sequence performed just before the name translation phase (where + Aliases and DocumentRoots are used to + map URLs to filenames). The results of this sequence are + completely thrown away after the translation has completed. +

+ + + diff --git a/docs/manual/sections.html.en b/docs/manual/sections.html.en new file mode 100644 index 0000000000..a145a56531 --- /dev/null +++ b/docs/manual/sections.html.en @@ -0,0 +1,139 @@ + + +How Directory, Location and Files sections work + + + + + +

How Directory, Location and Files sections work

Directives allowed in the sections

How the sections are merged

+ +The order of merging is: + +

+ + <Directory> (except regular expressions) and + .htaccess done simultaneously (with .htaccess overriding + <Directory>) + +
+ <DirectoryMatch>, and + <Directory> with regular expressions + +
<Files> and <FilesMatch> done simultaneously +
<Location> and <LocationMatch> done simultaneously +

Notes about using sections

+ +The general guidelines are: + +

+ +

+ If you are attempting to match objects at the filesystem level + then you must use <Directory> and/or + <Files>. +
+ If you are attempting to match objects at the URL level then you + must use <Location> +

+ +But a notable exception is: + +

+ proxy control is done via <Directory>. This is + a legacy mistake because the proxy existed prior to + <Location>. A future version of the config + language should probably switch this to + <Location>. +

+ +Note also that modifying .htaccess parsing during Location doesn't do +anything because .htaccess parsing has already occured. + +

+ +Another note: +

+ +

+ There is actually a + <Location>/<LocationMatch> + sequence performed just before the name translation phase (where + Aliases and DocumentRoots are used to + map URLs to filenames). The results of this sequence are + completely thrown away after the translation has completed. +

+ + +