Return-Path: Mailing-List: contact apache-docs-help@apache.org; run by ezmlm Delivered-To: mailing list apache-docs@apache.org Received: (qmail 83584 invoked by uid 500); 16 Dec 2000 21:36:08 -0000 Delivered-To: apmail-httpd-docs-1.3-cvs@apache.org Received: (qmail 83581 invoked by uid 1173); 16 Dec 2000 21:36:08 -0000 Date: 16 Dec 2000 21:36:08 -0000 Message-ID: <20001216213608.83580.qmail@locus.apache.org> From: slive@locus.apache.org To: httpd-docs-1.3-cvs@apache.org Subject: cvs commit: httpd-docs-1.3/htdocs/manual/mod mod_access.html 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 @@

Module mod_access

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

Module Identifier: access_module

Summary

+ +

The directives provided by mod_access are used in <Directory>, <Files>, and <Location> sections as +well as .htaccess 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 environment variables. The +Allow and Deny directives are used +to specify which clients are or are not allowed access to the +server, while the Order directive sets the +default access state, and configures how the Allow +and Deny directives interact with each other.

+ +

Both host-based access restrictions and password-based +authentication may be implemented simultaneously. In +that case, the Satisfy directive +is used to determine how the two sets of restrictions +interact.

+ +

In general, access restriction directives apply to all access +methods (GET, PUT, POST, 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 <Limit> section.

@@ -53,13 +81,15 @@

Allow directive

Syntax: Allow from host [host] ...
+>Syntax: Allow from + all|host|env=variablename + [host|env=variablename] ...
Module: mod_access

-The Allow directive affects which hosts can access a given directory. -Host is one of the following: -

+The Allow 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.

+ +

The first argument to this directive is always from. +The subsequent arguments can take three different forms. If +Allow from all is specified, then all hosts are allowed +access, subject to the configuration of the Deny and +Order directives as discussed below. To allow only +particular hosts or groups of hosts to access the server, the +host can be specified in any of the following formats:

all -: All hosts are allowed access -
A (partial) domain-name -: Hosts whose names match, or end in, this string are allowed access. -
A full IP address -: An IP address of a host allowed access -
A partial IP address -: The first 1 to 3 bytes of an IP address, for subnet restriction. -
A network/netmask pair (Apache 1.3 and later) -: A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet - restriction. (i.e., 10.1.0.0/255.255.0.0) -
A network/nnn CIDR specification (Apache 1.3 and later) -: Similar to the previous case, except the netmask consists of nnn - high-order 1 bits. (i.e., 10.1.0.0/16 is the same as 10.1.0.0/255.255.0.0) + +
A (partial) domain-name: Example: Allow from +apache.org
Hosts whose names match, or end in, this string +are allowed access. Only complete components are matched, so the +above example will match foo.apache.org but it will not +match fooapache.org. This configuration will cause the +server to perform a reverse DNS lookup on the client IP address, +regardless of the setting of the HostNameLookups directive.
A full IP address: Example: Allow from 10.1.2.3
+An IP address of a host allowed access
A partial IP address: Example: Allow from 10.1
+The first 1 to 3 bytes of an IP address, for subnet restriction.
A network/netmask pair: Example: Allow from 10.1.0.0/255.255.0.0
+ A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet + restriction. (Apache 1.3 and later)
A network/nnn CIDR specification: Example: Allow +from 10.1.0.0/16
Similar to the previous case, except the +netmask consists of nnn high-order 1 bits. (Apache 1.3 and +later)

-Example: -

Allow from .ncsa.uiuc.edu

-All hosts in the specified domain are allowed access. -

-Note that this compares whole components; bar.edu -would not match foobar.edu. -

-See also Allow from env=, Deny and Order. -

Note that the last three examples above match exactly the +same set of hosts.

Allow from env= directive

The third format of the arguments to the Allow +directive allows access to the server to be controlled based on the +existence of an environment variable. When +Allow from env=variablename is specified, then +the request is allowed access if the environment variable +variablename 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 mod_setenvif. Therefore, this directive +can be used to allow access based on such factors as the clients +User-Agent (browser type), Referer, or other +HTTP request header fields.

-Syntax: Allow from - env=variablename
-Context: directory, .htaccess
-Override: Limit
-Status: Base
-Module: mod_access
-Compatibility: Apache 1.2 and above -

-The Allow from env directive controls access to a directory by the -existence (or non-existence) of an environment variable. -

Example:

  @@ -156,21 +178,25 @@
       Allow from env=let_me_in
   </Directory>

-In this case browsers with the user-agent string KnockKnock/2.0 will -be allowed access, and all others will be denied. + +

In this case, browsers with a user-agent string beginning with +KnockKnock/2.0 will be allowed access, and all others will be +denied.

-See also Deny from env=, Order +See also Deny, Order and SetEnvIf.

Deny directive

Syntax: Deny from host [host] ...
+>Syntax: Deny from + all|host|env=variablename + [host|env=variablename] ...
Module: mod_access

-The Deny directive affects which hosts can access a given directory. -Host is one of the following: -

all -: all hosts are denied access -
A (partial) domain-name -: host whose name is, or ends in, this string are denied access. -
A full IP address -: An IP address of a host denied access -
A partial IP address -: The first 1 to 3 bytes of an IP address, for subnet restriction. -
A network/netmask pair (Apache 1.3 and later) -: A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet - restriction. (i.e., 10.1.0.0/255.255.0.0) -
A network/nnn CIDR specification (Apache 1.3 and later) -: Similar to the previous case, except the netmask consists of nnn - high-order 1 bits. (i.e., 10.1.0.0/16 is the same as 10.1.0.0/255.255.0.0) -

-Example: -

Deny from 16

-All hosts in the specified network are denied access. -

-Note that this compares whole components; bar.edu -would not match foobar.edu. -

-See also Deny from env=, Allow and Order. -

- -

Deny from env= directive

- -

-Syntax: Deny from - env=variablename
-Context: directory, .htaccess
-Override: Limit
-Status: Base
-Module: mod_access
-Compatibility: Apache 1.2 and above -

-The Deny from env directive controls access to a directory by the -existence (or non-existence) of an environment variable. -

-Example: -

  -SetEnvIf User-Agent ^BadRobot/0.9 go_away
  -<Directory /docroot>
  -    Order Allow,Deny
  -    Allow from all
  -    Deny from env=go_away
  -</Directory>
  -

-In this case browsers with the user-agent string BadRobot/0.9 will -be denied access, and all others will be allowed. +

This directive allows access to the server to be restricted based +on hostname, IP address, or environment variables. The arguments for +the Deny directive are identical to the arguments for the +Allow directive.

-See also Allow from env=, Order and SetEnvIf. -

Order directive

@@ -306,42 +253,93 @@ >Module: mod_access

-The Order directive controls the order in which -Allow and Deny directives are -evaluated. Ordering is one -of +The Order directive controls the default access state and +the order in which Allow and Deny directives are evaluated. Ordering is +one of

Deny,Allow -: the Deny directives are evaluated before the Allow -directives. (The initial state is OK.) -
Allow,Deny -: the Allow directives are evaluated before the Deny -directives. (The initial state is FORBIDDEN.) -
Mutual-failure -: Only those hosts which appear on the Allow list and do not -appear on the Deny list are granted access. (The initial state is -irrelevant.) This ordering has the same effect as Order Allow,Deny -and is deprecated in favor of that configuration. +
Deny,Allow: The Deny directives are evaluated +before the Allow directives. Access is allowed +by default. Any client which does not match a Deny +directive or does match an Allow directive will be +allowed access to the server.
Allow,Deny: The Allow directives are +evaluated before the Deny directives. Access is +denied by default. Any client which does not match +an Allow directive or does match a Deny +directive will be denied access to the server.
Mutual-failure: Only those hosts which appear on the +Allow list and do not appear on the Deny +list are granted access. This ordering has the same effect as +Order Allow,Deny and is deprecated in favor of that +configuration.

-Keywords may only be separated by a comma; no whitespace is allowed between -them. -Note that in all cases every Allow and Deny -statement is evaluated, there is no "short-circuiting". -

-Example: + +

Keywords may only be separated by a comma; no whitespace is allowed +between them. Note that in all cases every Allow +and Deny statement is evaluated.

+ +

In the following example, all hosts in the apache.org domain are +allowed access; all other hosts are denied access.

Order Deny,Allow Deny from all - Allow from .ncsa.uiuc.edu + Allow from apache.org

-Hosts in the ncsa.uiuc.edu domain are allowed access; all other hosts are -denied access. + +

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.

+ +

+ Order Allow,Deny + Allow from apache.org + Deny from foo.apache.org +

+ +

On the other hand, if the Order in the last example is +changed to Deny,Allow, all hosts will be allowed access. +This happens because, regardless of the actual ordering of the +directives in the configuration file, the Allow from +apache.org will be evaluated last and will override the +Deny from foo.apache.org. All hosts not in the +apache.org domain will also be allowed access because the +default state will change to allow.

+ +

The presence of an Order directive can +affect access to a part of the server even in the absence +of accompanying Allow and Deny +directives because of its effect on the default access state. +For example,

+ +

+<Directory /www> + Order Allow,Deny +</Directory> +

+ +

will deny all access to the /www directory because +the default access state will be set to deny.

+ +

The Order directive controls the order of access +directive processing only within each phase of the server's +configuration processing. This implies, for example, that an +Allow or Deny directive occurring +in a <Location> section will always be evaluated after +an Allow or Deny directive occurring +in a <Directory> section or .htaccess file, +regardless of the setting of the Order directive. +For details on the merging of configuration sections, +see the documentation on How Directory, +Location and Files sections work.