git.sur5r.net Git - openldap/blob - doc/man/man5/slapo-dynlist.5

   1 .TH SLAPO-DYNLIST 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" Copyright 1998-2017 The OpenLDAP Foundation, All Rights Reserved.
   3 .\" Copying restrictions apply.  See the COPYRIGHT file.
   4 .\" $OpenLDAP$
   5 .SH NAME
   6 slapo\-dynlist \- Dynamic List overlay to slapd
   7 .SH SYNOPSIS
   8 ETCDIR/slapd.conf
   9 .SH DESCRIPTION
  10 The
  11 .B dynlist
  12 overlay to
  13 .BR slapd (8)
  14 allows expansion of dynamic groups and more.
  15 Any time an entry with a specific objectClass (defined in the overlay configuration) is being returned,
  16 the LDAP URI-valued occurrences of a specific attribute (also defined in the overlay configuration) are
  17 expanded into the corresponding entries, and the values
  18 of the attributes listed in the URI are added to the original
  19 entry.
  20 No recursion is allowed, to avoid potential infinite loops.
  21
  22 Since the resulting entry is dynamically constructed,
  23 it does not exist until it is constructed while being returned.
  24 As a consequence, dynamically added attributes do not participate
  25 in the filter matching phase of the search request handling.
  26 In other words, \fIfiltering for dynamically added attributes always fails\fP.
  27
  28 The resulting entry must comply with the LDAP data model, so constraints
  29 are enforced.
  30 For example, if a \fISINGLE\-VALUE\fP attribute is listed,
  31 only the first value found during the list expansion appears in the final entry.
  32 The above described behavior is disabled when the \fImanageDSAit\fP
  33 control (RFC 3296) is used.
  34 In that case, the contents of the dynamic group entry is returned;
  35 namely, the URLs are returned instead of being expanded.
  36
  37 .SH CONFIGURATION
  38 The config directives that are specific to the
  39 .B dynlist
  40 overlay must be prefixed by
  41 .BR dynlist\- ,
  42 to avoid potential conflicts with directives specific to the underlying
  43 database or to other stacked overlays.
  44
  45 .TP
  46 .B overlay dynlist
  47 This directive adds the dynlist overlay to the current database,
  48 or to the frontend, if used before any database instantiation; see
  49 .BR slapd.conf (5)
  50 for details.
  51
  52 .LP
  53 This
  54 .B slapd.conf
  55 configuration option is defined for the dynlist overlay. It may have multiple
  56 occurrences, and it must appear after the
  57 .B overlay
  58 directive.
  59 .TP
  60 .B dynlist\-attrset <group-oc> [<URI>] <URL-ad> [[<mapped-ad>:]<member-ad> ...]
  61 The value
  62 .B group\-oc
  63 is the name of the objectClass that triggers the dynamic expansion of the
  64 data.
  65
  66 The optional
  67 .B URI
  68 restricts expansion only to entries matching the \fIDN\fP,
  69 the \fIscope\fP and the \fIfilter\fP portions of the URI.
  70
  71 The value
  72 .B URL-ad
  73 is the name of the attributeDescription that contains the URI that is
  74 expanded by the overlay; if none is present, no expansion occurs.
  75 If the intersection of the attributes requested by the search operation
  76 (or the asserted attribute for compares) and the attributes listed
  77 in the URI is empty, no expansion occurs for that specific URI.
  78 It must be a subtype of \fIlabeledURI\fP.
  79
  80 The value
  81 .B member-ad
  82 is optional; if present, the overlay behaves as a dynamic group: this
  83 attribute will list the DN of the entries resulting from the internal search.
  84 In this case, the \fIattrs\fP portion of the URIs in the
  85 .B URL-ad
  86 attribute must be absent, and the \fIDN\fPs
  87 of all the entries resulting from the expansion of the URIs are listed
  88 as values of this attribute.
  89 Compares that assert the value of the
  90 .B member-ad
  91 attribute of entries with
  92 .B group-oc
  93 objectClass apply as if the DN of the entries resulting from the expansion
  94 of the URI were present in the
  95 .B group-oc
  96 entry as values of the
  97 .B member-ad
  98 attribute.
  99
 100 Alternatively,
 101 .B mapped-ad
 102 can be used to remap attributes obtained through expansion.
 103 .B member-ad
 104 attributes are not filled by expanded DN, but are remapped as
 105 .B mapped-ad
 106 attributes.  Multiple mapping statements can be used.
 107
 108 .LP
 109 The dynlist overlay may be used with any backend, but it is mainly
 110 intended for use with local storage backends.
 111 In case the URI expansion is very resource-intensive and occurs frequently
 112 with well-defined patterns, one should consider adding a proxycache
 113 later on in the overlay stack.
 114
 115 .SH AUTHORIZATION
 116 By default the expansions are performed using the identity of the current
 117 LDAP user.
 118 This identity may be overridden by setting the
 119 .B dgIdentity
 120 attribute in the group's entry to the DN of another LDAP user.
 121 In that case the dgIdentity will be used when expanding the URIs in the object.
 122 Setting the dgIdentity to a zero-length string will cause the expansions
 123 to be performed anonymously.
 124 Note that the dgIdentity attribute is defined in the
 125 .B dyngroup
 126 schema, and this schema must be loaded before the dgIdentity
 127 authorization feature may be used.
 128 If the
 129 .B dgAuthz
 130 attribute is also present in the group's entry, its values are used
 131 to determine what identities are authorized to use the
 132 .B dgIdentity
 133 to expand the group.
 134 Values of the
 135 .B dgAuthz
 136 attribute must conform to the (experimental) \fIOpenLDAP authz\fP syntax.
 137
 138 .SH EXAMPLE
 139 This example collects all the email addresses of a database into a single
 140 entry; first of all, make sure that slapd.conf contains the directives:
 141
 142 .LP
 143 .nf
 144     include /path/to/dyngroup.schema
 145     # ...
 146
 147     database <database>
 148     # ...
 149
 150     overlay dynlist
 151     dynlist\-attrset groupOfURLs memberURL
 152 .fi
 153 .LP
 154 and that slapd loads dynlist.la, if compiled as a run-time module;
 155 then add to the database an entry like
 156 .LP
 157 .nf
 158     dn: cn=Dynamic List,ou=Groups,dc=example,dc=com
 159     objectClass: groupOfURLs
 160     cn: Dynamic List
 161     memberURL: ldap:///ou=People,dc=example,dc=com?mail?sub?(objectClass=person)
 162 .fi
 163
 164 If no <attrs> are provided in the URI, all (non-operational) attributes are
 165 collected.
 166
 167 This example implements the dynamic group feature on the
 168 .B member
 169 attribute:
 170
 171 .LP
 172 .nf
 173     include /path/to/dyngroup.schema
 174     # ...
 175
 176     database <database>
 177     # ...
 178
 179     overlay dynlist
 180     dynlist\-attrset groupOfURLs memberURL member
 181 .fi
 182 .LP
 183
 184 A dynamic group with dgIdentity authorization could be created with an
 185 entry like
 186 .LP
 187 .nf
 188     dn: cn=Dynamic Group,ou=Groups,dc=example,dc=com
 189     objectClass: groupOfURLs
 190     objectClass: dgIdentityAux
 191     cn: Dynamic Group
 192     memberURL: ldap:///ou=People,dc=example,dc=com??sub?(objectClass=person)
 193     dgIdentity: cn=Group Proxy,ou=Services,dc=example,dc=com
 194 .fi
 195
 196 .SH FILES
 197 .TP
 198 ETCDIR/slapd.conf
 199 default slapd configuration file
 200 .SH SEE ALSO
 201 .BR slapd.conf (5),
 202 .BR slapd\-config (5),
 203 .BR slapd (8).
 204 The
 205 .BR slapo\-dynlist (5)
 206 overlay supports dynamic configuration via
 207 .BR back-config .
 208 .SH ACKNOWLEDGEMENTS
 209 .P
 210 This module was written in 2004 by Pierangelo Masarati for SysNet s.n.c.
 211 .P
 212 Attribute remapping was contributed in 2008 by Emmanuel Dreyfus.