git.sur5r.net Git - openldap/blob - doc/guide/admin/overlays.sdf

   1 # $OpenLDAP$
   2 # Copyright 2007 The OpenLDAP Foundation, All Rights Reserved.
   3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
   4
   5 H1: Overlays
   6
   7 Overlays are software components that provide hooks to functions analogous to
   8 those provided by backends, which can be stacked on top of the backend calls
   9 and as callbacks on top of backend responses to alter their behavior.
  10
  11 Overlays may be compiled statically into slapd, or when module support
  12 is enabled, they may be dynamically loaded. Most of the overlays
  13 are only allowed to be configured on individual databases, but some
  14 may also be configured globally.
  15
  16 Essentially they represent a means to:
  17
  18     * customize the behavior of existing backends without changing the backend
  19       code and without requiring one to write a new custom backend with
  20       complete functionality
  21     * write functionality of general usefulness that can be applied to
  22       different backend types
  23
  24 Overlays are usually documented by separate specific man pages in section 5;
  25 the naming convention is
  26
  27 >        slapo-<overlay name>
  28
  29 Not all distributed overlays have a man page yet. Feel free to contribute one,
  30 if you think you well understood the behavior of the component and the
  31 implications of all the related configuration directives.
  32
  33 Official overlays are located in
  34
  35 >        servers/slapd/overlays/
  36
  37 That directory also contains the file slapover.txt, which describes the
  38 rationale of the overlay implementation, and may serve as guideline for the
  39 development of custom overlays.
  40
  41 Contribware overlays are located in
  42
  43 >        contrib/slapd-modules/<overlay name>/
  44
  45 along with other types of run-time loadable components; they are officially
  46 distributed, but not maintained by the project.
  47
  48 They can be stacked on the frontend as well; this means that they can be
  49 executed after a request is parsed and validated, but right before the
  50 appropriate database is selected. The main purpose is to affect operations
  51 regardless of the database they will be handled by, and, in some cases,
  52 to influence the selection of the database by massaging the request DN.
  53
  54 All the current overlays in 2.4 are listed and described in detail in the
  55 following sections.
  56
  57
  58 H2: Access Logging
  59
  60
  61 H3: Overview
  62
  63 This overlay can record accesses to a given backend database on another
  64 database.
  65
  66
  67 H3: Access Logging Configuration
  68
  69
  70 H2: Audit Logging
  71
  72 This overlay records changes on a given backend database to an LDIF log
  73 file.
  74
  75
  76 H3: Overview
  77
  78
  79 H3: Audit Logging Configuration
  80
  81
  82 H2: Chaining
  83
  84
  85 H3: Overview
  86
  87 The chain overlay provides basic chaining capability to the underlying
  88 database.
  89
  90 What is chaining? It indicates the capability of a DSA to follow referrals on
  91 behalf of the client, so that distributed systems are viewed as a single
  92 virtual DSA by clients that are otherwise unable to "chase" (i.e. follow)
  93 referrals by themselves.
  94
  95 The chain overlay is built on top of the ldap backend; it is compiled by
  96 default when --enable-ldap.
  97
  98
  99 H3: Chaining Configuration
 100
 101
 102 H2: Constraints
 103
 104
 105 H3: Overview
 106
 107 This overlay enforces a regular expression constraint on all values
 108 of specified attributes. It is used to enforce a more rigorous
 109 syntax when the underlying attribute syntax is too general.
 110
 111
 112 H3: Constraint Configuration
 113
 114
 115 H2: Dynamic Directory Services
 116
 117
 118 H3: Overview
 119
 120 This overlay supports dynamic objects, which have a limited life after
 121 which they expire and are automatically deleted.
 122
 123
 124 H3: Dynamic Directory Service Configuration
 125
 126
 127 H2: Dynamic Groups
 128
 129
 130 H3: Overview
 131
 132 This overlay extends the Compare operation to detect
 133 members of a dynamic group. This overlay is now deprecated
 134 as all of its functions are available using the
 135 {{SECT:Dynamic Lists}} overlay.
 136
 137
 138 H3: Dynamic Group Configuration
 139
 140
 141 H2: Dynamic Lists
 142
 143
 144 H3: Overview
 145
 146 This overlay allows expansion of dynamic groups and more.
 147
 148
 149 H3: Dynamic List Configuration
 150
 151
 152 H2: Reverse Group Membership Maintenance
 153
 154
 155 H3: Member Of Configuration
 156
 157
 158 H2: The Proxy Cache Engine
 159
 160 {{TERM:LDAP}} servers typically hold one or more subtrees of a
 161 {{TERM:DIT}}. Replica (or shadow) servers hold shadow copies of
 162 entries held by one or more master servers.  Changes are propagated
 163 from the master server to replica (slave) servers using LDAP Sync
 164 replication.  An LDAP cache is a special type of replica which holds
 165 entries corresponding to search filters instead of subtrees.
 166
 167 H3: Overview
 168
 169 The proxy cache extension of slapd is designed to improve the
 170 responsiveness of the ldap and meta backends. It handles a search
 171 request (query)
 172 by first determining whether it is contained in any cached search
 173 filter. Contained requests are answered from the proxy cache's local
 174 database. Other requests are passed on to the underlying ldap or
 175 meta backend and processed as usual.
 176
 177 E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and
 178 {{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}}
 179
 180 Correct matching rules and syntaxes are used while comparing
 181 assertions for query containment. To simplify the query containment
 182 problem, a list of cacheable "templates" (defined below) is specified
 183 at configuration time. A query is cached or answered only if it
 184 belongs to one of these templates. The entries corresponding to
 185 cached queries are stored in the proxy cache local database while
 186 its associated meta information (filter, scope, base, attributes)
 187 is stored in main memory.
 188
 189 A template is a prototype for generating LDAP search requests.
 190 Templates are described by a prototype search filter and a list of
 191 attributes which are required in queries generated from the template.
 192 The representation for prototype filter is similar to {{REF:RFC4515}},
 193 except that the assertion values are missing. Examples of prototype
 194 filters are: (sn=),(&(sn=)(givenname=)) which are instantiated by
 195 search filters (sn=Doe) and (&(sn=Doe)(givenname=John)) respectively.
 196
 197 The cache replacement policy removes the least recently used (LRU)
 198 query and entries belonging to only that query. Queries are allowed
 199 a maximum time to live (TTL) in the cache thus providing weak
 200 consistency. A background task periodically checks the cache for
 201 expired queries and removes them.
 202
 203 The Proxy Cache paper
 204 ({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides
 205 design and implementation details.
 206
 207
 208 H3: Proxy Cache Configuration
 209
 210 The cache configuration specific directives described below must
 211 appear after a {{EX:overlay proxycache}} directive within a
 212 {{EX:"database meta"}} or {{EX:database ldap}} section of
 213 the server's {{slapd.conf}}(5) file.
 214
 215 H4: Setting cache parameters
 216
 217 > proxyCache <DB> <maxentries> <nattrsets> <entrylimit> <period>
 218
 219 This directive enables proxy caching and sets general cache
 220 parameters.  The <DB> parameter specifies which underlying database
 221 is to be used to hold cached entries.  It should be set to
 222 {{EX:bdb}} or {{EX:hdb}}.  The <maxentries> parameter specifies the
 223 total number of entries which may be held in the cache.  The
 224 <nattrsets> parameter specifies the total number of attribute sets
 225 (as specified by the {{EX:proxyAttrSet}} directive) that may be
 226 defined.  The <entrylimit> parameter specifies the maximum number of
 227 entries in a cacheable query.  The <period> specifies the consistency
 228 check period (in seconds).  In each period, queries with expired
 229 TTLs are removed.
 230
 231 H4: Defining attribute sets
 232
 233 > proxyAttrset <index> <attrs...>
 234
 235 Used to associate a set of attributes to an index. Each attribute
 236 set is associated with an index number from 0 to <numattrsets>-1.
 237 These indices are used by the proxyTemplate directive to define
 238 cacheable templates.
 239
 240 H4: Specifying cacheable templates
 241
 242 > proxyTemplate <prototype_string> <attrset_index> <TTL>
 243
 244 Specifies a cacheable template and the "time to live" (in sec) <TTL>
 245 for queries belonging to the template. A template is described by
 246 its prototype filter string and set of required attributes identified
 247 by <attrset_index>.
 248
 249
 250 H4: Example
 251
 252 An example {{slapd.conf}}(5) database section for a caching server
 253 which proxies for the {{EX:"dc=example,dc=com"}} subtree held
 254 at server {{EX:ldap.example.com}}.
 255
 256 >       database        ldap
 257 >       suffix          "dc=example,dc=com"
 258 >       rootdn          "dc=example,dc=com"
 259 >       uri             ldap://ldap.example.com/dc=example%2cdc=com
 260 >       overlay proxycache
 261 >       proxycache    bdb 100000 1 1000 100
 262 >       proxyAttrset  0 mail postaladdress telephonenumber
 263 >       proxyTemplate (sn=) 0 3600
 264 >       proxyTemplate (&(sn=)(givenName=)) 0 3600
 265 >       proxyTemplate (&(departmentNumber=)(secretary=*)) 0 3600
 266 >
 267 >       cachesize 20
 268 >       directory ./testrun/db.2.a
 269 >       index       objectClass eq
 270 >       index       cn,sn,uid,mail  pres,eq,sub
 271
 272
 273 H5: Cacheable Queries
 274
 275 A LDAP search query is cacheable when its filter matches one of the
 276 templates as defined in the "proxyTemplate" statements and when it references
 277 only the attributes specified in the corresponding attribute set.
 278 In the example above the attribute set number 0 defines that only the
 279 attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
 280 proxyTemplates.
 281
 282 H5: Examples:
 283
 284 >       Filter: (&(sn=Richard*)(givenName=jack))
 285 >       Attrs: mail telephoneNumber
 286
 287     is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
 288     attributes are contained in proxyAttrset 0.
 289
 290 >       Filter: (&(sn=Richard*)(telephoneNumber))
 291 >       Attrs: givenName
 292
 293     is not cacheable, because the filter does not match the template,
 294     nor is the attribute givenName stored in the cache
 295
 296 >       Filter: (|(sn=Richard*)(givenName=jack))
 297 >       Attrs: mail telephoneNumber
 298
 299     is not cacheable, because the filter does not match the template ( logical
 300     OR "|" condition instead of logical AND "&" )
 301
 302
 303 H2: Password Policies
 304
 305
 306 H3: Overview
 307
 308 This overlay provides a variety of password control mechanisms,
 309 e.g. password aging, password reuse and duplication control, mandatory
 310 password resets, etc.
 311
 312
 313 H3: Password Policy Configuration
 314
 315
 316 H2: Referential Integrity
 317
 318
 319 H3: Overview
 320
 321 This overlay can be used with a backend database such as slapd-bdb (5)
 322 to maintain the cohesiveness of a schema which utilizes reference
 323 attributes.
 324
 325
 326 H3: Referential Integrity Configuration
 327
 328
 329 H2: Return Code
 330
 331
 332 H3: Overview
 333
 334 This overlay is useful to test the behavior of clients when
 335 server-generated erroneous and/or unusual responses occur.
 336
 337
 338 H3: Return Code Configuration
 339
 340
 341 H2: Rewrite/Remap
 342
 343
 344 H3: Overview
 345
 346 It performs basic DN/data rewrite and
 347 objectClass/attributeType mapping.
 348
 349
 350 H3: Rewrite/Remap Configuration
 351
 352
 353 H2: Sync Provider
 354
 355
 356 H3: Overview
 357
 358 This overlay implements the provider-side support for syncrepl
 359 replication, including persistent search functionality
 360
 361
 362 H3: Sync Provider Configuration
 363
 364
 365 H2: Translucent Proxy
 366
 367
 368 H3: Overview
 369
 370 This overlay can be used with a backend database such as slapd-bdb (5)
 371 to create a "translucent proxy".
 372
 373 Content of entries retrieved from a remote LDAP server can be partially
 374 overridden by the database.
 375
 376
 377 H3: Translucent Proxy Configuration
 378
 379
 380 H2: Attribute Uniqueness
 381
 382
 383 H3: Overview
 384
 385 This overlay can be used with a backend database such as slapd-bdb (5)
 386 to enforce the uniqueness of some or all attributes within a subtree.
 387
 388
 389 H3: Attribute Uniqueness Configuration
 390
 391
 392 H2: Value Sorting
 393
 394
 395 H3: Overview
 396
 397 This overlay can be used to enforce a specific order for the values
 398 of an attribute when it is returned in a search.
 399
 400
 401 H3: Value Sorting Configuration
 402
 403
 404 H2: Overlay Stacking
 405
 406
 407 H3: Overview
 408
 409
 410 H3: Example Scenarios
 411
 412
 413 H4: Samba