From: Howard Chu <hyc@openldap.org>
Date: Mon, 12 Dec 2022 11:50:43 +0000 (+0000)
Subject: ITS#9957 slapo-dynlist: more explicit config doc
X-Git-Tag: OPENLDAP_REL_ENG_2_5_14~24
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=211e789db823648c95cc3c538de42b05a684716e;p=thirdparty%2Fopenldap.git

ITS#9957 slapo-dynlist: more explicit config doc
---

diff --git a/doc/man/man5/slapo-dynlist.5 b/doc/man/man5/slapo-dynlist.5
index eb1bb35c7f..49a3d505d4 100644
--- a/doc/man/man5/slapo-dynlist.5
+++ b/doc/man/man5/slapo-dynlist.5
@@ -11,21 +11,26 @@ The
 .B dynlist
 overlay to
 .BR slapd (8)
-allows expansion of dynamic groups and more.
+allows expansion of dynamic lists and groups.
 Any time an entry with a specific objectClass (defined in the overlay configuration) is being returned,
 the LDAP URI-valued occurrences of a specific attribute (also defined in the overlay configuration) are
-expanded into the corresponding entries, and the values
-of the attributes listed in the URI are added to the original
+expanded into the corresponding entries.
+
+For a dynamic list, the values
+of the attributes listed in the URI are added from the matching entries to the original
 entry.
 No recursion is allowed, to avoid potential infinite loops.
-
 The resulting entry must comply with the LDAP data model, so constraints
 are enforced.
 For example, if a \fISINGLE\-VALUE\fP attribute is listed,
 only the first value found during the list expansion appears in the final entry.
+
+For a dynamic group, the DNs of the matching entries are added to a member attribute
+in the original entry.
+
 All dynamic behavior is disabled when the \fImanageDSAit\fP
 control (RFC 3296) is used.
-In that case, the contents of the dynamic group entry is returned;
+In that case, the contents of the original entry is returned;
 namely, the URLs are returned instead of being expanded.
 
 .SH CONFIGURATION
@@ -51,7 +56,8 @@ occurrences, and it must appear after the
 .B overlay
 directive.
 .TP
-.B dynlist\-attrset <group-oc> [<URI>] <URL-ad> [[<mapped-ad>:]<member-ad>[+<memberOf-ad[@<static-oc>[*]] ...]
+.B dynlist\-attrset <group-oc> [<URI>] <URL-ad> [options]
+
 The value 
 .B group\-oc
 is the name of the objectClass that triggers the dynamic expansion of the
@@ -71,9 +77,33 @@ If the intersection of the attributes requested by the search operation
 in the URI is empty, no expansion occurs for that specific URI.
 It must be a subtype of \fIlabeledURI\fP.
 
-The value
+The remaining options depend on whether a dynamic list or a dynamic group
+is being configured.
+
+For a dynamic list, the allowed options have the form
+
+.B [<mapped-ad>:<list-ad> ...]
+
+The
+.B mapped-ad
+can be used to remap attributes obtained through expansion.
+The
+.B list-ad
+must be one of the attributes returned in the expansion of the URIs in the
+.B URL-ad
+attribute of the dynamic entry. Multiple mapping statements can be used.
+Note that in order for dynamic lists
+to be usable in a search filter, the dynamic attributes to be filtered
+must be explicitly mapped. They can be mapped to themselves
+if no transformation is required.
+
+For a dynamic group, the allowed options are
+
+.B <member-ad>[+<memberOf-ad>[@<static-oc>[*]]]
+
+The
 .B member-ad
-is optional; if present, the overlay behaves as a dynamic group: this
+is required; this
 attribute will list the DN of the entries resulting from the internal search.
 In this case, the \fIattrs\fP portion of the URIs in the
 .B URL-ad
@@ -104,19 +134,6 @@ character is also specified, then the member and memberOf values will be
 populated recursively, for nested groups. Note that currently nesting is
 only supported for Search operations, not Compares.
 
-Alternatively, 
-.B mapped-ad
-can be used to remap attributes obtained through expansion. 
-.B member-ad
-attributes are not filled by expanded DN, but are remapped as
-.B mapped-ad 
-attributes.  Multiple mapping statements can be used. The
-.B memberOf-ad
-option is not used in this case. Note that in order for dynamic lists
-to be usable in a search filter, the dynamic attributes to be filtered
-in the list must be explicitly mapped. They can be mapped to themselves
-if no transformation is required.
-
 .LP
 The dynlist overlay may be used with any backend, but it is mainly 
 intended for use with local storage backends.