You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Joshua Slive <sl...@finance.commerce.ubc.ca> on 2000/12/15 01:44:16 UTC
mod_access.html
Here is another major rewrite of a module doc.
This one looks like it has not been touched much since NCSA days.
The patch is below, and the full file is at:
http://garibaldi.commerce.ubc.ca:8080/ap13/htdocs/manual/mod/mod_access.html
One question for you folks:
In the Order directive documentation it says (in bold)
'Note that in all cases every Allow and Deny statement is evaluated, there
is no "short-circuiting".'
I have no idea what that is trying to say. Any ideas?
Some of the major changes:
- Add a "summary"
- Add several more examples
- Combine the "Allow from host" and "Allow from env=" documentation. This
makes the "Syntax" line look pretty confusing, but it is more technically
correct, since it appears from the code that env= and host arguments can
be mixed on the Allow line. If people think this makes things more
confusing, I may be convinced to change it back. However, I think
it is an improvement.
- Remove all the duplicate documentation from the "Deny" directive,
and just reference the "Allow" directive instaead.
- Add quite a bit more discussion and examples to the Order directive.
I still say that, if we were to rewrite apache today, it would be clearer
and easier if directives where just evaluated in the order they
appear. At the moment, the Order directive controls order of evaluation,
but only withing the same "scope". For example, an Allow in a <Location>
section will be evaluated after a Deny in a <Directory> section,
regardless of Order. This is very confusing. I have tried to at least
document this fact.
Comments VERY welcome.
Joshua
Index: mod_access.html
===================================================================
RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/mod/mod_access.html,v
retrieving revision 1.25
diff -u -d -b -r1.25 mod_access.html
--- mod_access.html 2000/12/08 18:42:22 1.25
+++ mod_access.html 2000/12/15 00:31:52
@@ -16,8 +16,8 @@
<H1 ALIGN="CENTER">Module mod_access</H1>
<P>
-This module provides access control based on client hostname or IP
-address.
+This module provides access control based on client hostname, IP
+address, or other characteristics of the client request.
</P>
<P><A
@@ -36,14 +36,31 @@
><STRONG>Module Identifier:</STRONG></A> access_module
</P>
+<h2>Summary</h2>
+<p>The directives provided by mod_access are used in <CODE><A
+HREF="core.html#directory"><Directory></A>, <A
+HREF="core.html#files"><Files></A>,</code> and <code> <A
+HREF="core.html#location"><Location></A></code> sections as
+well as <code><a
+href="core.html#accessfilename">.htaccess</a></code> files
+to control access to particular parts of the server. Access
+can be controlled based on the client hostname, IP address,
+or other characteristics of the client request, as captured
+in <a href="../env.html">environment variables</a>.</p>
+
+<p>Both host-based access restrictions and password-based
+authentication may be implemented simultaneously. In
+that case, the <a href="core.html#satsify">Satisfy</a> directive
+is used to determine how the two sets of restrictions
+interact.</p>
+
+
<H2>Directives</H2>
<UL>
<LI><A HREF="#allow">Allow</A>
-<LI><A HREF="#allowfromenv">Allow from env=</A>
<LI><A HREF="#deny">Deny</A>
-<LI><A HREF="#denyfromenv">Deny from env=</A>
<LI><A HREF="#order">Order</A>
</UL>
@@ -53,13 +70,15 @@
<HR>
-<H2><A NAME="allow">Allow directive</A></H2>
+<H2><A NAME="allow">Allow</a> <a name="allowfromenv">directive</A></H2>
<P>
<!--%plaintext <?INDEX {\tt Allow} directive> -->
<A
HREF="directive-dict.html#Syntax"
REL="Help"
-><STRONG>Syntax:</STRONG></A> Allow from <EM>host</em> [<em>host</em>] ...<BR>
+><STRONG>Syntax:</STRONG></A> Allow from
+ all|<EM>host</em>|env=<em>variablename</em>
+ [<em>host</em>|env=<em>variablename</em>] ...<BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
@@ -77,75 +96,63 @@
REL="Help"
><STRONG>Module:</STRONG></A> mod_access
</P>
+
<P>
-The Allow directive affects which hosts can access a given directory.
-<EM>Host</EM> is one of the following:
-</P>
+The <code>Allow</code> directive affects which hosts can access an
+area of the server. Access can be controlled by hostname, IP Address,
+IP Address range, or by other characteristics of the client
+request captured in environment variables.</p>
+
+<p>The first argument to this directive is always
+<code>from</code>. The subsequent arguments can take three different
+forms. If <code>Allow from all</code> is specified, then all hosts
+are allowed access. To allow only particular hosts or groups of hosts
+to access the server, the <em>host</em> can be specified in any of the
+following formats:</p>
<DL>
-<DT><CODE>all</CODE>
-<DD>All hosts are allowed access
-<DT>A (partial) domain-name
-<DD>Hosts whose names match, or end in, this string are allowed access.
-<DT>A full IP address
-<DD>An IP address of a host allowed access
-<DT>A partial IP address
-<DD>The first 1 to 3 bytes of an IP address, for subnet restriction.
-<DT>A network/netmask pair (<STRONG>Apache 1.3 and later</STRONG>)
-<DD>A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet
- restriction. (<EM>i.e.</EM>, 10.1.0.0/255.255.0.0)
-<DT>A network/nnn CIDR specification (<STRONG>Apache 1.3 and later</STRONG>)
-<DD>Similar to the previous case, except the netmask consists of nnn
- high-order 1 bits. (<EM>i.e.</EM>, 10.1.0.0/16 is the same as 10.1.0.0/255.255.0.0)
+
+<DT>A (partial) domain-name</dt> <dd>Example: <code>Allow from
+apache.org</code><br> Hosts whose names match, or end in, this string
+are allowed access. Only complete components are matched, so the
+above example will match <code>foo.apache.org</code> but it will not
+match <code>fooapache.org</code>. This configuration will cause the
+server to perform a reverse DNS lookup on the client IP address,
+regardless of the setting of <a
+href="core.html#hostnamelookups">HostNameLookups</a> directive.</dd>
+
+<DT>A full IP address</dt>
+<DD>Example: <code>Allow from 10.1.2.3</code><br>
+An IP address of a host allowed access</dd>
+
+<DT>A partial IP address</dt>
+<dd>Example: <code>Allow from 10.1</code><br>
+The first 1 to 3 bytes of an IP address, for subnet restriction.</dd>
+
+<DT>A network/netmask pair</dt>
+<dd>Example: <code>Allow from 10.1.0.0/255.255.0.0</code><br>
+ A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet
+ restriction. (Apache 1.3 and later)</dd>
+
+<DT>A network/nnn CIDR specification</dt> <dd>Example: <code>Allow
+from 10.1.0.0/16</code><br> Similar to the previous case, except the
+netmask consists of nnn high-order 1 bits. (Apache 1.3 and
+later)</dd>
</DL>
-<P>
-Example:
-</P>
-<BLOCKQUOTE><CODE>Allow from .ncsa.uiuc.edu</CODE></BLOCKQUOTE>
-<P>
-All hosts in the specified domain are allowed access.
-</P>
-<P>
-Note that this compares whole components; <CODE>bar.edu</CODE>
-would not match <CODE>foobar.edu</CODE>.
-</P>
-<P>
-See also <A HREF="#allowfromenv">Allow from env=</A>, <A
-HREF="#deny">Deny</A> and <A HREF="#order">Order</A>.
-</P>
-<HR>
+<p>Note that the last three examples above match exactly the
+same set of hosts.</p>
-<H2><A NAME="allowfromenv">Allow from env= directive</A></H2>
+<p>The third format of the arguments to the <code>Allow</code>
+directive allows access to the server to be controlled based on the
+existence of an <a href="../env.html">environment variable</a>. The
+server provides the ability to set environment variables in a flexible
+way based on characteristics of the client request using the
+directives provided by <a href="mod_setenvif.html">mod_setenvif</a>.
+Therefore, this directive can be used to allow access based
+on such factors as the clients <code>User-Agent</code> (browser type),
+<code>Referer</code>, or other HTTP request header fields.</P>
<P>
-<STRONG>Syntax:</STRONG> Allow from
- env=<EM>variablename</EM><BR>
-<A
- HREF="directive-dict.html#Context"
- REL="Help"
-><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
-<A
- HREF="directive-dict.html#Override"
- REL="Help"
-><STRONG>Override:</STRONG></A> Limit<BR>
-<A
- HREF="directive-dict.html#Status"
- REL="Help"
-><STRONG>Status:</STRONG></A> Base<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_access<BR>
-<A
- HREF="directive-dict.html#Compatibility"
- REL="Help"
-><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above
-</P>
-<P>
-The <CODE>Allow from env</CODE> directive controls access to a directory by the
-existence (or non-existence) of an environment variable.
-</P>
-<P>
Example:
</P>
<BLOCKQUOTE><PRE>
@@ -156,21 +163,25 @@
Allow from env=let_me_in
</Directory>
</PRE></BLOCKQUOTE>
-In this case browsers with the user-agent string <TT>KnockKnock/2.0</TT> will
-be allowed access, and all others will be denied.
+
+<p>In this case browsers with the user-agent string
+<TT>KnockKnock/2.0</TT> will be allowed access, and all others will be
+denied.</p>
<P>
-See also <A HREF="#denyfromenv">Deny from env=</A>, <A HREF="#order">Order</A>
+See also <A HREF="#order">Order</A>
and <A HREF="mod_setenvif.html#SetEnvIf">SetEnvIf</A>.
</P>
<HR>
-<H2><A NAME="deny">Deny directive</A></H2>
+<H2><A NAME="deny">Deny</a> <a name="denyfromenv">directive</A></H2>
<P>
<!--%plaintext <?INDEX {\tt Deny} directive> -->
<A
HREF="directive-dict.html#Syntax"
REL="Help"
-><STRONG>Syntax:</STRONG></A> Deny from <EM>host</em> [<em>host</em>] ...<BR>
+><STRONG>Syntax:</STRONG></A> Deny from
+ all|<EM>host</em>|env=<em>variablename</em>
+ [<em>host</em>|env=<em>variablename</em>] ...<BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
@@ -188,93 +199,14 @@
REL="Help"
><STRONG>Module:</STRONG></A> mod_access
</P>
-<P>
-The <CODE>Deny</CODE> directive affects which hosts can access a given directory.
-<EM>Host</EM> is one of the following:
-</P>
-<DL>
-<DT><CODE>all</CODE>
-<DD>all hosts are denied access
-<DT>A (partial) domain-name
-<DD>host whose name is, or ends in, this string are denied access.
-<DT>A full IP address
-<DD>An IP address of a host denied access
-<DT>A partial IP address
-<DD>The first 1 to 3 bytes of an IP address, for subnet restriction.
-<DT>A network/netmask pair (<STRONG>Apache 1.3 and later</STRONG>)
-<DD>A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet
- restriction. (<EM>i.e.</EM>, 10.1.0.0/255.255.0.0)
-<DT>A network/nnn CIDR specification (<STRONG>Apache 1.3 and later</STRONG>)
-<DD>Similar to the previous case, except the netmask consists of nnn
- high-order 1 bits. (<EM>i.e.</EM>, 10.1.0.0/16 is the same as 10.1.0.0/255.255.0.0)
-</DL>
-<P>
-Example:
-</P>
-<BLOCKQUOTE><CODE>Deny from 16</CODE></BLOCKQUOTE>
-<P>
-All hosts in the specified network are denied access.
-</P>
-<P>
-Note that this compares whole components; <CODE>bar.edu</CODE>
-would not match <CODE>foobar.edu</CODE>.
-</P>
-<P>
-See also <A HREF="#denyfromenv">Deny from env=</A>, <A
-HREF="#allow">Allow</A> and <A HREF="#order">Order</A>.
-</P>
-
-<HR>
-<H2><A NAME="denyfromenv">Deny from env= directive</A></H2>
-
-<P>
-<STRONG>Syntax:</STRONG> Deny from
- env=<EM>variablename</EM><BR>
-<A
- HREF="directive-dict.html#Context"
- REL="Help"
-><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
-<A
- HREF="directive-dict.html#Override"
- REL="Help"
-><STRONG>Override:</STRONG></A> Limit<BR>
-<A
- HREF="directive-dict.html#Status"
- REL="Help"
-><STRONG>Status:</STRONG></A> Base<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_access<BR>
-<A
- HREF="directive-dict.html#Compatibility"
- REL="Help"
-><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above
-</P>
-<P>
-The <CODE>Deny from env</CODE> directive controls access to a directory by the
-existence (or non-existence) of an environment variable.
-</P>
-<P>
-Example:
-</P>
-<BLOCKQUOTE><PRE>
-SetEnvIf User-Agent ^BadRobot/0.9 go_away
-<Directory /docroot>
- Order Allow,Deny
- Allow from all
- Deny from env=go_away
-</Directory>
-</PRE></BLOCKQUOTE>
-In this case browsers with the user-agent string <TT>BadRobot/0.9</TT> will
-be denied access, and all others will be allowed.
+<p>This directive allows access to the server to be restricted based
+on host name or environment variables. The arguments for the directive are
+identical to the arguments for the <a href="#allow">Allow</a>
+directive.</p>
-<P>
-See also <A HREF="#allowfromenv">Allow from env=</A>, <A
-HREF="#order">Order</A> and <A
-HREF="mod_setenvif.html#SetEnvIf">SetEnvIf</A>.
-</P>
+<p>See also <A HREF="#order">Order</A>
+and <A HREF="mod_setenvif.html#SetEnvIf">SetEnvIf</A>.</p>
<HR>
<H2><A NAME="order">Order directive</A></H2>
@@ -318,30 +250,75 @@
<DT>Allow,Deny
<DD>the <CODE>Allow</CODE> directives are evaluated before the <CODE>Deny</CODE>
directives. (The initial state is FORBIDDEN.)
-<DT>Mutual-failure
-<DD>Only those hosts which appear on the <CODE>Allow</CODE> list and do not
-appear on the <CODE>Deny</CODE> list are granted access. (The initial state is
-irrelevant.) This ordering has the same effect as <code>Order Allow,Deny</code>
-and is deprecated in favor of that configuration.
+
+<DT>Mutual-failure <DD>Only those hosts which appear on the
+<CODE>Allow</CODE> list and do not appear on the <CODE>Deny</CODE>
+list are granted access. (The initial state is irrelevant.) This
+ordering has the same effect as <code>Order Allow,Deny</code> and is
+deprecated in favor of that configuration.
</DL>
-<P>
-Keywords may only be separated by a comma; no whitespace is allowed between
-them.
-<STRONG>Note that in all cases every <CODE>Allow</CODE> and <CODE>Deny</CODE>
-statement is evaluated, there is no "short-circuiting".</STRONG>
+
+<P>Keywords may only be separated by a comma; no whitespace is allowed
+between them. <STRONG>Note that in all cases every <CODE>Allow</CODE>
+and <CODE>Deny</CODE> statement is evaluated, there is no
+"short-circuiting".</STRONG>
</P>
-<P>
-Example:
+
+<P>In the following example, all hosts in the apache.org domain are
+allowed access; all other hosts are denied access.
</P>
+
<BLOCKQUOTE><CODE>
Order Deny,Allow<BR>
Deny from all<BR>
- Allow from .ncsa.uiuc.edu<BR>
+ Allow from apache.org<BR>
</CODE></BLOCKQUOTE>
-<P>
-Hosts in the ncsa.uiuc.edu domain are allowed access; all other hosts are
-denied access.
+
+<P>In the next example, all hosts in the apache.org domain are allowed
+access, except for the hosts which are in the foo.apache.org subdomain,
+who are denied access. All hosts not in the apache.org domain are
+denied access because the default state is <em>forbidden</em>.
</P>
+
+<blockquote><code>
+ Order Allow,Deny<br>
+ Allow from apache.org<br>
+ Deny from foo.apache.org<br>
+</code></blockquote>
+
+<p>Note that if the <code>Order</code> in the last example is changed
+to <code>Deny,Allow</code>, then all hosts will be allowed access
+since the default state will be <em>OK</em>, and the
+<code>Allow from apache.org</code> will be evaluated last and
+will override the <code>Deny from foo.apache.org</code>.</p>
+
+<p>The presence of an <code>Order</code> directive can
+affect access to a part of the server even in the absence
+of accompanying <code>Allow</code> and <code>Deny</code>
+directives because of its effect on the default access state.
+For example,</p>
+
+<blockquote><code>
+<Directory /www><br>
+ Order Allow,Deny<br>
+</Directory>
+</code></blockquote>
+
+<p>will deny all access to the <code>/www</code> directory because
+the default access state will be set to <em>forbidden</em>.</p>
+
+
+<p>The <code>Order</code> directive controls the order of access
+directive processing only within each phase of the server's
+configuration processing. This implies, for example, that an
+<code>Allow</code> or <code>Deny</code> directive occurring
+in a <Location> section will always be evaluated after
+an <code>Allow</code> or <code>Deny</code> directive occurring
+in a <Directory> section or <code>.htaccess</code> file,
+regardless of the setting of the <code>Order</code> directive.
+For details on the merging of configuration sections,
+see the documentation on <a href="../sections.html">How Directory,
+Location and Files sections work</a>.</p>
<P>See also: <A HREF="#deny">Deny</A> and <A HREF="#allow">Allow</A>.
<!--#include virtual="footer.html" -->