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_authz_host.xml.meta">
25 <name>mod_authz_host</name>
26 <description>Group authorizations based on host (name or IP
27 address)</description>
29 <sourcefile>mod_authz_host.c</sourcefile>
30 <identifier>authz_host_module</identifier>
31 <compatibility>Available in Apache 2.3 and later</compatibility>
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, IP address, or
43 other characteristics of the client request, as captured in <a
44 href="../env.html">environment variables</a>.</p>
46 <p>In general, access restriction directives apply to all
47 access methods (<code>GET</code>, <code>PUT</code>,
48 <code>POST</code>, etc). This is the desired behavior in most
49 cases. However, it is possible to restrict some methods, while
50 leaving other methods unrestricted, by enclosing the directives
51 in a <directive module="core" type="section">Limit</directive> section.</p>
54 <seealso><a href="../howto/auth.html">Authentication, Authorization,
55 and Access Control</a></seealso>
56 <seealso><directive module="mod_authz_core">Require</directive></seealso>
58 <section id="requiredirectives"><title>The Require Directives</title>
60 <p>Apache's <directive module="mod_authz_core">Require</directive>
61 directive is used during the authorization phase to ensure that a user is allowed or
62 denied access to a resource. mod_authz_host extends the
63 authorization types with <code>env</code>, <code>ip</code>,
64 <code>host</code> and <code>all</code>. Other authorization types may also be
65 used but may require that additional authorization modules be loaded.</p>
67 <p>These authorization providers affect which hosts can
68 access an area of the server. Access can be controlled by
69 hostname, IP Address, IP Address range, or by other
70 characteristics of the client request captured in environment
73 <section id="reqenv"><title>Require env</title>
75 <p>The <code>env</code> provider allows access to the server
76 to be controlled based on the existence of an <a
77 href="../env.html">environment variable</a>. When <code>Require
78 env <var>env-variable</var></code> is specified, then the request is
79 allowed access if the environment variable <var>env-variable</var>
80 exists. The server provides the ability to set environment
81 variables in a flexible way based on characteristics of the client
82 request using the directives provided by
83 <module>mod_setenvif</module>. Therefore, this directive can be
84 used to allow access based on such factors as the clients
85 <code>User-Agent</code> (browser type), <code>Referer</code>, or
86 other HTTP request header fields.</p>
88 <example><title>Example:</title>
89 SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in<br />
90 <Directory /docroot><br />
92 Require env let_me_in<br />
97 <p>In this case, browsers with a user-agent string beginning
98 with <code>KnockKnock/2.0</code> will be allowed access, and all
99 others will be denied.</p>
103 <section id="reqip"><title>Require ip</title>
105 <p>The <code>ip</code> provider allows access to the server
106 to be controlled based on the IP address of the remote client.
107 When <code>Require ip <var>ip-address</var></code> is specified,
108 then the request is allowed access if the IP address matches.</p>
110 <p>A full IP address:</p>
113 Require ip 10.1.2.3<br />
114 Require ip 192.168.1.104 192.168.1.205
117 <p>An IP address of a host allowed access</p>
119 <p>A partial IP address:</p>
122 Require ip 10.1<br />
123 Require ip 10 172.20 192.168.2
125 <p>The first 1 to 3 bytes of an IP address, for subnet
128 <p>A network/netmask pair:</p>
131 Require ip 10.1.0.0/255.255.0.0
133 <p>A network a.b.c.d, and a netmask w.x.y.z. For more
134 fine-grained subnet restriction.</p>
136 <p>A network/nnn CIDR specification:</p>
139 Require ip 10.1.0.0/16
141 <p>Similar to the previous case, except the netmask consists of
142 nnn high-order 1 bits.</p>
144 <p>Note that the last three examples above match exactly the
145 same set of hosts.</p>
147 <p>IPv6 addresses and IPv6 subnets can be specified as shown
151 Require ip 2001:db8::a00:20ff:fea7:ccea<br />
152 Require ip 2001:db8::a00:20ff:fea7:ccea/10
158 <section id="reqhost"><title>Require host</title>
160 <p>The <code>host</code> provider allows access to the server
161 to be controlled based on the host name of the remote client.
162 When <code>Require host <var>host-name</var></code> is specified,
163 then the request is allowed access if the host name matches.</p>
165 <p>A (partial) domain-name</p>
168 Require host apache.org<br />
169 Require host .net example.edu
172 <p>Hosts whose names match, or end in, this string are allowed
173 access. Only complete components are matched, so the above
174 example will match <code>foo.apache.org</code> but it will not
175 match <code>fooapache.org</code>. This configuration will cause
176 Apache to perform a double reverse DNS lookup on the client IP
177 address, regardless of the setting of the <directive
178 module="core">HostnameLookups</directive> directive. It will do
179 a reverse DNS lookup on the IP address to find the associated
180 hostname, and then do a forward lookup on the hostname to assure
181 that it matches the original IP address. Only if the forward
182 and reverse DNS are consistent and the hostname matches will
183 access be allowed.</p>
187 <section id="reqall"><title>Require all</title>
189 <p>The <code>all</code> provider mimics the functionality the
190 was previously provided by the 'Allow from all' and 'Deny from all'
191 directives. This provider can take one of two arguments which are
192 'granted' or 'denied'. The following examples will grant or deny
193 access to all requests.</p>
196 Require all granted<br />
200 Require all denied<br />