From: Joshua Slive Date: Sat, 16 Dec 2000 21:41:38 +0000 (+0000) Subject: Major rewrite of mod_access docs. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=30211f4dac73fe5a115142a87e8e4f202e75eaff;p=apache Major rewrite of mod_access docs. Submitted by: Joshua Slive, Cliff Woolley git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@87378 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_access.html b/docs/manual/mod/mod_access.html index 26d32410ea..c2a1294ced 100644 --- a/docs/manual/mod/mod_access.html +++ b/docs/manual/mod/mod_access.html @@ -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.

Directives

@@ -53,13 +81,15 @@ REL="Help"
-

Allow directive

+

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

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

-

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

Example:

@@ -152,21 +177,25 @@ SetEnvIf User-Agent ^KnockKnock/2.0 let_me_in 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

+

Deny directive

Syntax: Deny from host [host] ...
+>Syntax: Deny from + all|host|env=variablename + [host|env=variablename] ...
SetEnvIf. REL="Help" >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 -
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 -
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 -

-

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

+

See also Allow, Order +and SetEnvIf.

Order directive

@@ -298,43 +252,94 @@ HREF="mod_setenvif.html#SetEnvIf">SetEnvIf. >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.

+

See also: Deny and Allow.