X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman5%2Fslapd.access.5;h=0b11805952ad1cf409ad4c948f1b93c538198aec;hb=e1a5177baca44d6ff5dceea3f6f91da329d43b85;hp=04d1d1e1b61b3fa5c67982a6dc6aa16ad8cb957c;hpb=fbbb8a5d93eb1942668f1d271837e0fa72c53c21;p=openldap

diff --git a/doc/man/man5/slapd.access.5 b/doc/man/man5/slapd.access.5
index 04d1d1e1b6..0b11805952 100644
--- a/doc/man/man5/slapd.access.5
+++ b/doc/man/man5/slapd.access.5
@@ -1,6 +1,7 @@
 .TH SLAPD.ACCESS 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2006 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 1998-2011 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
+.\" $OpenLDAP$
 .SH NAME
 slapd.access \- access configuration for slapd, the stand-alone LDAP daemon
 .SH SYNOPSIS
@@ -10,9 +11,7 @@ The
 .BR slapd.conf (5)
 file contains configuration information for the
 .BR slapd (8)
-daemon. This configuration file is also used by the
-.BR slurpd (8)
-replication daemon and by the SLAPD tools
+daemon. This configuration file is also used by the SLAPD tools
 .BR slapacl (8),
 .BR slapadd (8),
 .BR slapauth (8),
@@ -55,11 +54,18 @@ are then used.
 If no access controls are present, the default policy
 allows anyone and everyone to read anything but restricts
 updates to rootdn.  (e.g., "access to * by * read").
-The rootdn can always read and write EVERYTHING!
+.LP
+When dealing with an access list, because the global access list is 
+effectively appended to each per-database list, if the resulting 
+list is non-empty then the access list will end with an implicit 
+.B access to * by * none
+directive. If there are no access directives applicable to a backend, 
+then a default read is used.
+.LP
+.B Be warned: the rootdn can always read and write EVERYTHING!
 .LP
 For entries not held in any backend (such as a root DSE), the
-directives of the first backend (and any global directives) are
-used.
+global directives are used.
 .LP
 Arguments that should be replaced by actual text are shown in
 brackets <>.
@@ -124,7 +130,7 @@ specifies the entity the access control directive applies to.
 It can have the forms
 .LP
 .nf
-	[dn[.<dnstyle>]=]<dnpattern>
+	dn[.<dnstyle>]=<dnpattern>
 	filter=<ldapfilter>
 	attrs=<attrlist>[ val[/matchingRule][.<attrstyle>]=<attrval>]
 .fi
@@ -142,9 +148,6 @@ with
 The statement
 .B dn=<dnpattern>
 selects the entries based on their naming context.
-The 
-.B dn=
-part is optional.
 The
 .B <dnpattern>
 is a string representation of the entry's DN.
@@ -156,11 +159,7 @@ form is given.
 .LP
 The 
 .B <dnstyle> 
-is also optional; however, it is recommended to specify both the 
-.B dn=
-and the
-.B <dnstyle>
-to avoid ambiguities.
+is optional; however, it is recommended to specify it to avoid ambiguities.
 .B Base 
 (synonym of
 .BR baseObject ),
@@ -197,11 +196,11 @@ as detailed in
 and/or
 .BR re_format (7),
 matching a normalized string representation of the entry's DN.
-The regex form of the pattern does not (yet) support UTF\-8.
+The regex form of the pattern does not (yet) support UTF-8.
 .LP
 The statement
 .B filter=<ldapfilter>
-selects the entries based on a valid LDAP filter as described in RFC 2254.
+selects the entries based on a valid LDAP filter as described in RFC 4515.
 A filter of
 .B (objectClass=*)
 is implied if no
@@ -258,6 +257,24 @@ resulting in base, onelevel, subtree or children match, respectively.
 The dn, filter, and attrs statements are additive; they can be used in sequence 
 to select entities the access rule applies to based on naming context,
 value and attribute type simultaneously.
+Submatches resulting from
+.B regex
+matching can be dereferenced in the
+.B <who>
+field using the syntax
+.IR ${v<n>} ,
+where
+.I <n>
+is the submatch number.
+The default syntax,
+.IR $<n> ,
+is actually an alias for
+.IR ${d<n>} ,
+that corresponds to dereferencing submatches from the
+.B dnpattern
+portion of the
+.B <what>
+field.
 .SH THE <WHO> FIELD
 The field
 .B <who>
@@ -309,9 +326,9 @@ with
 	<dnstyle>={{exact|base(object)}|regex
 		|one(level)|sub(tree)|children|level{<n>}}
 	<groupstyle>={exact|expand}
-	<peernamestyle>={<style>|ip|path}
+	<peernamestyle>={<style>|ip|ipv6|path}
 	<domainstyle>={exact|regex|sub(tree)}
-	<setstyle>={exact|regex}
+	<setstyle>={exact|expand}
 	<modifier>={expand}
 	<name>=aci		<pattern>=<attrname>]
 .fi
@@ -377,6 +394,10 @@ ranging from 0 to 9 (where 0 matches the entire string),
 or the form
 .BR ${<digit>+} ,
 for submatches higher than 9.
+Substring substitution from attribute value can
+be done in 
+using the form
+.BR ${v<digit>+} .
 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.
@@ -540,7 +561,10 @@ The statements
 and
 .BR sockurl=<sockurl>
 mean that the contacting host IP (in the form 
-.BR "IP=<ip>:<port>" )
+.BR "IP=<ip>:<port>"
+for IPv4, or
+.BR "IP=[<ipv6>]:<port>"
+for IPv6)
 or the contacting host named pipe file name (in the form
 .B "PATH=<path>"
 if connecting through a named pipe) for
@@ -589,6 +613,9 @@ and
 are dotted digit representations of the IP and the mask, while
 .BR <n> ,
 delimited by curly brackets, is an optional port.
+The same applies to IPv6 addresses when the special
+.B ipv6
+style is used.
 When checking access privileges, the IP portion of the
 .BR peername 
 is extracted, eliminating the
@@ -598,10 +625,13 @@ prefix and the
 part, and it is compared against the
 .B <ip>
 portion of the pattern after masking with
-.BR <mask> .
+.BR <mask> :
+\fI((peername & <mask>) == <ip>)\fP.
 As an example, 
 .B peername.ip=127.0.0.1
-allows connections only from localhost,
+and
+.B peername.ipv6=::1
+allow 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}
@@ -709,8 +739,8 @@ field will have.
 Its component are defined as
 .LP
 .nf
-	<level> ::= none|disclose|auth|compare|search|read|write|manage
-	<priv> ::= {=|+|-}{m|w|r|s|c|x|d|0}+
+	<level> ::= none|disclose|auth|compare|search|read|{write|add|delete}|manage
+	<priv> ::= {=|+|\-}{0|d|x|c|s|r|{w|a|z}|m}+
 .fi
 .LP
 The modifier
@@ -727,7 +757,8 @@ modifier.
 An example is the
 .B selfwrite
 access to the member attribute of a group, which allows one to add/delete
-its own DN from the member list of a group, without affecting other members.
+its own DN from the member list of a group, while being not allowed
+to affect other members.
 .LP
 The 
 .B level 
@@ -740,11 +771,22 @@ The possible levels are
 .BR compare ,
 .BR search ,
 .BR read ,
+.BR write ,
 and
-.BR write .
+.BR manage .
 Each access level implies all the preceding ones, thus 
 .B manage
-grants all access including administrative access,
+grants all access including administrative access.
+The 
+.BR write
+access is actually the combination of
+.BR add
+and
+.BR delete ,
+which respectively restrict the write privilege to add or delete
+the specified
+.BR <what> .
+
 .LP
 The
 .B none 
@@ -774,13 +816,17 @@ access privileges will be only those defined by the clause.
 The 
 .B +
 and
-.B -
+.B \-
 signs add/remove access privileges to the existing ones.
 The privileges are
 .B m
 for manage,
 .B w
 for write,
+.B a
+for add,
+.B z
+for delete,
 .B r
 for read,
 .B s 
@@ -794,6 +840,10 @@ for disclose.
 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).
+Note that
+.B +az
+is equivalent to
+.BR +w .
 .LP
 If no access is given, it defaults to 
 .BR +0 .
@@ -867,23 +917,39 @@ as the first access rule.
 As a consequence, unless the operation is performed with the 
 .B updatedn
 identity, control is passed straight to the subsequent rules.
+
 .SH OPERATION REQUIREMENTS
 Operations require different privileges on different portions of entries.
 The following summary applies to primary database backends such as
 the BDB and HDB backends.   Requirements for other backends may
 (and often do) differ.
+
 .LP
 The
 .B add
 operation requires
-.B write (=w)
+.B add (=a)
 privileges on the pseudo-attribute 
 .B entry
 of the entry being added, and 
-.B write (=w)
+.B add (=a)
 privileges on the pseudo-attribute
 .B children
 of the entry's parent.
+When adding the suffix entry of a database,
+.B add
+access to
+.B children
+of the empty DN ("") is required. Also if
+Add content ACL checking has been configured on
+the database (see the
+.BR slapd.conf (5)
+or
+.BR slapd\-config (5)
+manual page),
+.B add (=a)
+will be required on all of the attributes being added.
+
 .LP
 The 
 .B bind
@@ -891,30 +957,46 @@ operation, when credentials are stored in the directory, requires
 .B auth (=x)
 privileges on the attribute the credentials are stored in (usually
 .BR userPassword ).
+
 .LP
 The
 .B compare
 operation requires 
 .B compare (=c)
 privileges on the attribute that is being compared.
+
 .LP
 The
 .B delete
 operation requires
-.B write (=w)
+.B delete (=z)
 privileges on the pseudo-attribute
 .B entry 
 of the entry being deleted, and
-.B write (=w)
+.B delete (=d)
 privileges on the
 .B children
 pseudo-attribute of the entry's parent.
+
 .LP
 The
 .B modify
 operation requires 
 .B write (=w)
 privileges on the attributes being modified.
+In detail, 
+.B add (=a)
+is required to add new values,
+.B delete (=z)
+is required to delete existing values,
+and both
+.B delete
+and
+.BR "add (=az)" ,
+or
+.BR "write (=w)" ,
+are required to replace existing values.
+
 .LP
 The
 .B modrdn
@@ -923,17 +1005,22 @@ operation requires
 privileges on the pseudo-attribute
 .B entry
 of the entry whose relative DN is being modified,
-.B write (=w)
+.B delete (=z)
 privileges on the pseudo-attribute
 .B children
-of the old and new entry's parents, and
-.B write (=w)
+of the old entry's parents,
+.B add (=a)
+privileges on the pseudo-attribute
+.B children
+of the new entry's parents, and
+.B add (=a)
 privileges on the attributes that are present in the new relative DN.
-.B Write (=w)
+.B Delete (=z)
 privileges are also required on the attributes that are present 
 in the old relative DN if 
 .B deleteoldrdn
 is set to 1.
+
 .LP
 The
 .B search
@@ -941,7 +1028,8 @@ operation, requires
 .B search (=s)
 privileges on the 
 .B entry
-pseudo-attribute of the searchBase (NOTE: this was introduced with 2.3).
+pseudo-attribute of the searchBase
+(NOTE: this was introduced with OpenLDAP 2.4).
 Then, for each entry, it requires
 .B search (=s)
 privileges on the attributes that are defined in the filter.
@@ -966,6 +1054,7 @@ access to the attribute holding the referral information
 (generally the
 .B ref
 attribute).
+
 .LP
 Some internal operations and some
 .B controls
@@ -986,18 +1075,22 @@ privileges are also required on the
 attribute of the authorizing identity and/or on the 
 .B authzFrom
 attribute of the authorized identity.
+In general, when an internal lookup is performed for authentication
+or authorization purposes, search-specific privileges (see the access
+requirements for the search operation illustrated above) are relaxed to
+.BR auth .
 
 .LP
 Access control to search entries is checked by the frontend,
 so it is fully honored by all backends; for all other operations
 and for the discovery phase of the search operation,
 full ACL semantics is only supported by the primary backends, i.e.
-.BR back-bdb (5),
+.BR back\-bdb (5),
 and
-.BR back-hdb (5).
+.BR back\-hdb (5).
 
 Some other backend, like
-.BR back-sql (5),
+.BR back\-sql (5),
 may fully support them; others may only support a portion of the 
 described semantics, or even differ in some aspects.
 The relevant details are described in the backend-specific man pages.
@@ -1080,14 +1173,11 @@ ETCDIR/slapd.conf
 default slapd configuration file
 .SH SEE ALSO
 .BR slapd (8),
-.BR slapd-* (5),
+.BR slapd\-* (5),
 .BR slapacl (8),
 .BR regex (7),
 .BR re_format (7)
 .LP
 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
 .SH ACKNOWLEDGEMENTS
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
+.so ../Project