X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman5%2Fslapd.access.5;h=763e449edf8e296800d99915b4d62b616403e40f;hb=44e8ffd4fee407b54988b6da6c95554c75500147;hp=8e48197957a7501d67d124806d0fbab519dc7a21;hpb=947f41832ee6f0cd925560ebbe7c67daf8a4fa87;p=openldap

diff --git a/doc/man/man5/slapd.access.5 b/doc/man/man5/slapd.access.5
index 8e48197957..763e449edf 100644
--- 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
@@ -13,10 +13,14 @@ file contains configuration information for the
 daemon. This configuration file is also used by the
 .BR slurpd (8)
 replication daemon and by the SLAPD tools
+.BR slapacl (8),
 .BR slapadd (8),
+.BR slapauth (8),
 .BR slapcat (8),
+.BR slapdn (8),
+.BR slapindex (8),
 and
-.BR slapindex (8).
+.BR slaptest (8).
 .LP
 The
 .B slapd.conf
@@ -91,11 +95,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 +135,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 
@@ -185,12 +188,12 @@ It can have the forms
 	dn[.<dnstyle>[,<modifier>]]=<DN>
 	dnattr=<attrname>
 	group[/<objectclass>[/<attrname>]]
-		[.<style>]=<group>
-	peername[.<style>]=<peername>
+		[.<groupstyle>]=<group>
+	peername[.<peernamestyle>]=<peername>
 	sockname[.<style>]=<sockname>
 	domain[.<domainstyle>[,<modifier>]]=<domain>
 	sockurl[.<style>]=<sockurl>
-	set[.<style>]=<pattern>
+	set[.<setstyle>]=<pattern>
 
 	ssf=<n>
 	transport_ssf=<n>
@@ -200,6 +203,18 @@ It can have the forms
 	aci=<attrname>
 .fi
 .LP
+with
+.LP
+.nf
+	<dnstyle>={{exact|base}|regex|sub(tree)|one(level)|children}
+	<groupstyle>={exact|expand}
+	<style>={exact|regex|expand}
+	<peernamestyle>={<style>|ip|path}
+	<domainstyle>={exact|regex|sub(tree)}
+	<setstyle>={exact|regex}
+	<modifier>={expand}
+.fi
+.LP
 They may be specified in combination.
 .LP
 .nf
@@ -241,6 +256,15 @@ dn.regex clause by using the form
 with 
 .B digit
 ranging from 1 to 9.
+Since the dollar character is used to indicate a substring replacement,
+the dollar character that is used to indicate match up to the end of
+the string must be escaped by a second dollar character, e.g.
+.LP
+.nf
+    access to dn.regex="^(.+,)?uid=([^,]+),dc=[^,]+,dc=com$"
+        by dn.regex="^uid=$2,dc=[^,]+,dc=com$$" write
+.fi
+.LP
 The style qualifier
 allows an optional
 .BR modifier .
@@ -251,6 +275,39 @@ even if
 .B dnstyle
 is not 
 .BR regex .
+Note that the 
+.I regex 
+dnstyle in the above example may be of use only if the 
+.B by
+clause needs to be a regex; otherwise, if the
+value of the second (from the right)
+.I dc=
+portion of the DN in the above example were fixed, the form
+.LP
+.nf
+    access to dn.regex="^(.+,)?uid=([^,]+),dc=example,dc=com$"
+        by dn.exact,expand="uid=$2,dc=example,dc=com" write
+.fi
+.LP
+could be used; if it had to match the value in the 
+.B what
+clause, the form
+.LP
+.nf
+    access to dn.regex="^(.+,)?uid=([^,]+),dc=([^,]+),dc=com$"
+        by dn.exact,expand="uid=$2,dc=$3,dc=com" write
+.fi
+.LP
+could be used.
+.LP
+It is perfectly useless to give any access privileges to a DN 
+that exactly matches the
+.B rootdn
+of the database the ACLs apply to, because it implicitly
+possesses write privileges for the entire tree of that database.
+Actually, access control is bypassed for the
+.BR rootdn ,
+to solve the intrinsic chicken-and-egg problem.
 .LP
 The statement
 .B dnattr=<attrname>
@@ -272,16 +329,12 @@ define the objectClass and the member attributeType of the group entry.
 The optional style qualifier
 .B <style>
 can be
-.BR regex ,
+.BR expand ,
 which means that
 .B <group>
 will be expanded as a replacement string (but not as a regular expression)
 according to regex (7), and
-.B base
-or
-.B exact
-(an alias of
-.BR base ),
+.BR exact ,
 which means that exact match will be used.
 .LP
 For static groups, the specified attributeType must have
@@ -293,7 +346,7 @@ be a subtype of the
 .B labeledURI
 attributeType. Only LDAP URIs of the form
 .B ldap:///<base>??<scope>?<filter>
-will be evaluated in a dynamic group.
+will be evaluated in a dynamic group, by searching the local server only.
 .LP
 The statements
 .BR peername=<peername> ,
@@ -301,7 +354,11 @@ The statements
 .BR domain=<domain> ,
 and
 .BR sockurl=<sockurl>
-mean that the contacting host IP for
+mean that the contacting host IP (in the form 
+.BR "IP=<ip>:<port>" )
+or the contacting host named pipe file name (in the form
+.B "PATH=<path>"
+if connecting through a named pipe) for
 .BR peername ,
 the named pipe file name for
 .BR sockname ,
@@ -316,7 +373,65 @@ The same
 .B style
 rules for pattern match described for the
 .B group
-case apply. 
+case apply, plus the
+.B regex
+style, which implies submatch
+.B expand
+and
+.BR regex (7)
+match of the corresponding connection parameters.
+The
+.B exact
+style of the
+.BR peername
+clause (the default) implies a case-exact match on the client's
+.BR IP , 
+including the
+.B "IP="
+prefix and the trailing
+.BR ":<port>" , 
+or the client's 
+.BR path ,
+including the
+.B "PATH="
+prefix if connecting through a named pipe.
+The special
+.B ip
+style interprets the pattern as 
+.BR <peername>=<ip>[%<mask>][{<n>}] ,
+where
+.B <ip>
+and 
+.B <mask>
+are dotted digit representations of the IP and the mask, while
+.BR <n> ,
+delimited by curly brackets, is an optional port.
+When checking access privileges, the IP portion of the
+.BR peername 
+is extracted, eliminating the
+.B "IP="
+prefix and the
+.B ":<port>"
+part, and it is compared against the
+.B <ip>
+portion of the pattern after masking with
+.BR <mask> .
+As an example, 
+.B peername.ip=127.0.0.1
+alows connections only from localhost,
+.B peername.ip=192.168.1.0%255.255.255.0 
+allows connections from any IP in the 192.168.1 class C domain, and
+.B peername.ip=192.168.1.16%255.255.255.240{9009}
+allows connections from any IP in the 192.168.1.[16-31] range 
+of the same domain, only if port 9009 is used.
+The special 
+.B path
+style eliminates the 
+.B "PATH="
+prefix from the 
+.B peername
+when connecting through a named pipe, and performs an exact match 
+on the given pattern.
 The
 .BR domain 
 clause also allows the
@@ -328,6 +443,16 @@ pattern, or its trailing part, after a
 exactly matches the 
 .BR domain
 pattern.
+The 
+.B expand
+style is allowed, implying an
+.B exact 
+match with submatch expansion; the use of 
+.B expand 
+as a style modifier is considered more appropriate.
+As an example,
+.B domain.subtree=example.com
+will match www.example.com, but will not match www.anotherexample.com.
 The
 .B domain
 of the contacting host is determined by performing a DNS reverse lookup.
@@ -379,7 +504,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 +568,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,14 +716,38 @@ access to the attribute holding the referral information
 (generally the
 .B ref
 attribute).
+.LP
+Some internal operations and some
+.B controls
+require specific access privileges.
+The
+.B authzID
+mapping and the 
+.B proxyAuthz
+control require
+.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 authz-regexp
+directives).
+.B Auth (=x)
+privileges are also required on the
+.B authzTo
+attribute of the authorizing identity and/or on the 
+.B authzFrom
+attribute of the authorized identity.
 .SH CAVEATS
 It is strongly recommended to explicitly use the most appropriate
-.BR <dnstyle> ,
-to avoid possible incorrect specifications of the access rules as well
-as for performance (avoid unrequired regex matching when an exact
+.B <dnstyle>
+in
+.B <what>
+and
+.B <who>
+clauses, to avoid possible incorrect specifications of the access rules 
+as well as for performance (avoid unrequired regex matching when an exact
 match suffices) reasons.
 .LP
-An adminisistrator might create a rule of the form:
+An administrator might create a rule of the form:
 .LP
 .nf
 	access to dn.regex="dc=example,dc=com"
@@ -612,7 +763,7 @@ To match the desired subtree, the rule would be more precisely
 written:
 .LP
 .nf
-	access to dn.regex="^(.+,)?dc=example,dc=com$$"
+	access to dn.regex="^(.+,)?dc=example,dc=com$"
 		by ...
 .fi
 .LP
@@ -632,17 +783,17 @@ that matches the
 clause, one could use
 .LP
 .nf
-	access to dn.regex="^(.+,)?uid=([^,]+),dc=example,dc=com$$"
+	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
+.B by
 clause is substring expansion, a more efficient solution is
 .LP
 .nf
-	access to dn.regex="^(.+,)?uid=([^,]+),dc=example,dc=com$$"
+	access to dn.regex="^(.+,)?uid=([^,]+),dc=example,dc=com$"
 		by dn.exact,expand="uid=$1,dc=example,dc=com" write
 		by ...
 .fi
@@ -663,6 +814,7 @@ ETCDIR/slapd.conf
 default slapd configuration file
 .SH SEE ALSO
 .BR slapd (8),
+.BR slapacl (8),
 .LP
 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
 .SH ACKNOWLEDGEMENTS