2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
6 Copyright 2002-2004 The Apache Software Foundation
8 Licensed under the Apache License, Version 2.0 (the "License");
9 you may not use this file except in compliance with the License.
10 You may obtain a copy of the License at
12 http://www.apache.org/licenses/LICENSE-2.0
14 Unless required by applicable law or agreed to in writing, software
15 distributed under the License is distributed on an "AS IS" BASIS,
16 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 See the License for the specific language governing permissions and
18 limitations under the License.
21 <modulesynopsis metafile="mod_authz_host.xml.meta">
23 <name>mod_authz_host</name>
24 <description>Group authorizations based on host (name or IP
25 address)</description>
27 <sourcefile>mod_authz_host.c</sourcefile>
28 <identifier>authz_host_module</identifier>
29 <compatibility>Available in Apache 2.1 and later</compatibility>
32 <p>The directives provided by <module>mod_authz_host</module> are
33 used in <directive module="core" type="section">Directory</directive>,
34 <directive module="core" type="section">Files</directive>, and
35 <directive module="core" type="section">Location</directive> sections
36 as well as <code><a href="core.html#accessfilename">.htaccess</a>
37 </code> files to control access to particular parts of the server.
38 Access can be controlled based on the client hostname, IP address, or
39 other characteristics of the client request, as captured in <a
40 href="../env.html">environment variables</a>. The <directive
41 module="mod_authz_host">Allow</directive> and <directive
42 module="mod_authz_host">Deny</directive> directives are used to
43 specify which clients are or are not allowed access to the server,
44 while the <directive module="mod_authz_host">Order</directive>
45 directive sets the default access state, and configures how the
46 <directive module="mod_authz_host">Allow</directive> and <directive
47 module="mod_authz_host">Deny</directive> directives interact with each
50 <p>Both host-based access restrictions and password-based
51 authentication may be implemented simultaneously. In that case,
52 the <directive module="core">Satisfy</directive> directive is used
53 to determine how the two sets of restrictions interact.</p>
55 <p>In general, access restriction directives apply to all
56 access methods (<code>GET</code>, <code>PUT</code>,
57 <code>POST</code>, etc). This is the desired behavior in most
58 cases. However, it is possible to restrict some methods, while
59 leaving other methods unrestricted, by enclosing the directives
60 in a <directive module="core" type="section">Limit</directive> section.</p>
63 <seealso><directive module="core">Satisfy</directive></seealso>
64 <seealso><directive module="core">Require</directive></seealso>
68 <description>Controls which hosts can access an area of the
70 <syntax> Allow from all|<var>host</var>|env=<var>env-variable</var>
71 [<var>host</var>|env=<var>env-variable</var>] ...</syntax>
72 <contextlist><context>directory</context><context>.htaccess</context>
74 <override>Limit</override>
77 <p>The <directive>Allow</directive> directive affects which hosts can
78 access an area of the server. Access can be controlled by
79 hostname, IP Address, IP Address range, or by other
80 characteristics of the client request captured in environment
83 <p>The first argument to this directive is always
84 <code>from</code>. The subsequent arguments can take three
85 different forms. If <code>Allow from all</code> is specified, then
86 all hosts are allowed access, subject to the configuration of the
87 <directive module="mod_authz_host">Deny</directive> and <directive
88 module="mod_authz_host">Order</directive> directives as discussed
89 below. To allow only particular hosts or groups of hosts to access
90 the server, the <em>host</em> can be specified in any of the
91 following formats:</p>
94 <dt>A (partial) domain-name</dt>
97 <example><title>Example:</title>
100 <p>Hosts whose names match, or end in, this string are allowed
101 access. Only complete components are matched, so the above
102 example will match <code>foo.apache.org</code> but it will not
103 match <code>fooapache.org</code>. This configuration will cause
104 Apache to perform a double reverse DNS lookup on the client IP
105 address, regardless of the setting of the <directive
106 module="core">HostnameLookups</directive> directive. It will do
107 a reverse DNS lookup on the IP address to find the associated
108 hostname, and then do a forward lookup on the hostname to assure
109 that it matches the original IP address. Only if the forward
110 and reverse DNS are consistent and the hostname matches will
111 access be allowed.</p></dd>
113 <dt>A full IP address</dt>
116 <example><title>Example:</title>
119 <p>An IP address of a host allowed access</p></dd>
121 <dt>A partial IP address</dt>
124 <example><title>Example:</title>
127 <p>The first 1 to 3 bytes of an IP address, for subnet
128 restriction.</p></dd>
130 <dt>A network/netmask pair</dt>
133 <example><title>Example:</title>
134 Allow from 10.1.0.0/255.255.0.0
136 <p>A network a.b.c.d, and a netmask w.x.y.z. For more
137 fine-grained subnet restriction.</p></dd>
139 <dt>A network/nnn CIDR specification</dt>
142 <example><title>Example:</title>
143 Allow from 10.1.0.0/16
145 <p>Similar to the previous case, except the netmask consists of
146 nnn high-order 1 bits.</p></dd>
149 <p>Note that the last three examples above match exactly the
150 same set of hosts.</p>
152 <p>IPv6 addresses and IPv6 subnets can be specified as shown
156 Allow from fe80::a00:20ff:fea7:ccea<br />
157 Allow from fe80::a00:20ff:fea7:ccea/10
160 <p>The third format of the arguments to the
161 <directive>Allow</directive> directive allows access to the server
162 to be controlled based on the existence of an <a
163 href="../env.html">environment variable</a>. When <code>Allow from
164 env=<var>env-variable</var></code> is specified, then the request is
165 allowed access if the environment variable <var>env-variable</var>
166 exists. The server provides the ability to set environment
167 variables in a flexible way based on characteristics of the client
168 request using the directives provided by
169 <module>mod_setenvif</module>. Therefore, this directive can be
170 used to allow access based on such factors as the clients
171 <code>User-Agent</code> (browser type), <code>Referer</code>, or
172 other HTTP request header fields.</p>
174 <example><title>Example:</title>
175 SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in<br />
176 <Directory /docroot><br />
178 Order Deny,Allow<br />
180 Allow from env=let_me_in<br />
185 <p>In this case, browsers with a user-agent string beginning
186 with <code>KnockKnock/2.0</code> will be allowed access, and all
187 others will be denied.</p>
193 <description>Controls which hosts are denied access to the
195 <syntax> Deny from all|<var>host</var>|env=<var>env-variable</var>
196 [<var>host</var>|env=<var>env-variable</var>] ...</syntax>
197 <contextlist><context>directory</context><context>.htaccess</context>
199 <override>Limit</override>
202 <p>This directive allows access to the server to be restricted
203 based on hostname, IP address, or environment variables. The
204 arguments for the <directive>Deny</directive> directive are
205 identical to the arguments for the <directive
206 module="mod_authz_host">Allow</directive> directive.</p>
212 <description>Controls the default access state and the order in which
213 <directive>Allow</directive> and <directive>Deny</directive> are
214 evaluated.</description>
215 <syntax> Order <var>ordering</var></syntax>
216 <default>Order Deny,Allow</default>
217 <contextlist><context>directory</context><context>.htaccess</context>
219 <override>Limit</override>
222 <p>The <directive>Order</directive> directive controls the default
223 access state and the order in which <directive
224 module="mod_authz_host">Allow</directive> and <directive
225 module="mod_authz_host">Deny</directive> directives are evaluated.
226 <var>Ordering</var> is one of</p>
229 <dt><code>Deny,Allow</code></dt>
231 <dd>The <directive module="mod_authz_host">Deny</directive> directives
232 are evaluated before the <directive
233 module="mod_authz_host">Allow</directive> directives. Access is
234 allowed by default. Any client which does not match a
235 <directive module="mod_authz_host">Deny</directive> directive or does
236 match an <directive module="mod_authz_host">Allow</directive>
237 directive will be allowed access to the server.</dd>
239 <dt><code>Allow,Deny</code></dt>
241 <dd>The <directive module="mod_authz_host">Allow</directive>
242 directives are evaluated before the <directive
243 module="mod_authz_host">Deny</directive> directives. Access is denied
244 by default. Any client which does not match an <directive
245 module="mod_authz_host">Allow</directive> directive or does match a
246 <directive module="mod_authz_host">Deny</directive> directive will be
247 denied access to the server.</dd>
249 <dt><code>Mutual-failure</code></dt>
251 <dd>Only those hosts which appear on the <directive
252 module="mod_authz_host">Allow</directive> list and do not appear on
253 the <directive module="mod_authz_host">Deny</directive> list are
254 granted access. This ordering has the same effect as <code>Order
255 Allow,Deny</code> and is deprecated in favor of that
259 <p>Keywords may only be separated by a comma; <em>no whitespace</em> is
260 allowed between them. Note that in all cases every <directive
261 module="mod_authz_host">Allow</directive> and <directive
262 module="mod_authz_host">Deny</directive> statement is evaluated.</p>
264 <p>In the following example, all hosts in the apache.org domain
265 are allowed access; all other hosts are denied access.</p>
268 Order Deny,Allow<br />
270 Allow from apache.org
273 <p>In the next example, all hosts in the apache.org domain are
274 allowed access, except for the hosts which are in the
275 foo.apache.org subdomain, who are denied access. All hosts not
276 in the apache.org domain are denied access because the default
277 state is to deny access to the server.</p>
280 Order Allow,Deny<br />
281 Allow from apache.org<br />
282 Deny from foo.apache.org
285 <p>On the other hand, if the <directive>Order</directive> in the last
286 example is changed to <code>Deny,Allow</code>, all hosts will
287 be allowed access. This happens because, regardless of the
288 actual ordering of the directives in the configuration file,
289 the <code>Allow from apache.org</code> will be evaluated last
290 and will override the <code>Deny from foo.apache.org</code>.
291 All hosts not in the <code>apache.org</code> domain will also
292 be allowed access because the default state will change to
295 <p>The presence of an <directive>Order</directive> directive can affect
296 access to a part of the server even in the absence of accompanying
297 <directive module="mod_authz_host">Allow</directive> and <directive
298 module="mod_authz_host">Deny</directive> directives because of its effect
299 on the default access state. For example,</p>
302 <Directory /www><br />
304 Order Allow,Deny<br />
309 <p>will deny all access to the <code>/www</code> directory
310 because the default access state will be set to
313 <p>The <directive>Order</directive> directive controls the order of access
314 directive processing only within each phase of the server's
315 configuration processing. This implies, for example, that an
316 <directive module="mod_authz_host">Allow</directive> or <directive
317 module="mod_authz_host">Deny</directive> directive occurring in a
318 <directive module="core" type="section">Location</directive> section will
319 always be evaluated after an <directive
320 module="mod_authz_host">Allow</directive> or <directive
321 module="mod_authz_host">Deny</directive> directive occurring in a
322 <directive module="core" type="section">Directory</directive> section or
323 <code>.htaccess</code> file, regardless of the setting of the
324 <directive>Order</directive> directive. For details on the merging
325 of configuration sections, see the documentation on <a
326 href="../sections.html">How Directory, Location and Files sections