granicus.if.org Git - apache/blob - docs/manual/howto/access.xml

   1 <?xml version='1.0' encoding='UTF-8' ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   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
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  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.
  21 -->
  22
  23 <manualpage metafile="access.xml.meta">
  24 <parentdocument href="./">How-To / Tutorials</parentdocument>
  25
  26 <title>Access Control</title>
  27
  28 <summary>
  29     <p>Access control refers to any means of controlling access to any
  30     resource. This is separate from <a
  31     href="auth.html">authentication and authorization</a>.</p>
  32 </summary>
  33
  34 <section id="related"><title>Related Modules and Directives</title>
  35
  36     <p>Access control can be done by several different modules. The most
  37     important of these are <module>mod_authz_core</module> and
  38     <module>mod_authz_host</module>. Also discussed in this document
  39     is access control using <module>mod_rewrite</module>.</p>
  40
  41 </section>
  42
  43 <section id="host"><title>Access control by host</title>
  44     <p>
  45     If you wish to restrict access to portions of your site based on the
  46     host address of your visitors, this is most easily done using
  47     <module>mod_authz_host</module>.
  48     </p>
  49
  50     <p>The <directive module="mod_authz_core">Require</directive>
  51     provides a variety of different ways to allow or deny access to
  52     resources. In conjunction with the <directive
  53     module="mod_authz_core">RequireAll</directive>, <directive
  54     module="mod_authz_core">RequireAny</directive>, and <directive
  55     module="mod_authz_core">RequireNone</directive> directives, these
  56     requirements may be combined in arbitrarily complex ways, to enforce
  57     whatever your access policy happens to be.</p>
  58
  59     <note type="warning"><p>
  60     The <directive module="mod_access_compat">Allow</directive>,
  61     <directive module="mod_access_compat">Deny</directive>, and
  62     <directive module="mod_access_compat">Order</directive> directives,
  63     provided by <module>mod_access_compat</module>, are deprecated and
  64     will go away in a future version. You should avoid using them, and
  65     avoid outdated tutorials recommending their use.
  66     </p></note>
  67
  68     <p>The usage of these directives is:</p>
  69
  70     <highlight language="config">
  71 Require host address
  72 Require ip ip.address
  73     </highlight>
  74
  75     <p>In the first form, <var>address</var> is a fully qualified
  76     domain name (or a partial domain name); you may provide multiple
  77     addresses or domain names, if desired.</p>
  78
  79     <p>In the second form, <var>ip.address</var> is an IP address, a
  80     partial IP address, a network/netmask pair, or a network/nnn CIDR
  81     specification. Either IPv4 or IPv6 addresses may be used.</p>
  82
  83     <p>See <a href="../mod/mod_authz_host.html#requiredirectives">the
  84     mod_authz_host documentation</a> for further examples of this
  85     syntax.</p>
  86
  87     <p>You can insert <code>not</code> to negate a particular requirement.
  88     Note, that since a <code>not</code> is a negation of a value, it cannot
  89     be used by itself to allow or deny a request, as <em>not true</em>
  90     does not constitute <em>false</em>. Thus, to deny a visit using a negation,
  91     the block must have one element that evaluates as true or false.
  92     For example, if you have someone spamming your message
  93     board, and you want to keep them out, you could do the
  94     following:</p>
  95
  96     <highlight language="config">
  97 &lt;RequireAll&gt;
  98     Require all granted
  99     Require not ip 10.252.46.165
 100 &lt;/RequireAll&gt;
 101 </highlight>
 102
 103     <p>Visitors coming from that address (<code>10.252.46.165</code>)
 104     will not be able to see the content covered by this directive. If,
 105     instead, you have a machine name, rather than an IP address, you
 106     can use that.</p>
 107
 108     <highlight language="config">Require not host <var>host.example.com</var></highlight>
 109
 110     <p>And, if you'd like to block access from an entire domain,
 111     you can specify just part of an address or domain name:</p>
 112
 113     <highlight language="config">
 114 Require not ip 192.168.205
 115 Require not host phishers.example.com moreidiots.example
 116 Require not host gov
 117     </highlight>
 118
 119     <p>Use of the <directive
 120     module="mod_authz_core">RequireAll</directive>, <directive
 121     module="mod_authz_core">RequireAny</directive>, and <directive
 122     module="mod_authz_core">RequireNone</directive> directives may be
 123     used to enforce more complex sets of requirements.</p>
 124
 125 </section>
 126
 127 <section id="env"><title>Access control by arbitrary variables</title>
 128
 129     <p>Using the <directive type="section" module="core">If</directive>,
 130     you can allow or deny access based on arbitrary environment
 131     variables or request header values. For example, to deny access
 132     based on user-agent (the browser type) you might do the
 133     following:</p>
 134
 135     <highlight language="config">
 136 &lt;If "%{HTTP_USER_AGENT} == 'BadBot'"&gt;
 137     Require All Denied
 138 &lt;/If&gt;
 139     </highlight>
 140
 141     <note><title>Warning:</title>
 142     <p>Access control by <code>User-Agent</code> is an unreliable technique,
 143     since the <code>User-Agent</code> header can be set to anything at all,
 144     at the whim of the end user.</p>
 145     </note>
 146
 147     <p>See <a href="../expr.html">the expressions document</a> for a
 148     further discussion of what expression syntaxes and variables are
 149     available to you.</p>
 150
 151 </section>
 152
 153 <section id="rewrite"><title>Access control with mod_rewrite</title>
 154
 155     <p>The <code>[F]</code> <directive
 156     module="mod_rewrite">RewriteRule</directive> flag causes a 403 Forbidden
 157     response to be sent. Using this, you can deny access to a resource based
 158     on arbitrary criteria.</p>
 159
 160     <p>For example, if you wish to block access to a resource between 8pm
 161     and 6am, you can do this using <module>mod_rewrite</module>.</p>
 162
 163     <highlight language="config">
 164 RewriteEngine On
 165 RewriteCond %{TIME_HOUR} &gt;=20 [OR]
 166 RewriteCond %{TIME_HOUR} &lt;07
 167 RewriteRule ^/fridge - [F]
 168     </highlight>
 169
 170     <p>This will return a 403 Forbidden response for any request after 8pm
 171     or before 7am. This technique can be used for any criteria that you wish
 172     to check. You can also redirect, or otherwise rewrite these requests, if
 173     that approach is preferred.</p>
 174
 175     <p>The <directive type="section" module="core">If</directive> directive,
 176     added in 2.4, replaces many things that <module>mod_rewrite</module> has
 177     traditionally been used to do, and you should probably look there first
 178     before resorting to mod_rewrite.</p>
 179
 180 </section>
 181
 182 <section id="moreinformation"><title>More information</title>
 183
 184     <p>The <a href="../expr.html">expression engine</a> gives you a
 185     great deal of power to do a variety of things based on arbitrary
 186     server variables, and you should consult that document for more
 187     detail.</p>
 188
 189     <p>Also, you should read the <module>mod_authz_core</module>
 190     documentation for examples of combining multiple access requirements
 191     and specifying how they interact.</p>
 192
 193     <p>See also the <a href="auth.html">Authentication and Authorization</a>
 194     howto.</p>
 195 </section>
 196
 197 </manualpage>
 198