docs/manual/mod/mod_authz_host.xml - httpd - Git at Google


            
            <?xml version="1.0"?>

            
            <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">

            
            <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>

            
            <!-- $LastChangedRevision$ -->


            <!--

            
             Licensed to the Apache Software Foundation (ASF) under one or more

            
             contributor license agreements.  See the NOTICE file distributed with

            
             this work for additional information regarding copyright ownership.

            
             The ASF licenses this file to You under the Apache License, Version 2.0

            
             (the "License"); you may not use this file except in compliance with

            
             the License.  You may obtain a copy of the License at


                 http://www.apache.org/licenses/LICENSE-2.0


             Unless required by applicable law or agreed to in writing, software

            
             distributed under the License is distributed on an "AS IS" BASIS,

            
             WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

            
             See the License for the specific language governing permissions and

            
             limitations under the License.

            
            -->


            <modulesynopsis metafile="mod_authz_host.xml.meta">


            <name>mod_authz_host</name>

            
            <description>Group authorizations based on host (name or IP

            
            address)</description>

            
            <status>Base</status>

            
            <sourcefile>mod_authz_host.c</sourcefile>

            
            <identifier>authz_host_module</identifier>

            
            <compatibility>The <code>forward-dns</code> provider was added in 2.4.19</compatibility>


            <summary>

            
                <p>The authorization providers implemented by <module>mod_authz_host</module> are

            
                registered using the <directive module="mod_authz_core">Require</directive>

            
                directive. The directive can be referenced within a

            
                <directive module="core" type="section">Directory</directive>,

            
                <directive module="core" type="section">Files</directive>,

            
                or <directive module="core" type="section">Location</directive> section

            
                as well as <code><a href="core.html#accessfilename">.htaccess</a>

            
                </code> files to control access to particular parts of the server.

            
                Access can be controlled based on the client hostname or IP address.</p>


                <p>In general, access restriction directives apply to all

            
                access methods (<code>GET</code>, <code>PUT</code>,

            
                <code>POST</code>, etc). This is the desired behavior in most

            
                cases. However, it is possible to restrict some methods, while

            
                leaving other methods unrestricted, by enclosing the directives

            
                in a <directive module="core" type="section">Limit</directive> section.</p>

            
            </summary>


            <seealso><a href="../howto/auth.html">Authentication, Authorization,

            
                and Access Control</a></seealso>

            
            <seealso><directive module="mod_authz_core">Require</directive></seealso>

            
            <seealso><a href="mod_authz_core.html#authzresults">Authorization Result States</a></seealso>


            <section id="requiredirectives"><title>The Require Directives</title>


                <p>Apache's <directive module="mod_authz_core">Require</directive>

            
                directive is used during the authorization phase to ensure that a user is allowed or

            
                denied access to a resource.  mod_authz_host extends the

            
                authorization types with <code>ip</code>, <code>host</code>,

            
                <code>forward-dns</code> and <code>local</code>.

            
                Other authorization types may also be

            
                used but may require that additional authorization modules be loaded.</p>


                <p>These authorization providers affect which hosts can

            
                access an area of the server. Access can be controlled by

            
                hostname, IP Address, or IP Address range.</p>


                <p>Since v2.4.8, <a href="../expr.html">expressions</a> are supported

            
                within the host require directives.</p>


            <section id="reqip"><title>Require ip</title>


                <p>The <code>ip</code> provider allows access to the server

            
                to be controlled based on the IP address of the remote client.

            
                When <code>Require ip <var>ip-address</var></code> is specified,

            
                then the request is allowed access if the IP address matches.</p>


                <p>A full IP address:</p>


                <highlight language="config">

            
            Require ip 10.1.2.3

            
            Require ip 192.168.1.104 192.168.1.205

            
                </highlight>


                <p>An IP address of a host allowed access</p>


                <p>A partial IP address:</p>


                <highlight language="config">

            
            Require ip 10.1

            
            Require ip 10 172.20 192.168.2

            
                </highlight>

            
                <p>The first 1 to 3 bytes of an IP address, for subnet

            
                restriction.</p>


                <p>A network/netmask pair:</p>


                <highlight language="config">

            
                  Require ip 10.1.0.0/255.255.0.0

            
                </highlight>

            
                <p>A network a.b.c.d, and a netmask w.x.y.z. For more

            
                fine-grained subnet restriction.</p>


                <p>A network/nnn CIDR specification:</p>


                <highlight language="config">

            
                  Require ip 10.1.0.0/16

            
                </highlight>

            
                <p>Similar to the previous case, except the netmask consists of

            
                nnn high-order 1 bits.</p>


                <p>Note that the last three examples above match exactly the

            
                same set of hosts.</p>


                <p>IPv6 addresses and IPv6 subnets can be specified as shown

            
                below:</p>


                <highlight language="config">

            
            Require ip 2001:db8::a00:20ff:fea7:ccea

            
            Require ip 2001:db8:1:1::a

            
            Require ip 2001:db8:2:1::/64

            
            Require ip 2001:db8:3::/48

            
                </highlight>


                <p>Note: As the IP addresses are parsed on startup, expressions are

            
                not evaluated at request time.</p>


            </section>


            <section id="reqhost"><title>Require host</title>


                <p>The <code>host</code> provider allows access to the server

            
                to be controlled based on the host name of the remote client.

            
                When <code>Require host <var>host-name</var></code> is specified,

            
                then the request is allowed access if the host name matches.</p>


                <p>A (partial) domain-name</p>


                <highlight language="config">

            
            Require host example.org

            
            Require host .net example.edu

            
                </highlight>


                <p>Hosts whose names match, or end in, this string are allowed

            
                access. Only complete components are matched, so the above

            
                example will match <code>foo.example.org</code> but it will not

            
                match <code>fooexample.org</code>. This configuration will cause

            
                Apache to perform a double reverse DNS lookup on the client IP

            
                address, regardless of the setting of the <directive

            
                module="core">HostnameLookups</directive> directive.  It will do

            
                a reverse DNS lookup on the IP address to find the associated

            
                hostname, and then do a forward lookup on the hostname to assure

            
                that it matches the original IP address.  Only if the forward

            
                and reverse DNS are consistent and the hostname matches will

            
                access be allowed.</p>


            </section>


            <section id="reqfwddns"><title>Require forward-dns</title>


                <p>The <code>forward-dns</code> provider allows access to the server

            
                to be controlled based on simple host names.  When

            
                <code>Require forward-dns <var>host-name</var></code> is specified,

            
                all IP addresses corresponding to <code><var>host-name</var></code>

            
                are allowed access.</p>


                <p>In contrast to the <code>host</code> provider, this provider does not

            
                rely on reverse DNS lookups: it simply queries the DNS for the host name

            
                and allows a client if its IP matches.  As a consequence, it will only

            
                work with complete host names that can be resolved in DNS, not partial domain names.

            
                However, as the reverse DNS is not used, and DNS lookups occur at request processing

            
                time (instead of startup), it will work with clients which use a dynamic DNS service.</p>


                <highlight language="config">

            
            Require forward-dns dynamic.example.org

            
                </highlight>


                <p>A client the IP of which is resolved from the name

            
                <code>dynamic.example.org</code> will be granted access.</p>


                <p>The <code>forward-dns</code> provider was added in 2.4.19.</p>

            
            </section>


            <section id="reqlocal"><title>Require local</title>


                <p>The <code>local</code> provider allows access to the server if any

            
                of the following conditions is true:</p>


                <ul>

            
                    <li>the client address matches 127.0.0.0/8</li>

            
                    <li>the client address is ::1</li>

            
                    <li>both the client and the server address of the connection are

            
                    the same</li>

            
                </ul>


                <p>This allows a convenient way to match connections that originate from

            
                the local host:</p>


                <highlight language="config">

            
                Require local

            
                </highlight>


            </section>


            <section id="proxy"><title>Security Note</title>


                <p>If you are proxying content to your server, you need to be aware

            
                that the client address will be the address of your proxy server,

            
                not the address of the client, and so using the <code>Require</code>

            
                directive in this context may not do what you mean. See

            
                <module>mod_remoteip</module> for one possible solution to this

            
                problem.</p>


            </section>


            </section>


            </modulesynopsis>
	<?xml version="1.0"?>
	<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
	<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
	<!-- $LastChangedRevision$ -->

	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<modulesynopsis metafile="mod_authz_host.xml.meta">

	<name>mod_authz_host</name>
	<description>Group authorizations based on host (name or IP
	address)</description>
	<status>Base</status>
	<sourcefile>mod_authz_host.c</sourcefile>
	<identifier>authz_host_module</identifier>
	<compatibility>The <code>forward-dns</code> provider was added in 2.4.19</compatibility>

	<summary>
	<p>The authorization providers implemented by <module>mod_authz_host</module> are
	registered using the <directive module="mod_authz_core">Require</directive>
	directive. The directive can be referenced within a
	<directive module="core" type="section">Directory</directive>,
	<directive module="core" type="section">Files</directive>,
	or <directive module="core" type="section">Location</directive> section
	as well as <code><a href="core.html#accessfilename">.htaccess</a>
	</code> files to control access to particular parts of the server.
	Access can be controlled based on the client hostname or IP address.</p>

	<p>In general, access restriction directives apply to all
	access methods (<code>GET</code>, <code>PUT</code>,
	<code>POST</code>, etc). This is the desired behavior in most
	cases. However, it is possible to restrict some methods, while
	leaving other methods unrestricted, by enclosing the directives
	in a <directive module="core" type="section">Limit</directive> section.</p>
	</summary>

	<seealso><a href="../howto/auth.html">Authentication, Authorization,
	and Access Control</a></seealso>
	<seealso><directive module="mod_authz_core">Require</directive></seealso>
	<seealso><a href="mod_authz_core.html#authzresults">Authorization Result States</a></seealso>

	<section id="requiredirectives"><title>The Require Directives</title>

	<p>Apache's <directive module="mod_authz_core">Require</directive>
	directive is used during the authorization phase to ensure that a user is allowed or
	denied access to a resource. mod_authz_host extends the
	authorization types with <code>ip</code>, <code>host</code>,
	<code>forward-dns</code> and <code>local</code>.
	Other authorization types may also be
	used but may require that additional authorization modules be loaded.</p>

	<p>These authorization providers affect which hosts can
	access an area of the server. Access can be controlled by
	hostname, IP Address, or IP Address range.</p>

	<p>Since v2.4.8, <a href="../expr.html">expressions</a> are supported
	within the host require directives.</p>

	<section id="reqip"><title>Require ip</title>

	<p>The <code>ip</code> provider allows access to the server
	to be controlled based on the IP address of the remote client.
	When <code>Require ip <var>ip-address</var></code> is specified,
	then the request is allowed access if the IP address matches.</p>

	<p>A full IP address:</p>

	<highlight language="config">
	Require ip 10.1.2.3
	Require ip 192.168.1.104 192.168.1.205
	</highlight>

	<p>An IP address of a host allowed access</p>

	<p>A partial IP address:</p>

	<highlight language="config">
	Require ip 10.1
	Require ip 10 172.20 192.168.2
	</highlight>
	<p>The first 1 to 3 bytes of an IP address, for subnet
	restriction.</p>

	<p>A network/netmask pair:</p>

	<highlight language="config">
	Require ip 10.1.0.0/255.255.0.0
	</highlight>
	<p>A network a.b.c.d, and a netmask w.x.y.z. For more
	fine-grained subnet restriction.</p>

	<p>A network/nnn CIDR specification:</p>

	<highlight language="config">
	Require ip 10.1.0.0/16
	</highlight>
	<p>Similar to the previous case, except the netmask consists of
	nnn high-order 1 bits.</p>

	<p>Note that the last three examples above match exactly the
	same set of hosts.</p>

	<p>IPv6 addresses and IPv6 subnets can be specified as shown
	below:</p>

	<highlight language="config">
	Require ip 2001:db8::a00:20ff:fea7:ccea
	Require ip 2001:db8:1:1::a
	Require ip 2001:db8:2:1::/64
	Require ip 2001:db8:3::/48
	</highlight>

	<p>Note: As the IP addresses are parsed on startup, expressions are
	not evaluated at request time.</p>

	</section>

	<section id="reqhost"><title>Require host</title>

	<p>The <code>host</code> provider allows access to the server
	to be controlled based on the host name of the remote client.
	When <code>Require host <var>host-name</var></code> is specified,
	then the request is allowed access if the host name matches.</p>

	<p>A (partial) domain-name</p>

	<highlight language="config">
	Require host example.org
	Require host .net example.edu
	</highlight>

	<p>Hosts whose names match, or end in, this string are allowed
	access. Only complete components are matched, so the above
	example will match <code>foo.example.org</code> but it will not
	match <code>fooexample.org</code>. This configuration will cause
	Apache to perform a double reverse DNS lookup on the client IP
	address, regardless of the setting of the <directive
	module="core">HostnameLookups</directive> directive. It will do
	a reverse DNS lookup on the IP address to find the associated
	hostname, and then do a forward lookup on the hostname to assure
	that it matches the original IP address. Only if the forward
	and reverse DNS are consistent and the hostname matches will
	access be allowed.</p>

	</section>

	<section id="reqfwddns"><title>Require forward-dns</title>

	<p>The <code>forward-dns</code> provider allows access to the server
	to be controlled based on simple host names. When
	<code>Require forward-dns <var>host-name</var></code> is specified,
	all IP addresses corresponding to <code><var>host-name</var></code>
	are allowed access.</p>

	<p>In contrast to the <code>host</code> provider, this provider does not
	rely on reverse DNS lookups: it simply queries the DNS for the host name
	and allows a client if its IP matches. As a consequence, it will only
	work with complete host names that can be resolved in DNS, not partial domain names.
	However, as the reverse DNS is not used, and DNS lookups occur at request processing
	time (instead of startup), it will work with clients which use a dynamic DNS service.</p>

	<highlight language="config">
	Require forward-dns dynamic.example.org
	</highlight>

	<p>A client the IP of which is resolved from the name
	<code>dynamic.example.org</code> will be granted access.</p>

	<p>The <code>forward-dns</code> provider was added in 2.4.19.</p>
	</section>

	<section id="reqlocal"><title>Require local</title>

	<p>The <code>local</code> provider allows access to the server if any
	of the following conditions is true:</p>

	<ul>
	<li>the client address matches 127.0.0.0/8</li>
	<li>the client address is ::1</li>
	<li>both the client and the server address of the connection are
	the same</li>
	</ul>

	<p>This allows a convenient way to match connections that originate from
	the local host:</p>

	<highlight language="config">
	Require local
	</highlight>

	</section>

	<section id="proxy"><title>Security Note</title>

	<p>If you are proxying content to your server, you need to be aware
	that the client address will be the address of your proxy server,
	not the address of the client, and so using the <code>Require</code>
	directive in this context may not do what you mean. See
	<module>mod_remoteip</module> for one possible solution to this
	problem.</p>

	</section>

	</section>

	</modulesynopsis>