granicus.if.org Git - apache/blob - docs/manual/mod/mod_authz_host.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.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 <modulesynopsis metafile="mod_authz_host.xml.meta">
  24
  25 <name>mod_authz_host</name>
  26 <description>Group authorizations based on host (name or IP
  27 address)</description>
  28 <status>Base</status>
  29 <sourcefile>mod_authz_host.c</sourcefile>
  30 <identifier>authz_host_module</identifier>
  31 <compatibility>Available in Apache 2.3 and later</compatibility>
  32
  33 <summary>
  34     <p>The authorization providers implemented by <module>mod_authz_host</module> are
  35     registered using the <directive module="mod_authz_core">Require</directive>
  36     directive. The directive can be referenced within a
  37     <directive module="core" type="section">Directory</directive>,
  38     <directive module="core" type="section">Files</directive>,
  39     or <directive module="core" type="section">Location</directive> section
  40     as well as <code><a href="core.html#accessfilename">.htaccess</a>
  41     </code> files to control access to particular parts of the server.
  42     Access can be controlled based on the client hostname or IP address.</p>
  43
  44     <p>In general, access restriction directives apply to all
  45     access methods (<code>GET</code>, <code>PUT</code>,
  46     <code>POST</code>, etc). This is the desired behavior in most
  47     cases. However, it is possible to restrict some methods, while
  48     leaving other methods unrestricted, by enclosing the directives
  49     in a <directive module="core" type="section">Limit</directive> section.</p>
  50 </summary>
  51
  52 <seealso><a href="../howto/auth.html">Authentication, Authorization,
  53     and Access Control</a></seealso>
  54 <seealso><directive module="mod_authz_core">Require</directive></seealso>
  55
  56 <section id="requiredirectives"><title>The Require Directives</title>
  57
  58     <p>Apache's <directive module="mod_authz_core">Require</directive>
  59     directive is used during the authorization phase to ensure that a user is allowed or
  60     denied access to a resource.  mod_authz_host extends the
  61     authorization types with <code>ip</code>, <code>host</code> and <code>local</code>.
  62     Other authorization types may also be
  63     used but may require that additional authorization modules be loaded.</p>
  64
  65     <p>These authorization providers affect which hosts can
  66     access an area of the server. Access can be controlled by
  67     hostname, IP Address, or IP Address range.</p>
  68
  69     <p>Since v2.4.8, <a href="../expr.html">expressions</a> are supported
  70     within the host require directives.</p>
  71
  72 <section id="reqip"><title>Require ip</title>
  73
  74     <p>The <code>ip</code> provider allows access to the server
  75     to be controlled based on the IP address of the remote client.
  76     When <code>Require ip <var>ip-address</var></code> is specified,
  77     then the request is allowed access if the IP address matches.</p>
  78
  79     <p>A full IP address:</p>
  80
  81     <highlight language="config">
  82 Require ip 10.1.2.3
  83 Require ip 192.168.1.104 192.168.1.205
  84     </highlight>
  85
  86     <p>An IP address of a host allowed access</p>
  87
  88     <p>A partial IP address:</p>
  89
  90     <highlight language="config">
  91 Require ip 10.1
  92 Require ip 10 172.20 192.168.2
  93     </highlight>
  94     <p>The first 1 to 3 bytes of an IP address, for subnet
  95     restriction.</p>
  96
  97     <p>A network/netmask pair:</p>
  98
  99     <highlight language="config">
 100       Require ip 10.1.0.0/255.255.0.0
 101     </highlight>
 102     <p>A network a.b.c.d, and a netmask w.x.y.z. For more
 103     fine-grained subnet restriction.</p>
 104
 105     <p>A network/nnn CIDR specification:</p>
 106
 107     <highlight language="config">
 108       Require ip 10.1.0.0/16
 109     </highlight>
 110     <p>Similar to the previous case, except the netmask consists of
 111     nnn high-order 1 bits.</p>
 112
 113     <p>Note that the last three examples above match exactly the
 114     same set of hosts.</p>
 115
 116     <p>IPv6 addresses and IPv6 subnets can be specified as shown
 117     below:</p>
 118
 119     <highlight language="config">
 120 Require ip 2001:db8::a00:20ff:fea7:ccea
 121 Require ip 2001:db8:1:1::a
 122 Require ip 2001:db8:2:1::/64
 123 Require ip 2001:db8:3::/48
 124     </highlight>
 125
 126     <p>Note: As the IP addresses are parsed on startup, expressions are
 127     not evaluated at request time.</p>
 128
 129 </section>
 130
 131 <section id="reqhost"><title>Require host</title>
 132
 133     <p>The <code>host</code> provider allows access to the server
 134     to be controlled based on the host name of the remote client.
 135     When <code>Require host <var>host-name</var></code> is specified,
 136     then the request is allowed access if the host name matches.</p>
 137
 138     <p>A (partial) domain-name</p>
 139
 140     <highlight language="config">
 141 Require host example.org
 142 Require host .net example.edu
 143     </highlight>
 144
 145     <p>Hosts whose names match, or end in, this string are allowed
 146     access. Only complete components are matched, so the above
 147     example will match <code>foo.example.org</code> but it will not
 148     match <code>fooexample.org</code>. This configuration will cause
 149     Apache to perform a double reverse DNS lookup on the client IP
 150     address, regardless of the setting of the <directive
 151     module="core">HostnameLookups</directive> directive.  It will do
 152     a reverse DNS lookup on the IP address to find the associated
 153     hostname, and then do a forward lookup on the hostname to assure
 154     that it matches the original IP address.  Only if the forward
 155     and reverse DNS are consistent and the hostname matches will
 156     access be allowed.</p>
 157
 158 </section>
 159
 160 <section id="reqlocal"><title>Require local</title>
 161
 162     <p>The <code>local</code> provider allows access to the server if any
 163     of the following conditions is true:</p>
 164
 165     <ul>
 166         <li>the client address matches 127.0.0.0/8</li>
 167         <li>the client address is ::1</li>
 168         <li>both the client and the server address of the connection are
 169         the same</li>
 170     </ul>
 171
 172     <p>This allows a convenient way to match connections that originate from
 173     the local host:</p>
 174
 175     <highlight language="config">
 176     Require local
 177     </highlight>
 178
 179 </section>
 180
 181 <section id="proxy"><title>Security Note</title>
 182
 183     <p>If you are proxying content to your server, you need to be aware
 184     that the client address will be the address of your proxy server,
 185     not the address of the client, and so using the <code>Require</code>
 186     directive in this context may not do what you mean. See
 187     <module>mod_remoteip</module> for one possible solution to this
 188     problem.</p>
 189
 190 </section>
 191
 192 </section>
 193
 194 </modulesynopsis>