You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by ch...@apache.org on 2008/12/19 20:57:02 UTC
svn commit: r728126 - in /httpd/httpd/trunk/docs/manual: howto/auth.xml
mod/mod_authz_core.xml new_features_2_4.xml
Author: chrisd
Date: Fri Dec 19 11:57:02 2008
New Revision: 728126
URL: http://svn.apache.org/viewvc?rev=728126&view=rev
Log:
Documentation revisions for r726082.
Modified:
httpd/httpd/trunk/docs/manual/howto/auth.xml
httpd/httpd/trunk/docs/manual/mod/mod_authz_core.xml
httpd/httpd/trunk/docs/manual/new_features_2_4.xml
Modified: httpd/httpd/trunk/docs/manual/howto/auth.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/howto/auth.xml?rev=728126&r1=728125&r2=728126&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/howto/auth.xml (original)
+++ httpd/httpd/trunk/docs/manual/howto/auth.xml Fri Dec 19 11:57:02 2008
@@ -430,8 +430,9 @@
<p>To take authorization a little further, authorization container
directives such as
- <directive module="mod_authz_core" type="section">MatchAll</directive> and
- <directive module="mod_authz_core" type="section">MatchAny</directive>
+ <directive module="mod_authz_core" type="section">RequireAll</directive>
+ and
+ <directive module="mod_authz_core" type="section">RequireAny</directive>
allow logic to be applied so that the order in which authorization
is handled can be completely controled through the configuration.
See <a href="../mod/mod_authz_core.html#logic">Authorization
@@ -454,20 +455,18 @@
configured and called in a specific order which didn't depend on the
load order of the auth module itself. This same provider based mechanism
has been brought forward into authorization as well. What this means is
- that the <directive module="mod_authz_core">Require</directive> and
- <directive module="mod_authz_core">Match</directive> directives
- not only specify which authorization methods should be used, they also
+ that the <directive module="mod_authz_core">Require</directive> directive
+ not only specifies which authorization methods should be used, it also
specifies the order in which they are called. Multiple authorization
- methods are called in the same order in which the
- <directive module="mod_authz_core">Require</directive>
- or <directive module="mod_authz_core">Match</directive> directives
+ methods are called in the same order in which the
+ <directive module="mod_authz_core">Require</directive> directives
appear in the configuration.</p>
<p>With the introduction of authorization container directives
such as
- <directive module="mod_authz_core" type="section">MatchAll</directive>
+ <directive module="mod_authz_core" type="section">RequireAll</directive>
and
- <directive module="mod_authz_core" type="section">MatchAny</directive>,
+ <directive module="mod_authz_core" type="section">RequireAny</directive>,
the configuration also has control over when the
authorization methods are called and what criteria determines when
access is granted. See
@@ -478,25 +477,11 @@
<p>By default all
<directive module="mod_authz_core">Require</directive>
directives are handled as though contained within a
- <directive module="mod_authz_core" type="section">MatchAny</directive>
+ <directive module="mod_authz_core" type="section">RequireAny</directive>
container directive. In other words, if
any of the specified authorization methods succeed, then authorization
is granted.</p>
- <p>In contrast, by default all
- <directive module="mod_authz_core">Match</directive> directives
- are handled as though contained within a
- <directive module="mod_authz_core" type="section">MatchAll</directive>
- container directive (unless they are explicitly contained within
- a different authorization container directive).
- This permits
- <directive module="mod_authz_core">Match</directive> directives
- to be usefully mixed with negated
- <code>Match not</code> directives. To authorize the request,
- none of the negated directives can match their parameters,
- while all of the positive directives must match their
- parameters (or else return a neutral result).</p>
-
</section>
<section id="reqaccessctrl"><title>Using authorization providers for access control</title>
@@ -514,9 +499,8 @@
a document.</p>
<p>The usage of these providers is specified through the
- <directive module="mod_authz_core">Require</directive> and
- <directive module="mod_authz_core">Match</directive> directives.
- These directives register the authorization providers
+ <directive module="mod_authz_core">Require</directive> directive.
+ This directive registers the authorization providers
that will be called during the authorization stage of the request
processing. For example:</p>
@@ -540,7 +524,12 @@
following:</p>
<example>
- Match not ip 10.252.46.165
+ <RequireAll>
+ <indent>
+ Require all granted<br/>
+ Require not ip 10.252.46.165
+ </indent>
+ </RequireAll>
</example>
<p>Visitors coming from that address will not be able to see
@@ -548,33 +537,38 @@
machine name, rather than an IP address, you can use that.</p>
<example>
- Match not host <var>host.example.com</var>
+ <RequireAll>
+ <indent>
+ Require all granted<br/>
+ Require not host <var>host.example.com</var>
+ </indent>
+ </RequireAll>
</example>
<p>And, if you'd like to block access from an entire domain,
you can specify just part of an address or domain name:</p>
<example>
- Match all granted<br />
- <MatchNotAny>
+ <RequireAll>
<indent>
- Match ip 192.168.205<br />
- Match host phishers.example.com moreidiots.example<br />
- Match host ke
+ Require all granted<br/>
+ <RequireNone>
+ <indent>
+ Require ip 192.168.205<br />
+ Require host phishers.example.com moreidiots.example<br />
+ Require host ke
+ </indent>
+ </RequireNone>
</indent>
- </MatchNotAny>
+ </RequireAll>
</example>
<p>The above example uses the <directive module="mod_authz_core"
- type="section">MatchNotAny</directive> container directive
+ type="section">RequireNone</directive> directive
to make sure that none of the
- <directive module="mod_authz_core">Match</directive> directives
- match their parameters before granting access. Note that
- the <code>Match all granted</code> directive and the
- <directive module="mod_authz_core"
- type="section">MatchNotAny</directive> are implicitly contained
- within a <directive module="mod_authz_core"
- type="section">MatchAll</directive> directive.</p>
+ <directive module="mod_authz_core">Require</directive> directives
+ contained within it
+ match their parameters before granting access.</p>
</section>
Modified: httpd/httpd/trunk/docs/manual/mod/mod_authz_core.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_authz_core.xml?rev=728126&r1=728125&r2=728126&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_authz_core.xml (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_authz_core.xml Fri Dec 19 11:57:02 2008
@@ -45,8 +45,7 @@
<p>Extended authorization providers can be created within the configuration
file and assigned an alias name. The alias providers can then be referenced
- through the <directive module="mod_authz_core">Require</directive> and
- <directive module="mod_authz_core">Match</directive> directives
+ through the <directive module="mod_authz_core">Require</directive> directive
in the same way as a base authorization provider. Besides the ability to
create and alias an extended provider, it also allows the same extended
authorization provider to be reference by multiple locations.
@@ -99,13 +98,12 @@
<section id="logic"><title>Authorization Containers</title>
<p>The authorization container directives
- <directive module="mod_authz_core" type="section">MatchAll</directive>,
- <directive module="mod_authz_core" type="section">MatchAny</directive>,
- <directive module="mod_authz_core" type="section">MatchNotAll</directive>
+ <directive module="mod_authz_core" type="section">RequireAll</directive>,
+ <directive module="mod_authz_core" type="section">RequireAny</directive>
and
- <directive module="mod_authz_core" type="section">MatchNotAny</directive>
+ <directive module="mod_authz_core" type="section">RequireNone</directive>
may be combined with each other and with the
- <directive module="mod_authz_core">Match</directive>
+ <directive module="mod_authz_core">Require</directive>
directive to express complex authorization logic.</p>
<p>The example below expresses the following authorization logic.
@@ -121,29 +119,33 @@
<example>
<Directory /www/mydocs>
<indent>
- <MatchAny>
+ <RequireAll>
<indent>
- Match user superadmin<br />
- <MatchAll>
+ <RequireAny>
<indent>
- Match group admins<br />
- Match ldap-group cn=Administrators,o=Airius<br />
- <MatchAny>
+ Require user superadmin<br />
+ <RequireAll>
<indent>
- Match group sales<br />
- Match ldap-attribute dept="sales"
+ Require group admins<br />
+ Require ldap-group cn=Administrators,o=Airius<br />
+ <RequireAny>
+ <indent>
+ Require group sales<br />
+ Require ldap-attribute dept="sales"
+ </indent>
+ </RequireAny>
</indent>
- </MatchAny>
+ </RequireAll>
</indent>
- </MatchAll>
- </indent>
- </MatchAny><br />
- <MatchNotAny>
- <indent>
- Match group temps<br />
- Match ldap-group cn=Temporary Employees,o=Airius
+ </RequireAny><br />
+ <RequireNone>
+ <indent>
+ Require group temps<br />
+ Require ldap-group cn=Temporary Employees,o=Airius
+ </indent>
+ </RequireNone>
</indent>
- </MatchNotAny>
+ </RequireAll>
</indent>
</Directory>
</example>
@@ -153,7 +155,8 @@
<name>Require</name>
<description>Tests whether an authenticated user is authorized by
an authorization provider.</description>
-<syntax>Require <var>entity-name</var> [<var>entity-name</var>] ...</syntax>
+<syntax>Require [not] <var>entity-name</var>
+ [<var>entity-name</var>] ...</syntax>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>
@@ -212,53 +215,12 @@
<directive module="core" type="section">Limit</directive>
section.</p>
- <p>When multiple <directive>Require</directive> directives are
- used in a single
- <a href="../sections.html#mergin">configuration section</a>,
- the first one to authorize a user authorizes the entire request,
- and subsequent <directive>Require</directive> directives are
- ignored. In other words, all <directive>Require</directive> directives
- are enclosed in an implied <directive module="mod_authz_core"
- type="section">MatchAny</directive> directive.</p>
-
- <note><directive>Require</directive> directives may not be combined
- with the <directive module="mod_authz_core">Match</directive> directive
- or any authorization container directives, such as
- <directive module="mod_authz_core"
- type="section">MatchAll</directive>.</note>
-</usage>
-
-<seealso><a href="../howto/auth.html">Authentication, Authorization,
- and Access Control</a></seealso>
-<seealso><module>mod_authn_core</module></seealso>
-<seealso><module>mod_authz_host</module></seealso>
-</directivesynopsis>
-
-<directivesynopsis>
-<name>Match</name>
-<description>Tests whether an authenticated user is authorized by
-an authorization provider.</description>
-<syntax>Match [not] <var>entity-name</var>
-[<var>entity-name</var>] ...</syntax>
-<contextlist><context>directory</context><context>.htaccess</context>
-</contextlist>
-<override>AuthConfig</override>
-
-<usage>
- <p>This directive is similar to the
- <directive module="mod_authz_core">Require</directive> directive;
- it tests whether an authenticated user is authorized according to
- a particular authorization provider and the specified restrictions.</p>
-
- <p>Unlike the <directive module="mod_authz_core">Require</directive>
- directive, it may be used with and inside authorization container
- directives such as
- <directive module="mod_authz_core" type="section">MatchAll</directive>.</p>
-
- <p>Furthermore, its result may be negated through the use of the
- <code>not</code> option. As with other negated authorization directives,
- in this case the <directive>Match</directive> directive may only
- either fail or return a neutral result, and can therefore never
+ <p>The result of the <directive>Require</directive> directive
+ may be negated through the use of the
+ <code>not</code> option. As with the other negated authorization
+ directive <directive type="section">RequireNone</directive>,
+ when the <directive>Require</directive> directive is negated it can
+ only fail or return a neutral result, and therefore may never
independently authorize a request.</p>
<p>In the following example, all users in the <code>alpha</code>
@@ -268,57 +230,57 @@
<example>
<Directory /www/docs>
<indent>
- Match group alpha beta<br />
- Match not group reject
+ <RequireAll>
+ <indent>
+ Require group alpha beta<br />
+ Require not group reject
+ </indent>
+ </RequireAll>
</indent>
</Directory>
</example>
- <p>When multiple <directive>Match</directive> directives are
+ <p>When multiple <directive>Require</directive> directives are
used in a single
<a href="../sections.html#mergin">configuration section</a>
and are not contained in another authorization directive like
- <directive module="mod_authz_core" type="section">MatchAny</directive>,
+ <directive module="mod_authz_core" type="section">RequireAll</directive>,
they are implicitly contained within a
- <directive module="mod_authz_core" type="section">MatchAll</directive>
- directive. Thus for the user to be authorized, all such
- <directive>Match</directive> directives must not fail, and
- at least one must be successful.</p>
-
- <note><directive>Match</directive> directives may not be combined
- with the <directive module="mod_authz_core">Require</directive>
- directive.</note>
+ <directive module="mod_authz_core" type="section">RequireAny</directive>
+ directive. Thus the first one to authorize a user authorizes the
+ entire request, and subsequent <directive>Require</directive> directives
+ are ignored.</p>
</usage>
-<seealso><directive module="mod_authz_core">Require</directive></seealso>
-<seealso><a href="#logic">Authorization Containers</a></seealso>
<seealso><a href="../howto/auth.html">Authentication, Authorization,
and Access Control</a></seealso>
+<seealso><a href="#logic">Authorization Containers</a></seealso>
+<seealso><module>mod_authn_core</module></seealso>
+<seealso><module>mod_authz_host</module></seealso>
</directivesynopsis>
<directivesynopsis type="section">
-<name>MatchAll</name>
+<name>RequireAll</name>
<description>Enclose a group of authorization directives of which none
must fail and at least one must succeed for the enclosing directive to
succeed.</description>
-<syntax><MatchAll>
-... </MatchAll></syntax>
+<syntax><RequireAll> ... </RequireAll></syntax>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>
<usage>
- <p><directive type="section">MatchAll</directive> and
- <code></MatchAll></code> are used to enclose a group of
+ <p><directive type="section">RequireAll</directive> and
+ <code></RequireAll></code> are used to enclose a group of
authorization directives of which none must fail and at least one
must succeed in order for
- the <directive type="section">MatchAll</directive> directive to
+ the <directive type="section">RequireAll</directive> directive to
succeed.</p>
<p>If none of the directives contained within the
- <directive type="section">MatchAll</directive> directive fails,
+ <directive type="section">RequireAll</directive> directive fails,
and at least one succeeds, then the
- <directive type="section">MatchAll</directive> directive
+ <directive type="section">RequireAll</directive> directive
succeeds. If none succeed and none fail, then it returns a
neutral result. In all other cases, it fails.</p>
</usage>
@@ -330,35 +292,34 @@
</directivesynopsis>
<directivesynopsis type="section">
-<name>MatchAny</name>
+<name>RequireAny</name>
<description>Enclose a group of authorization directives of which one
must succeed for the enclosing directive to succeed.</description>
-<syntax><MatchAny>
-... </MatchAny></syntax>
+<syntax><RequireAny> ... </RequireAny></syntax>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>
<usage>
- <p><directive type="section">MatchAny</directive> and
- <code></MatchAny></code> are used to enclose a group of
+ <p><directive type="section">RequireAny</directive> and
+ <code></RequireAny></code> are used to enclose a group of
authorization directives of which one must succeed in order for
- the <directive type="section">MatchAny</directive> directive to
+ the <directive type="section">RequireAny</directive> directive to
succeed.</p>
<p>If one or more of the directives contained within the
- <directive type="section">MatchAny</directive> directive succeed,
- then the <directive type="section">MatchAny</directive> directive
+ <directive type="section">RequireAny</directive> directive succeed,
+ then the <directive type="section">RequireAny</directive> directive
succeeds. If none succeed and none fail, then it returns a
neutral result. In all other cases, it fails.</p>
<note>Because negated authorization directives are unable to
return a successful result, they can not significantly influence
- the result of a <directive type="section">MatchAny</directive>
+ the result of a <directive type="section">RequireAny</directive>
directive. (At most they could cause the directive to fail in
the case where they failed and all other directives returned a
neutral value.) Therefore negated authorization directives
- are not permitted within a <directive type="section">MatchAny</directive>
+ are not permitted within a <directive type="section">RequireAny</directive>
directive.</note>
</usage>
@@ -369,74 +330,38 @@
</directivesynopsis>
<directivesynopsis type="section">
-<name>MatchNotAll</name>
-<description>Enclose a group of authorization directives of which some
-must fail or none must succeed for the enclosing directive to
-not fail.</description>
-<syntax><MatchNotAll>
-... </MatchNotAll></syntax>
-<contextlist><context>directory</context><context>.htaccess</context>
-</contextlist>
-<override>AuthConfig</override>
-
-<usage>
- <p><directive type="section">MatchNotAll</directive> and
- <code></MatchNotAll></code> are used to enclose a group of
- authorization directives of which some must fail or none must succeed
- in order for the
- <directive type="section">MatchNotAll</directive> directive to
- not fail.</p>
-
- <p>If none of the directives contained within the
- <directive type="section">MatchNotAll</directive> directive
- fail, and one or more succeed, then the
- <directive type="section">MatchNotAll</directive> directive fails.
- In all other cases, it returns a neutral result. Thus as with
- the other negated authorization directives, it can never independently
- authorize a request because it can never return a successful result.
- It can be used, however, to restrict the set of users who are
- authorized to access a resource.</p>
-</usage>
-
-<seealso><a href="#logic">Authorization Containers</a></seealso>
-<seealso><a href="../howto/auth.html">Authentication, Authorization,
- and Access Control</a></seealso>
-
-</directivesynopsis>
-
-<directivesynopsis type="section">
-<name>MatchNotAny</name>
+<name>RequireNone</name>
<description>Enclose a group of authorization directives of which none
-none must succeed for the enclosing directive to not fail.</description>
-<syntax><MatchNotAny>
-... </MatchNotAny></syntax>
+must succeed for the enclosing directive to not fail.</description>
+<syntax><RequireNone> ... </RequireNone></syntax>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>
<usage>
- <p><directive type="section">MatchNotAny</directive> and
- <code></MatchNotAny></code> are used to enclose a group of
+ <p><directive type="section">RequireNone</directive> and
+ <code></RequireNone></code> are used to enclose a group of
authorization directives of which none must succeed
in order for the
- <directive type="section">MatchNotAny</directive> directive to
+ <directive type="section">RequireNone</directive> directive to
not fail.</p>
<p>If one or more of the directives contained within the
- <directive type="section">MatchNotAny</directive> directive succeed,
- then the <directive type="section">MatchNotAny</directive> directive
+ <directive type="section">RequireNone</directive> directive succeed,
+ then the <directive type="section">RequireNone</directive> directive
fails. In all other cases, it returns a neutral result. Thus as with
- the other negated authorization directives, it can never independently
+ the other negated authorization directive <code>Require not</code>,
+ it can never independently
authorize a request because it can never return a successful result.
It can be used, however, to restrict the set of users who are
authorized to access a resource.</p>
<note>Because negated authorization directives are unable to
return a successful result, they can not significantly influence
- the result of a <directive type="section">MatchNotAny</directive>
+ the result of a <directive type="section">RequireNone</directive>
directive. Therefore negated authorization directives
are not permitted within a
- <directive type="section">MatchNotAny</directive> directive.</note>
+ <directive type="section">RequireNone</directive> directive.</note>
</usage>
<seealso><a href="#logic">Authorization Containers</a></seealso>
@@ -446,12 +371,12 @@
</directivesynopsis>
<directivesynopsis>
-<name>MergeAuthz</name>
+<name>AuthMerging</name>
<description>Controls the manner in which each configuration section's
authorization logic is combined with that of preceding configuration
sections.</description>
-<syntax>MergeAuthz Off | MatchAll | MatchAny</syntax>
-<default>MergeAuthz Off</default>
+<syntax>AuthMerging Off | And | Or</syntax>
+<default>AuthMerging Off</default>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>
@@ -461,31 +386,31 @@
subsequent <a href="../sections.html#mergin">configuration section</a>,
unless a different set of authorization directives are specified.
This is the default action, which corresponds to an explicit setting
- of <code>MergeAuthz Off</code>.</p>
+ of <code>AuthMerging Off</code>.</p>
<p>However, there may be circumstances in which is it desirable
for a configuration section's authorization to be combined with
that of its predecessor while configuration sections are being
- merged. Two options are available for this case, <code>MatchAll</code>
- and <code>MatchAny</code>.</p>
+ merged. Two options are available for this case, <code>And</code>
+ and <code>Or</code>.</p>
- <p>When a configuration section contains <code>AuthzMerge MatchAll</code>
- or <code>AuthzMerge MatchAny</code>,
+ <p>When a configuration section contains <code>AuthMerging And</code>
+ or <code>AuthMerging Or</code>,
its authorization logic is combined with that of the nearest
predecessor (according to the overall order of configuration sections)
which also contains authorization logic as if the two sections
were jointly contained within a
- <directive module="mod_authz_core" type="section">MatchAll</directive> or
- <directive module="mod_authz_core" type="section">MatchAny</directive>
+ <directive module="mod_authz_core" type="section">RequireAll</directive> or
+ <directive module="mod_authz_core" type="section">RequireAny</directive>
directive, respectively.</p>
- <note>The setting of <directive>AuthzMerge</directive> is not
+ <note>The setting of <directive>AuthMerging</directive> is not
inherited outside of the configuration section in which it appears.
In the following example, only users belonging to group <code>alpha</code>
may access <code>/www/docs</code>. Users belonging to either
groups <code>alpha</code> or <code>beta</code> may access
<code>/www/docs/ab</code>. However, the default <code>Off</code>
- setting of <directive>AuthzMerge</directive> applies to the
+ setting of <directive>AuthMerging</directive> applies to the
<directive type="section" module="core">Directory</directive>
configuration section for <code>/www/docs/ab/gamma</code>, so
that section's authorization directives override those of the
@@ -499,20 +424,20 @@
AuthName Documents<br />
AuthBasicProvider file<br />
AuthUserFile /usr/local/apache/passwd/passwords<br />
- Match group alpha
+ Require group alpha
</indent>
</Directory><br />
<br />
<Directory /www/docs/ab>
<indent>
- AuthzMerge MatchAny<br />
- Match group beta
+ AuthMerging Or<br />
+ Require group beta
</indent>
</Directory><br />
<br />
<Directory /www/docs/ab/gamma>
<indent>
- Match group gamma
+ Require group gamma
</indent>
</Directory>
</example>
Modified: httpd/httpd/trunk/docs/manual/new_features_2_4.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/new_features_2_4.xml?rev=728126&r1=728125&r2=728126&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/new_features_2_4.xml (original)
+++ httpd/httpd/trunk/docs/manual/new_features_2_4.xml Fri Dec 19 11:57:02 2008
@@ -75,10 +75,10 @@
<dt>Authorization Logic Containers</dt>
<dd>Advanced authorization logic may now be specified using the
- <directive module="mod_authz_core">Match</directive> directive
+ <directive module="mod_authz_core">Require</directive> directive
and the related container directives, such as
<directive module="mod_authz_core"
- type="section">MatchAll</directive>, all
+ type="section">RequireAll</directive>, all
provided by the <module>mod_authz_core</module> module.</dd>
</dl>
</section>