slive 00/12/16 13:36:08
Modified: htdocs/manual/mod mod_access.html
Log:
Major rewrite of mod_access documentation.
Submitted by: Joshua Slive, Cliff Woolley
Revision Changes Path
1.26 +184 -186 httpd-docs-1.3/htdocs/manual/mod/mod_access.html
Index: mod_access.html
===================================================================
RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/mod/mod_access.html,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -d -b -u -r1.25 -r1.26
--- mod_access.html 2000/12/08 18:42:22 1.25
+++ mod_access.html 2000/12/16 21:36:08 1.26
@@ -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,42 @@
><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>. The
+<code>Allow</code> and <code>Deny</code> directives are used
+to specify which clients are or are not allowed access to the
+server, while the <code>Order</code> directive sets the
+default access state, and configures how the <code>Allow</code>
+and <code>Deny</code> directives interact with each other.</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>
+
+<p>In general, access restriction directives apply to all access
+methods (<code>GET</code>, <code>PUT</code>, <code>POST</code>, etc).
+This is the desired behavior in most cases. However, it is possible
+to restrict some methods, while leaving other methods unrestricted, by
+enclosing the directives in a <a
+href="core.html#limit"><Limit></a> section.</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 +81,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 +107,67 @@
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, subject to the configuration of the <code>Deny</code> and
+<code>Order</code> directives as discussed below. 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 the <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>. When
+<code>Allow from env=</code><em>variablename</em> is specified, then
+the request is allowed access if the environment variable
+<em>variablename</em> exists. 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 +178,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 a user-agent string beginning with
+<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="#deny">Deny</a>, <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 +214,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 hostname, IP address, or environment variables. The arguments for
+the <code>Deny</code> 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="#allow">Allow</a>, <A HREF="#order">Order</A>
+and <A HREF="mod_setenvif.html#SetEnvIf">SetEnvIf</A>.</p>
<HR>
<H2><A NAME="order">Order directive</A></H2>
@@ -306,42 +253,93 @@
><STRONG>Module:</STRONG></A> mod_access
</P>
<P>
-The <CODE>Order</CODE> directive controls the order in which
-<A HREF="#allow">Allow</A> and <A HREF="#deny">Deny</A> directives are
-evaluated. <EM>Ordering</EM> is one
-of
+The <CODE>Order</CODE> directive controls the default access state and
+the order in which <A HREF="#allow">Allow</A> and <A
+HREF="#deny">Deny</A> directives are evaluated. <EM>Ordering</EM> is
+one of
</P>
<DL>
-<DT>Deny,Allow
-<DD>the <CODE>Deny</CODE> directives are evaluated before the
<CODE>Allow</CODE>
-directives. (The initial state is OK.)
-<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>Deny,Allow</dt> <DD>The <CODE>Deny</CODE> directives are evaluated
+before the <CODE>Allow</CODE> directives. Access is allowed
+by default. Any client which does not match a <code>Deny</code>
+directive or does match an <code>Allow</code> directive will be
+allowed access to the server.</dd>
+
+<DT>Allow,Deny</dt> <DD>The <CODE>Allow</CODE> directives are
+evaluated before the <CODE>Deny</CODE> directives. Access is
+denied by default. Any client which does not match
+an <code>Allow</code> directive or does match a <code>Deny</code>
+directive will be denied access to the server.</dd>
+
+<DT>Mutual-failure</dt> <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. This ordering has the same effect as
+<code>Order Allow,Deny</code> and is deprecated in favor of that
+configuration.</dd>
</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>
-<P>
-Example:
+
+<P>Keywords may only be separated by a comma; no whitespace is allowed
+between them. Note that in all cases every <CODE>Allow</CODE>
+and <CODE>Deny</CODE> statement is evaluated.</P>
+
+<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 to deny access
+to the server.
</P>
+
+<blockquote><code>
+ Order Allow,Deny<br>
+ Allow from apache.org<br>
+ Deny from foo.apache.org<br>
+</code></blockquote>
+
+<p>On the other hand, if the <code>Order</code> in the last example is
+changed to <code>Deny,Allow</code>, all hosts will be allowed access.
+This happens because, regardless of the actual ordering of the
+directives in the configuration file, the <code>Allow from
+apache.org</code> will be evaluated last and will override the
+<code>Deny from foo.apache.org</code>. All hosts not in the
+<code>apache.org</code> domain will also be allowed access because the
+default state will change to <em>allow</em>.</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>deny</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" -->
