Major rewrite of mod_access docs.

<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

><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">&lt;Directory&gt;</A>, <A

HREF="core.html#files">&lt;Files&gt;</A>,</code> and <code> <A

HREF="core.html#location">&lt;Location&gt;</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">&lt;Limit&gt;</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>

<HR>

<H2><A NAME="allow">Allow directive</A></H2>

<H2><A NAME="allow">Allow</a> <a name="allowfromenv">directive</A></H2>

<P>

<!--%plaintext &lt;?INDEX {\tt Allow} directive&gt; -->

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

 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

<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

<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.</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.</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

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

    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 &lt;?INDEX {\tt Deny} directive&gt; -->

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

 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

<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

<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="denfromenv">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

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

><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 &quot;short-circuiting&quot;.</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>

&lt;Directory /www&gt;<br>

&nbsp;&nbsp;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 &lt;Directory&gt; 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" -->

</BODY>