.TH SLAPO-DYNLIST 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2005 The OpenLDAP Foundation, All Rights Reserved.
+.\" Copyright 1998-2013 The OpenLDAP Foundation, All Rights Reserved.
.\" Copying restrictions apply. See the COPYRIGHT file.
.\" $OpenLDAP$
.SH NAME
-slapo-dynlist \- Dynamic List overlay
+slapo\-dynlist \- Dynamic List overlay to slapd
.SH SYNOPSIS
ETCDIR/slapd.conf
.SH DESCRIPTION
overlay to
.BR slapd (8)
allows expansion of dynamic groups and more.
-Any time an entry with a specific objectClass is being returned,
-the LDAP URI-valued occurrences of a specific attribute are
+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
entry.
-No recursion is currently allowed, to avoid potential infinite loops.
+No recursion is allowed, to avoid potential infinite loops.
+
+Since the resulting entry is dynamically constructed,
+it does not exist until it is constructed while being returned.
+As a consequence, dynamically added attributes do not participate
+in the filter matching phase of the search request handling.
+In other words, \fIfiltering for dynamically added attributes always fails\fP.
+
+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.
+The above described behavior is disabled when the \fImanageDSAit\fP
+control (RFC 3296) is used.
+In that case, the contents of the dynamic group entry is returned;
+namely, the URLs are returned instead of being expanded.
.SH CONFIGURATION
The config directives that are specific to the
for details.
.LP
-These
+This
.B slapd.conf
-configuration options apply to the dynlist overlay. They must appear
-after the
+configuration option is defined for the dynlist overlay. It may have multiple
+occurrences, and it must appear after the
.B overlay
directive.
.TP
-.B dynlist-oc <objectClass>
-The name of the objectClass that triggers the dynamic expansion of the
-data. This statement is required.
-.TP
-.B dynlist-ad <attributeName>
-The name of the attributeDescription that holds the LDAP URI values that
-will expand; if none is present, no expansion occurs. If the intersection
-of the attributes requested by the search operation (or the asserted attribute
-for compares) and the attributes listed in the URI is empty, no expansion
-occurs for that specific URI. This statement is required.
-.TP
-.B dynlist-member-ad <attributeName>
-The name of the attributeDescription that will list the DN of the entries
-resulting from the internal search. This statement is optional and, if
-present, changes the behavior of the overlay into that of a dynamic group.
-The <attrs> portion of the URI must be absent, and the DNs of all the entries
-resulting from the expansion of the URI are listed as values of this
-attribute.
-Compares to
-.B dynlist-member-ad
-attributes of entries with
-.B dynlist-oc
+.B dynlist\-attrset <group-oc> [<URI>] <URL-ad> [[<mapped-ad>:]<member-ad> ...]
+The value
+.B group\-oc
+is the name of the objectClass that triggers the dynamic expansion of the
+data.
+
+The optional
+.B URI
+restricts expansion only to entries matching the \fIDN\fP,
+the \fIscope\fP and the \fIfilter\fP portions of the URI.
+
+The value
+.B URL-ad
+is the name of the attributeDescription that contains the URI that is
+expanded by the overlay; if none is present, no expansion occurs.
+If the intersection of the attributes requested by the search operation
+(or the asserted attribute for compares) and the attributes listed
+in the URI is empty, no expansion occurs for that specific URI.
+It must be a subtype of \fIlabeledURI\fP.
+
+The value
+.B member-ad
+is optional; if present, the overlay behaves as a dynamic group: 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
+attribute must be absent, and the \fIDN\fPs
+of all the entries resulting from the expansion of the URIs are listed
+as values of this attribute.
+Compares that assert the value of the
+.B member-ad
+attribute of entries with
+.B group-oc
objectClass apply as if the DN of the entries resulting from the expansion
of the URI were present in the
-.B dynlist-oc
+.B group-oc
entry as values of the
-.B dynlist-member-ad
-attributeType.
+.B member-ad
+attribute.
+
+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.
+
.LP
The dynlist overlay may be used with any backend, but it is mainly
intended for use with local storage backends.
with well-defined patterns, one should consider adding a proxycache
later on in the overlay stack.
+.SH AUTHORIZATION
+By default the expansions are performed using the identity of the current
+LDAP user.
+This identity may be overridden by setting the
+.B dgIdentity
+attribute in the group's entry to the DN of another LDAP user.
+In that case the dgIdentity will be used when expanding the URIs in the object.
+Setting the dgIdentity to a zero-length string will cause the expansions
+to be performed anonymously.
+Note that the dgIdentity attribute is defined in the
+.B dyngroup
+schema, and this schema must be loaded before the dgIdentity
+authorization feature may be used.
+If the
+.B dgAuthz
+attribute is also present in the group's entry, its values are used
+to determine what identities are authorized to use the
+.B dgIdentity
+to expand the group.
+Values of the
+.B dgAuthz
+attribute must conform to the (experimental) \fIOpenLDAP authz\fP syntax.
+
.SH EXAMPLE
This example collects all the email addresses of a database into a single
entry; first of all, make sure that slapd.conf contains the directives:
# ...
overlay dynlist
- dynlist-oc groupOfURLs
- dynlist-ad memberURL
+ dynlist\-attrset groupOfURLs memberURL
.fi
.LP
and that slapd loads dynlist.la, if compiled as a run-time module;
If no <attrs> are provided in the URI, all (non-operational) attributes are
collected.
+This example implements the dynamic group feature on the
+.B member
+attribute:
+
+.LP
+.nf
+ include /path/to/dyngroup.schema
+ # ...
+
+ database <database>
+ # ...
+
+ overlay dynlist
+ dynlist\-attrset groupOfURLs memberURL member
+.fi
+.LP
+
+A dynamic group with dgIdentity authorization could be created with an
+entry like
+.LP
+.nf
+ dn: cn=Dynamic Group,ou=Groups,dc=example,dc=com
+ objectClass: groupOfURLs
+ objectClass: dgIdentityAux
+ cn: Dynamic Group
+ memberURL: ldap:///ou=People,dc=example,dc=com??sub?(objectClass=person)
+ dgIdentity: cn=Group Proxy,ou=Services,dc=example,dc=com
+.fi
.SH FILES
.TP
default slapd configuration file
.SH SEE ALSO
.BR slapd.conf (5),
+.BR slapd\-config (5),
.BR slapd (8).
+The
+.BR slapo\-dynlist (5)
+overlay supports dynamic configuration via
+.BR back-config .
.SH ACKNOWLEDGEMENTS
.P
This module was written in 2004 by Pierangelo Masarati for SysNet s.n.c.
+.P
+Attribute remapping was contributed in 2008 by Emmanuel Dreyfus.