<?xml version="1.0"?>

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

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

<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>Available in Apache 2.3 and later</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, IP address, or

other characteristics of the client request, as captured in <a

href="/env.html">environment variables</a>.</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>

<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>env</code>, <code>ip</code>,

<code>host</code> and <code>all</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, IP Address range, or by other

characteristics of the client request captured in environment

variables.</p>

<section id="reqenv"><title>Require env</title>

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

to be controlled based on the existence of an <a

href="/env.html">environment variable</a>. When <code>Require

env <var>env-variable</var></code> is specified, then the request is

allowed access if the environment variable <var>env-variable</var>

exists. The server provides the ability to set environment

variables in a flexible way based on characteristics of the client

request using the directives provided by

<module>mod_setenvif</module>. Therefore, this directive can be

used to allow access based on such factors as the clients

<code>User-Agent</code> (browser type), <code>Referer</code>, or

other HTTP request header fields.</p>

<example><title>Example:</title>

SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in<br />

&lt;Directory /docroot&gt;<br />

<indent>

Require env let_me_in<br />

</indent>

&lt;/Directory&gt;

</example>

<p>In this case, browsers with a user-agent string beginning

with <code>KnockKnock/2.0</code> will be allowed access, and all

others will be denied.</p>

</section>

<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>

<example>

Require ip 10.1.2.3<br />

Require ip 192.168.1.104 192.168.1.205

</example>

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

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

<example>

Require ip 10.1<br />

Require ip 10 172.20 192.168.2

</example>

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

restriction.</p>

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

<example>

Require ip 10.1.0.0/255.255.0.0

</example>

<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>

<example>

Require ip 10.1.0.0/16

</example>

<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>

<example>

Require ip 2001:db8::a00:20ff:fea7:ccea<br />

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

</example>

</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>

<example>

Require host apache.org<br />

Require host .net example.edu

</example>

<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.apache.org</code> but it will not

match <code>fooapache.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="reqall"><title>Require all</title>

<p>The <code>all</code> provider mimics the functionality the

was previously provided by the 'Allow from all' and 'Deny from all'

directives. This provider can take one of two arguments which are

'granted' or 'denied'. The following examples will grant or deny

access to all requests.</p>

<example>

Require all granted<br />

</example>

<example>

Require all denied<br />

</example>

</section>

<section id="reqmethod"><title>Require method</title>

<p>The <code>method</code> provider allows to use the HTTP method in

authorization decisions. The GET and HEAD methods are treated as

equivalent. The TRACE method is not available to this provider,

use <directive module="core">TraceEnable</directive> instead.</p>

<p>The following examples will only allow GET, HEAD, POST, and OPTIONS

requests:</p>

<example>

Require method GET POST OPTIONS<br />

</example>

<p>The following examples will allow GET, HEAD, POST, and OPTIONS

requests without authentication, and require a valid user for all other

methods:</p>

<example>

&lt;RequireAny&gt;<br />

Require method GET POST OPTIONS<br />

Require valid-user<br />

&lt;/RequireAny&gt;<br />

</example>

</section>

</section>

</modulesynopsis>