granicus.if.org Git - apache/blob - docs/manual/mod/mod_access_compat.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_access_compat - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body>
  14 <div id="page-header">
  15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  16 <p class="apache">Apache HTTP Server Version 2.3</p>
  17 <img alt="" src="../images/feather.gif" /></div>
  18 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.3</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Module mod_access_compat</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/mod_access_compat.html" title="English">&nbsp;en&nbsp;</a></p>
  25 </div>
  26 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Group authorizations based on host (name or IP
  27 address)</td></tr>
  28 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  29 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>access_compat_module</td></tr>
  30 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_access_compat.c</td></tr>
  31 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3 as a compatibility module with
  32 previous versions of Apache 2.x.  The directives provided by this module
  33 have been deprecated by the new authz refactoring.  Please see
  34 <code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code></td></tr></table>
  35 <h3>Summary</h3>
  36
  37     <p>The directives provided by <code class="module"><a href="../mod/mod_access_compat.html">mod_access_compat</a></code> are
  38     used in <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code>,
  39     <code class="directive"><a href="../mod/core.html#files">&lt;Files&gt;</a></code>, and
  40     <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> 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 href="../env.html">environment variables</a>. The <code class="directive"><a href="#allow">Allow</a></code> and <code class="directive"><a href="#deny">Deny</a></code> directives are used to
  45     specify which clients are or are not allowed access to the server,
  46     while the <code class="directive"><a href="#order">Order</a></code>
  47     directive sets the default access state, and configures how the
  48     <code class="directive"><a href="#allow">Allow</a></code> and <code class="directive"><a href="#deny">Deny</a></code> directives interact with each
  49     other.</p>
  50
  51     <p>Both host-based access restrictions and password-based
  52     authentication may be implemented simultaneously. In that case,
  53     the <code class="directive"><a href="../mod/core.html#satisfy">Satisfy</a></code> directive is used
  54     to determine how the two sets of restrictions interact.</p>
  55
  56     <div class="warning"><h3>Note</h3>
  57       <p>The directives provided by <code class="module"><a href="../mod/mod_access_compat.html">mod_access_compat</a></code> have
  58       been deprecated by the new authz refactoring. Please see
  59       <code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code>.  The module
  60       <code class="module"><a href="../mod/mod_authz_default.html">mod_authz_default</a></code> must also be loaded to provide for
  61       default authorization handling.</p>
  62     </div>
  63
  64     <p>In general, access restriction directives apply to all
  65     access methods (<code>GET</code>, <code>PUT</code>,
  66     <code>POST</code>, etc). This is the desired behavior in most
  67     cases. However, it is possible to restrict some methods, while
  68     leaving other methods unrestricted, by enclosing the directives
  69     in a <code class="directive"><a href="../mod/core.html#limit">&lt;Limit&gt;</a></code> section.</p>
  70 </div>
  71 <div id="quickview"><h3 class="directives">Directives</h3>
  72 <ul id="toc">
  73 <li><img alt="" src="../images/down.gif" /> <a href="#allow">Allow</a></li>
  74 <li><img alt="" src="../images/down.gif" /> <a href="#deny">Deny</a></li>
  75 <li><img alt="" src="../images/down.gif" /> <a href="#order">Order</a></li>
  76 <li><img alt="" src="../images/down.gif" /> <a href="#satisfy">Satisfy</a></li>
  77 </ul>
  78 <h3>See also</h3>
  79 <ul class="seealso">
  80 <li><code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code></li>
  81 <li><code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code></li>
  82 <li><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code></li>
  83 </ul></div>
  84
  85 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  86 <div class="directive-section"><h2><a name="Allow" id="Allow">Allow</a> <a name="allow" id="allow">Directive</a></h2>
  87 <table class="directive">
  88 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls which hosts can access an area of the
  89 server</td></tr>
  90 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> Allow from all|<var>host</var>|env=<var>env-variable</var>
  91 [<var>host</var>|env=<var>env-variable</var>] ...</code></td></tr>
  92 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
  93 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Limit</td></tr>
  94 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  95 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_access_compat</td></tr>
  96 </table>
  97     <p>The <code class="directive">Allow</code> directive affects which hosts can
  98     access an area of the server. Access can be controlled by
  99     hostname, IP Address, IP Address range, or by other
 100     characteristics of the client request captured in environment
 101     variables.</p>
 102
 103     <p>The first argument to this directive is always
 104     <code>from</code>. The subsequent arguments can take three
 105     different forms. If <code>Allow from all</code> is specified, then
 106     all hosts are allowed access, subject to the configuration of the
 107     <code class="directive"><a href="#deny">Deny</a></code> and <code class="directive"><a href="#order">Order</a></code> directives as discussed
 108     below. To allow only particular hosts or groups of hosts to access
 109     the server, the <em>host</em> can be specified in any of the
 110     following formats:</p>
 111
 112     <dl>
 113       <dt>A (partial) domain-name</dt>
 114
 115       <dd>
 116       <div class="example"><h3>Example:</h3><p><code>
 117         Allow from apache.org<br />
 118         Allow from .net example.edu
 119       </code></p></div>
 120       <p>Hosts whose names match, or end in, this string are allowed
 121       access. Only complete components are matched, so the above
 122       example will match <code>foo.apache.org</code> but it will not
 123       match <code>fooapache.org</code>. This configuration will cause
 124       Apache to perform a double reverse DNS lookup on the client IP
 125       address, regardless of the setting of the <code class="directive"><a href="../mod/core.html#hostnamelookups">HostnameLookups</a></code> directive.  It will do
 126       a reverse DNS lookup on the IP address to find the associated
 127       hostname, and then do a forward lookup on the hostname to assure
 128       that it matches the original IP address.  Only if the forward
 129       and reverse DNS are consistent and the hostname matches will
 130       access be allowed.</p></dd>
 131
 132       <dt>A full IP address</dt>
 133
 134       <dd>
 135       <div class="example"><h3>Example:</h3><p><code>
 136         Allow from 10.1.2.3<br />
 137         Allow from 192.168.1.104 192.168.1.205
 138       </code></p></div>
 139       <p>An IP address of a host allowed access</p></dd>
 140
 141       <dt>A partial IP address</dt>
 142
 143       <dd>
 144       <div class="example"><h3>Example:</h3><p><code>
 145         Allow from 10.1<br />
 146         Allow from 10 172.20 192.168.2
 147       </code></p></div>
 148       <p>The first 1 to 3 bytes of an IP address, for subnet
 149       restriction.</p></dd>
 150
 151       <dt>A network/netmask pair</dt>
 152
 153       <dd>
 154       <div class="example"><h3>Example:</h3><p><code>
 155         Allow from 10.1.0.0/255.255.0.0
 156       </code></p></div>
 157       <p>A network a.b.c.d, and a netmask w.x.y.z. For more
 158       fine-grained subnet restriction.</p></dd>
 159
 160       <dt>A network/nnn CIDR specification</dt>
 161
 162       <dd>
 163       <div class="example"><h3>Example:</h3><p><code>
 164         Allow from 10.1.0.0/16
 165       </code></p></div>
 166       <p>Similar to the previous case, except the netmask consists of
 167       nnn high-order 1 bits.</p></dd>
 168     </dl>
 169
 170     <p>Note that the last three examples above match exactly the
 171     same set of hosts.</p>
 172
 173     <p>IPv6 addresses and IPv6 subnets can be specified as shown
 174     below:</p>
 175
 176     <div class="example"><p><code>
 177        Allow from 2001:db8::a00:20ff:fea7:ccea<br />
 178        Allow from 2001:db8::a00:20ff:fea7:ccea/10
 179     </code></p></div>
 180
 181     <p>The third format of the arguments to the
 182     <code class="directive">Allow</code> directive allows access to the server
 183     to be controlled based on the existence of an <a href="../env.html">environment variable</a>. When <code>Allow from
 184     env=<var>env-variable</var></code> is specified, then the request is
 185     allowed access if the environment variable <var>env-variable</var>
 186     exists. The server provides the ability to set environment
 187     variables in a flexible way based on characteristics of the client
 188     request using the directives provided by
 189     <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code>. Therefore, this directive can be
 190     used to allow access based on such factors as the clients
 191     <code>User-Agent</code> (browser type), <code>Referer</code>, or
 192     other HTTP request header fields.</p>
 193
 194     <div class="example"><h3>Example:</h3><p><code>
 195       SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in<br />
 196       &lt;Directory /docroot&gt;<br />
 197       <span class="indent">
 198         Order Deny,Allow<br />
 199         Deny from all<br />
 200         Allow from env=let_me_in<br />
 201       </span>
 202       &lt;/Directory&gt;
 203     </code></p></div>
 204
 205     <p>In this case, browsers with a user-agent string beginning
 206     with <code>KnockKnock/2.0</code> will be allowed access, and all
 207     others will be denied.</p>
 208
 209 </div>
 210 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 211 <div class="directive-section"><h2><a name="Deny" id="Deny">Deny</a> <a name="deny" id="deny">Directive</a></h2>
 212 <table class="directive">
 213 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls which hosts are denied access to the
 214 server</td></tr>
 215 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> Deny from all|<var>host</var>|env=<var>env-variable</var>
 216 [<var>host</var>|env=<var>env-variable</var>] ...</code></td></tr>
 217 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 218 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Limit</td></tr>
 219 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 220 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_access_compat</td></tr>
 221 </table>
 222     <p>This directive allows access to the server to be restricted
 223     based on hostname, IP address, or environment variables. The
 224     arguments for the <code class="directive">Deny</code> directive are
 225     identical to the arguments for the <code class="directive"><a href="#allow">Allow</a></code> directive.</p>
 226
 227 </div>
 228 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 229 <div class="directive-section"><h2><a name="Order" id="Order">Order</a> <a name="order" id="order">Directive</a></h2>
 230 <table class="directive">
 231 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls the default access state and the order in which
 232 <code class="directive">Allow</code> and <code class="directive">Deny</code> are
 233 evaluated.</td></tr>
 234 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> Order <var>ordering</var></code></td></tr>
 235 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Order Deny,Allow</code></td></tr>
 236 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 237 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Limit</td></tr>
 238 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 239 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_access_compat</td></tr>
 240 </table>
 241     <p>The <code class="directive">Order</code> directive controls the default
 242     access state and the order in which <code class="directive"><a href="#allow">Allow</a></code> and <code class="directive"><a href="#deny">Deny</a></code> directives are evaluated.
 243     <var>Ordering</var> is one of</p>
 244
 245     <dl>
 246       <dt><code>Deny,Allow</code></dt>
 247
 248       <dd>The <code class="directive"><a href="#deny">Deny</a></code> directives
 249       are evaluated before the <code class="directive"><a href="#allow">Allow</a></code> directives. Access is
 250       allowed by default. Any client which does not match a
 251       <code class="directive"><a href="#deny">Deny</a></code> directive or does
 252       match an <code class="directive"><a href="#allow">Allow</a></code>
 253       directive will be allowed access to the server.</dd>
 254
 255       <dt><code>Allow,Deny</code></dt>
 256
 257       <dd>The <code class="directive"><a href="#allow">Allow</a></code>
 258       directives are evaluated before the <code class="directive"><a href="#deny">Deny</a></code> directives. Access is denied
 259       by default. Any client which does not match an <code class="directive"><a href="#allow">Allow</a></code> directive or does match a
 260       <code class="directive"><a href="#deny">Deny</a></code> directive will be
 261       denied access to the server.</dd>
 262
 263       <dt><code>Mutual-failure</code></dt>
 264
 265       <dd>Only those hosts which appear on the <code class="directive"><a href="#allow">Allow</a></code> list and do not appear on
 266       the <code class="directive"><a href="#deny">Deny</a></code> list are
 267       granted access. This ordering has the same effect as <code>Order
 268       Allow,Deny</code> and is deprecated in favor of that
 269       configuration.</dd>
 270     </dl>
 271
 272     <p>Keywords may only be separated by a comma; <em>no whitespace</em> is
 273     allowed between them. Note that in all cases every <code class="directive"><a href="#allow">Allow</a></code> and <code class="directive"><a href="#deny">Deny</a></code> statement is evaluated.</p>
 274
 275     <p>In the following example, all hosts in the apache.org domain
 276     are allowed access; all other hosts are denied access.</p>
 277
 278     <div class="example"><p><code>
 279       Order Deny,Allow<br />
 280       Deny from all<br />
 281       Allow from apache.org
 282     </code></p></div>
 283
 284     <p>In the next example, all hosts in the apache.org domain are
 285     allowed access, except for the hosts which are in the
 286     foo.apache.org subdomain, who are denied access. All hosts not
 287     in the apache.org domain are denied access because the default
 288     state is to deny access to the server.</p>
 289
 290     <div class="example"><p><code>
 291       Order Allow,Deny<br />
 292       Allow from apache.org<br />
 293       Deny from foo.apache.org
 294     </code></p></div>
 295
 296     <p>On the other hand, if the <code class="directive">Order</code> in the last
 297     example is changed to <code>Deny,Allow</code>, all hosts will
 298     be allowed access. This happens because, regardless of the
 299     actual ordering of the directives in the configuration file,
 300     the <code>Allow from apache.org</code> will be evaluated last
 301     and will override the <code>Deny from foo.apache.org</code>.
 302     All hosts not in the <code>apache.org</code> domain will also
 303     be allowed access because the default state will change to
 304     <em>allow</em>.</p>
 305
 306     <p>The presence of an <code class="directive">Order</code> directive can affect
 307     access to a part of the server even in the absence of accompanying
 308     <code class="directive"><a href="#allow">Allow</a></code> and <code class="directive"><a href="#deny">Deny</a></code> directives because of its effect
 309     on the default access state. For example,</p>
 310
 311     <div class="example"><p><code>
 312       &lt;Directory /www&gt;<br />
 313       <span class="indent">
 314         Order Allow,Deny<br />
 315       </span>
 316       &lt;/Directory&gt;
 317     </code></p></div>
 318
 319     <p>will deny all access to the <code>/www</code> directory
 320     because the default access state will be set to
 321     <em>deny</em>.</p>
 322
 323     <p>The <code class="directive">Order</code> directive controls the order of access
 324     directive processing only within each phase of the server's
 325     configuration processing. This implies, for example, that an
 326     <code class="directive"><a href="#allow">Allow</a></code> or <code class="directive"><a href="#deny">Deny</a></code> directive occurring in a
 327     <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> section will
 328     always be evaluated after an <code class="directive"><a href="#allow">Allow</a></code> or <code class="directive"><a href="#deny">Deny</a></code> directive occurring in a
 329     <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> section or
 330     <code>.htaccess</code> file, regardless of the setting of the
 331     <code class="directive">Order</code> directive. For details on the merging
 332     of configuration sections, see the documentation on <a href="../sections.html">How Directory, Location and Files sections
 333     work</a>.</p>
 334
 335 </div>
 336 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 337 <div class="directive-section"><h2><a name="Satisfy" id="Satisfy">Satisfy</a> <a name="satisfy" id="satisfy">Directive</a></h2>
 338 <table class="directive">
 339 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Interaction between host-level access control and
 340 user authentication</td></tr>
 341 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Satisfy Any|All</code></td></tr>
 342 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Satisfy All</code></td></tr>
 343 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 344 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 345 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 346 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_access_compat</td></tr>
 347 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Influenced by <code class="directive"><a href="../mod/core.html#limit">&lt;Limit&gt;</a></code> and <code class="directive"><a href="../mod/core.html#limitexcept">&lt;LimitExcept&gt;</a></code> in version 2.0.51 and
 348 later</td></tr>
 349 </table>
 350     <p>Access policy if both <code class="directive"><a href="../mod/mod_authz_host.html#allow">Allow</a></code> and <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> used. The parameter can be
 351     either <code>All</code> or <code>Any</code>. This directive is only
 352     useful if access to a particular area is being restricted by both
 353     username/password <em>and</em> client host address. In this case
 354     the default behavior (<code>All</code>) is to require that the client
 355     passes the address access restriction <em>and</em> enters a valid
 356     username and password. With the <code>Any</code> option the client will be
 357     granted access if they either pass the host restriction or enter a
 358     valid username and password. This can be used to password restrict
 359     an area, but to let clients from particular addresses in without
 360     prompting for a password.</p>
 361
 362     <p>For example, if you wanted to let people on your network have
 363     unrestricted access to a portion of your website, but require that
 364     people outside of your network provide a password, you could use a
 365     configuration similar to the following:</p>
 366
 367     <div class="example"><p><code>
 368       Require valid-user<br />
 369       Allow from 192.168.1<br />
 370       Satisfy Any
 371     </code></p></div>
 372
 373     <p>Since version 2.0.51 <code class="directive">Satisfy</code> directives can
 374     be restricted to particular methods by <code class="directive"><a href="../mod/core.html#limit">&lt;Limit&gt;</a></code> and <code class="directive"><a href="../mod/core.html#limitexcept">&lt;LimitExcept&gt;</a></code> sections.</p>
 375
 376 <h3>See also</h3>
 377 <ul>
 378 <li><code class="directive"><a href="#allow">Allow</a></code></li>
 379 <li><code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code></li>
 380 </ul>
 381 </div>
 382 </div>
 383 <div class="bottomlang">
 384 <p><span>Available Languages: </span><a href="../en/mod/mod_access_compat.html" title="English">&nbsp;en&nbsp;</a></p>
 385 </div><div id="footer">
 386 <p class="apache">Copyright 2006 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 387 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 388 </body></html>