2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_access_compat.xml.meta">
25 <name>mod_access_compat</name>
26 <description>Group authorizations based on host (name or IP
27 address)</description>
28 <status>Extension</status>
29 <sourcefile>mod_access_compat.c</sourcefile>
30 <identifier>access_compat_module</identifier>
31 <compatibility>Available in Apache HTTP Server 2.3 as a compatibility module with
32 previous versions of Apache httpd 2.x. The directives provided by this module
33 have been deprecated by the new authz refactoring. Please see
34 <module>mod_authz_host</module></compatibility>
37 <p>The directives provided by <module>mod_access_compat</module> are
38 used in <directive module="core" type="section">Directory</directive>,
39 <directive module="core" type="section">Files</directive>, and
40 <directive module="core" type="section">Location</directive> sections
41 as well as <code><a href="core.html#accessfilename">.htaccess</a>
42 </code> files to control access to particular parts of the server.
43 Access can be controlled based on the client hostname, IP address, or
44 other characteristics of the client request, as captured in <a
45 href="../env.html">environment variables</a>. The <directive
46 module="mod_access_compat">Allow</directive> and <directive
47 module="mod_access_compat">Deny</directive> directives are used to
48 specify which clients are or are not allowed access to the server,
49 while the <directive module="mod_access_compat">Order</directive>
50 directive sets the default access state, and configures how the
51 <directive module="mod_access_compat">Allow</directive> and <directive
52 module="mod_access_compat">Deny</directive> directives interact with each
55 <p>Both host-based access restrictions and password-based
56 authentication may be implemented simultaneously. In that case,
57 the <directive module="mod_access_compat">Satisfy</directive> directive is used
58 to determine how the two sets of restrictions interact.</p>
60 <note type="warning"><title>Note</title>
61 <p>The directives provided by <module>mod_access_compat</module> have
62 been deprecated by the new authz refactoring. Please see
63 <module>mod_authz_host</module>.</p>
66 <p>In general, access restriction directives apply to all
67 access methods (<code>GET</code>, <code>PUT</code>,
68 <code>POST</code>, etc). This is the desired behavior in most
69 cases. However, it is possible to restrict some methods, while
70 leaving other methods unrestricted, by enclosing the directives
71 in a <directive module="core" type="section">Limit</directive> section.</p>
74 <seealso><directive module="mod_authz_core">Require</directive></seealso>
75 <seealso><module>mod_authz_host</module></seealso>
76 <seealso><module>mod_authz_core</module></seealso>
80 <description>Controls which hosts can access an area of the
82 <syntax> Allow from all|<var>host</var>|env=[!]<var>env-variable</var>
83 [<var>host</var>|env=[!]<var>env-variable</var>] ...</syntax>
84 <contextlist><context>directory</context><context>.htaccess</context>
86 <override>Limit</override>
89 <p>The <directive>Allow</directive> directive affects which hosts can
90 access an area of the server. Access can be controlled by
91 hostname, IP address, IP address range, or by other
92 characteristics of the client request captured in environment
95 <p>The first argument to this directive is always
96 <code>from</code>. The subsequent arguments can take three
97 different forms. If <code>Allow from all</code> is specified, then
98 all hosts are allowed access, subject to the configuration of the
99 <directive module="mod_access_compat">Deny</directive> and <directive
100 module="mod_access_compat">Order</directive> directives as discussed
101 below. To allow only particular hosts or groups of hosts to access
102 the server, the <em>host</em> can be specified in any of the
103 following formats:</p>
106 <dt>A (partial) domain-name</dt>
109 <example><title>Example:</title>
110 Allow from example.org<br />
111 Allow from .net example.edu
113 <p>Hosts whose names match, or end in, this string are allowed
114 access. Only complete components are matched, so the above
115 example will match <code>foo.example.org</code> but it will not
116 match <code>fooexample.org</code>. This configuration will cause
117 Apache httpd to perform a double DNS lookup on the client IP
118 address, regardless of the setting of the <directive
119 module="core">HostnameLookups</directive> directive. It will do
120 a reverse DNS lookup on the IP address to find the associated
121 hostname, and then do a forward lookup on the hostname to assure
122 that it matches the original IP address. Only if the forward
123 and reverse DNS are consistent and the hostname matches will
124 access be allowed.</p></dd>
126 <dt>A full IP address</dt>
129 <example><title>Example:</title>
130 Allow from 10.1.2.3<br />
131 Allow from 192.168.1.104 192.168.1.205
133 <p>An IP address of a host allowed access</p></dd>
135 <dt>A partial IP address</dt>
138 <example><title>Example:</title>
139 Allow from 10.1<br />
140 Allow from 10 172.20 192.168.2
142 <p>The first 1 to 3 bytes of an IP address, for subnet
143 restriction.</p></dd>
145 <dt>A network/netmask pair</dt>
148 <example><title>Example:</title>
149 Allow from 10.1.0.0/255.255.0.0
151 <p>A network a.b.c.d, and a netmask w.x.y.z. For more
152 fine-grained subnet restriction.</p></dd>
154 <dt>A network/nnn CIDR specification</dt>
157 <example><title>Example:</title>
158 Allow from 10.1.0.0/16
160 <p>Similar to the previous case, except the netmask consists of
161 nnn high-order 1 bits.</p></dd>
164 <p>Note that the last three examples above match exactly the
165 same set of hosts.</p>
167 <p>IPv6 addresses and IPv6 subnets can be specified as shown
171 Allow from 2001:db8::a00:20ff:fea7:ccea<br />
172 Allow from 2001:db8::a00:20ff:fea7:ccea/10
175 <p>The third format of the arguments to the
176 <directive>Allow</directive> directive allows access to the server
177 to be controlled based on the existence of an <a
178 href="../env.html">environment variable</a>. When <code>Allow from
179 env=<var>env-variable</var></code> is specified, then the request is
180 allowed access if the environment variable <var>env-variable</var>
181 exists. When <code>Allow from env=!<var>env-variable</var></code> is
182 specified, then the request is allowed access if the environment
183 variable <var>env-variable</var> doesn't exist.
184 The server provides the ability to set environment
185 variables in a flexible way based on characteristics of the client
186 request using the directives provided by
187 <module>mod_setenvif</module>. Therefore, this directive can be
188 used to allow access based on such factors as the clients
189 <code>User-Agent</code> (browser type), <code>Referer</code>, or
190 other HTTP request header fields.</p>
192 <example><title>Example:</title>
193 SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in<br />
194 <Directory /docroot><br />
196 Order Deny,Allow<br />
198 Allow from env=let_me_in<br />
203 <p>In this case, browsers with a user-agent string beginning
204 with <code>KnockKnock/2.0</code> will be allowed access, and all
205 others will be denied.</p>
211 <description>Controls which hosts are denied access to the
213 <syntax> Deny from all|<var>host</var>|env=[!]<var>env-variable</var>
214 [<var>host</var>|env=[!]<var>env-variable</var>] ...</syntax>
215 <contextlist><context>directory</context><context>.htaccess</context>
217 <override>Limit</override>
220 <p>This directive allows access to the server to be restricted
221 based on hostname, IP address, or environment variables. The
222 arguments for the <directive>Deny</directive> directive are
223 identical to the arguments for the <directive
224 module="mod_access_compat">Allow</directive> directive.</p>
230 <description>Controls the default access state and the order in which
231 <directive>Allow</directive> and <directive>Deny</directive> are
232 evaluated.</description>
233 <syntax> Order <var>ordering</var></syntax>
234 <default>Order Deny,Allow</default>
235 <contextlist><context>directory</context><context>.htaccess</context>
237 <override>Limit</override>
241 <p>The <directive>Order</directive> directive, along with the
242 <directive module="mod_access_compat">Allow</directive> and
243 <directive module="mod_access_compat">Deny</directive> directives,
244 controls a three-pass access control system. The first pass
245 processes either all <directive
246 module="mod_access_compat">Allow</directive> or all <directive
247 module="mod_access_compat">Deny</directive> directives, as specified
248 by the <directive module="mod_access_compat">Order</directive>
249 directive. The second pass parses the rest of the directives
250 (<directive module="mod_access_compat">Deny</directive> or
251 <directive module="mod_access_compat">Allow</directive>). The third
252 pass applies to all requests which do not match either of the first
255 <p>Note that all <directive
256 module="mod_access_compat">Allow</directive> and <directive
257 module="mod_access_compat">Deny</directive> directives are
258 processed, unlike a typical firewall, where only the first match is
259 used. The last match is effective (also unlike a typical firewall).
260 Additionally, the order in which lines appear in the configuration
261 files is not significant -- all <directive
262 module="mod_access_compat">Allow</directive> lines are processed as
263 one group, all <directive
264 module="mod_access_compat">Deny</directive> lines are considered as
265 another, and the default state is considered by itself.</p>
267 <p><em>Ordering</em> is one of:</p>
270 <dt><code>Allow,Deny</code></dt>
272 <dd>First, all <directive
273 module="mod_access_compat">Allow</directive> directives are
274 evaluated; at least one must match, or the request is rejected.
275 Next, all <directive module="mod_access_compat">Deny</directive>
276 directives are evaluated. If any matches, the request is rejected.
277 Last, any requests which do not match an <directive
278 module="mod_access_compat">Allow</directive> or a <directive
279 module="mod_access_compat">Deny</directive> directive are denied
282 <dt><code>Deny,Allow</code></dt>
284 <dd>First, all <directive
285 module="mod_access_compat">Deny</directive> directives are
286 evaluated; if any match, the request is denied
287 <strong>unless</strong> it also matches an <directive
288 module="mod_access_compat">Allow</directive> directive. Any
289 requests which do not match any <directive
290 module="mod_access_compat">Allow</directive> or <directive
291 module="mod_access_compat">Deny</directive> directives are
294 <dt><code>Mutual-failure</code></dt>
296 <dd>This order has the same effect as <code>Order
297 Allow,Deny</code> and is deprecated in its favor.</dd>
300 <p>Keywords may only be separated by a comma; <em>no whitespace</em>
301 is allowed between them.</p>
306 <th>Allow,Deny result</th>
307 <th>Deny,Allow result</th>
309 <th>Match Allow only</th>
310 <td>Request allowed</td>
311 <td>Request allowed</td>
313 <th>Match Deny only</th>
314 <td>Request denied</td>
315 <td>Request denied</td>
318 <td>Default to second directive: Denied</td>
319 <td>Default to second directive: Allowed</td>
321 <th>Match both Allow & Deny</th>
322 <td>Final match controls: Denied</td>
323 <td>Final match controls: Allowed</td>
327 <p>In the following example, all hosts in the example.org domain
328 are allowed access; all other hosts are denied access.</p>
331 Order Deny,Allow<br />
333 Allow from example.org
336 <p>In the next example, all hosts in the example.org domain are
337 allowed access, except for the hosts which are in the
338 foo.example.org subdomain, who are denied access. All hosts not
339 in the example.org domain are denied access because the default
340 state is to <directive module="mod_access_compat">Deny</directive>
341 access to the server.</p>
344 Order Allow,Deny<br />
345 Allow from example.org<br />
346 Deny from foo.example.org
349 <p>On the other hand, if the <directive>Order</directive> in the
350 last example is changed to <code>Deny,Allow</code>, all hosts will
351 be allowed access. This happens because, regardless of the actual
352 ordering of the directives in the configuration file, the
353 <code>Allow from example.org</code> will be evaluated last and will
354 override the <code>Deny from foo.example.org</code>. All hosts not in
355 the <code>example.org</code> domain will also be allowed access
356 because the default state is <directive
357 module="mod_access_compat">Allow</directive>.</p>
359 <p>The presence of an <directive>Order</directive> directive can
360 affect access to a part of the server even in the absence of
361 accompanying <directive module="mod_access_compat">Allow</directive>
362 and <directive module="mod_access_compat">Deny</directive>
363 directives because of its effect on the default access state. For
367 <Directory /www><br />
369 Order Allow,Deny<br />
374 <p>will Deny all access to the <code>/www</code> directory
375 because the default access state is set to
376 <directive module="mod_access_compat">Deny</directive>.</p>
378 <p>The <directive>Order</directive> directive controls the order of access
379 directive processing only within each phase of the server's
380 configuration processing. This implies, for example, that an
381 <directive module="mod_access_compat">Allow</directive> or <directive
382 module="mod_access_compat">Deny</directive> directive occurring in a
383 <directive module="core" type="section">Location</directive> section will
384 always be evaluated after an <directive
385 module="mod_access_compat">Allow</directive> or <directive
386 module="mod_access_compat">Deny</directive> directive occurring in a
387 <directive module="core" type="section">Directory</directive> section or
388 <code>.htaccess</code> file, regardless of the setting of the
389 <directive>Order</directive> directive. For details on the merging
390 of configuration sections, see the documentation on <a
391 href="../sections.html">How Directory, Location and Files sections
398 <description>Interaction between host-level access control and
399 user authentication</description>
400 <syntax>Satisfy Any|All</syntax>
401 <default>Satisfy All</default>
402 <contextlist><context>directory</context><context>.htaccess</context>
404 <override>AuthConfig</override>
405 <compatibility>Influenced by <directive module="core" type="section"
406 >Limit</directive> and <directive module="core"
407 type="section">LimitExcept</directive> in version 2.0.51 and
408 later</compatibility>
411 <p>Access policy if both <directive
412 module="mod_access_compat">Allow</directive> and <directive
413 module="mod_authz_core">Require</directive> used. The parameter can be
414 either <code>All</code> or <code>Any</code>. This directive is only
415 useful if access to a particular area is being restricted by both
416 username/password <em>and</em> client host address. In this case
417 the default behavior (<code>All</code>) is to require that the client
418 passes the address access restriction <em>and</em> enters a valid
419 username and password. With the <code>Any</code> option the client will be
420 granted access if they either pass the host restriction or enter a
421 valid username and password. This can be used to password restrict
422 an area, but to let clients from particular addresses in without
423 prompting for a password.</p>
425 <p>For example, if you wanted to let people on your network have
426 unrestricted access to a portion of your website, but require that
427 people outside of your network provide a password, you could use a
428 configuration similar to the following:</p>
431 Require valid-user<br />
432 Allow from 192.168.1<br />
437 Another frequent use of the <directive>Satisfy</directive> directive
438 is to relax access restrictions for a subdirectory:
442 <Directory /var/www/private><br />
443 Require valid-user<br />
444 </Directory><br />
446 <Directory /var/www/private/public><br />
452 <p>In the above example, authentication will be required for the
453 <code>/var/www/private</code> directory, but will not be required
454 for the <code>/var/www/private/public</code> directory.</p>
456 <p>Since version 2.0.51 <directive>Satisfy</directive> directives can
457 be restricted to particular methods by <directive module="core"
458 type="section">Limit</directive> and <directive module="core" type="section"
459 >LimitExcept</directive> sections.</p>
461 <seealso><directive module="mod_access_compat">Allow</directive></seealso>
462 <seealso><directive module="mod_authz_core">Require</directive></seealso>