ITS#2906: report invalid userPassword schemes, clarify documentation

[openldap] / doc / man / man5 / slapd.access.5

diff --git a/doc/man/man5/slapd.access.5 b/doc/man/man5/slapd.access.5
index e1496e29f2286008d7ec13213639b3665008b374..f109d6d1db6b4a0ef501d8fd396f72fd31416779 100644 (file)
--- a/doc/man/man5/slapd.access.5
+++ b/doc/man/man5/slapd.access.5
@@ -1,5 +1,5 @@
 .TH SLAPD.ACCESS 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2003 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 1998-2004 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
 .SH NAME
 slapd.access \- access configuration for slapd, the stand-alone LDAP daemon
@@ -91,11 +91,15 @@ or
 .B exact 
 (an alias of 
 .BR base )
-indicates the entry whose DN is equal to the pattern.
+indicates the entry whose DN is equal to the pattern;
 .B one
+(synonym of
+.BR onelevel )
 indicates all the entries immediately below the
 .BR pattern ,
-.B subtree
+.B sub
+(synonym of
+.BR subtree )
 indicates all entries in the subtree at the pattern,
 .B children
 indicates all the entries below (subordinate to) the pattern.
@@ -127,13 +131,8 @@ are required and/or allowed by that objectClass.
 Actually, names in 
 .B <attrlist>
 that are prefixed by
-.B +
-are directly treated as objectClass names, while names that 
-do not correspond to an attribute type are also searched 
-in the objectclass set.
-This latter behavior is deprecated and might not be supported
-in future releases.
-A name prefixed by
+.B @
+are directly treated as objectClass names.  A name prefixed by
 .B !
 is also treated as an objectClass, but in this case the access rule
 affects the attributes that are not required nor allowed 
@@ -379,7 +378,7 @@ Its component are defined as
 .LP
 .nf
        <level> ::= none|auth|compare|search|read|write
-       <priv> ::= {=|+|-}{w|r|s|c|x}+
+       <priv> ::= {=|+|-}{w|r|s|c|x|0}+
 .fi
 .LP
 The modifier
@@ -443,7 +442,9 @@ for search,
 for compare, and
 .B x
 for authentication.
-More than one privilege can be added in one statement.
+More than one of the above privileges can be added in one statement.
+.B 0
+indicates no privileges and is used only by itself (e.g., +0).
 .LP
 The optional field
 .B <control>
@@ -589,10 +590,28 @@ access to the attribute holding the referral information
 (generally the
 .B ref
 attribute).
+.LP
+Some
+.B controls
+require specific access privileges.
+The
+.B proxyAuthz
+control requires
+.B auth (=x)
+privileges on all the attributes that are present in the search filter
+of the URI regexp maps (the right-hand side of the
+.B sasl-regexp
+directives).
+It also requires
+.B auth (=x)
+privileges on the
+.B saslAuthzTo
+attribute of the authorizing identity and/or on the 
+.B saslAuthzFrom
+attribute of the authorized identity.
 .SH CAVEATS
 It is strongly recommended to explicitly use the most appropriate
-DN 
-.BR style ,
+.BR <dnstyle> ,
 to avoid possible incorrect specifications of the access rules as well
 as for performance (avoid unrequired regex matching when an exact
 match suffices) reasons.
@@ -624,6 +643,40 @@ For performance reasons, it would be better to use the subtree style.
                by ...
 .fi
 .LP
+When writing submatch rules, it may be convenient to avoid unnecessary
+.B regex
+.B <dnstyle>
+use; for instance, to allow access to the subtree of the user 
+that matches the
+.B what
+clause, one could use
+.LP
+.nf
+       access to dn.regex="^(.+,)?uid=([^,]+),dc=example,dc=com$$"
+               by dn.regex="^uid=$1,dc=example,dc=com$$" write
+               by ...
+.fi
+.LP
+However, since all that is required in the 
+.B to
+clause is substring expansion, a more efficient solution is
+.LP
+.nf
+       access to dn.regex="^(.+,)?uid=([^,]+),dc=example,dc=com$$"
+               by dn.exact,expand="uid=$1,dc=example,dc=com" write
+               by ...
+.fi
+.LP
+In fact, while a
+.B <dnstyle>
+of
+.B regex
+implies substring expansion, 
+.BR exact ,
+as well as all the other DN specific
+.B <dnstyle>
+values, does not, so it must be explicitly requested.
+.LP
 .SH FILES
 .TP
 ETCDIR/slapd.conf