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.
 134
 135
 136 H3: Dynamic Group Configuration
 137
 138
 139 H2: Dynamic Lists
 140
 141
 142 H3: Overview
 143
 144 This overlay allows expansion of dynamic groups and more.
 145
 146
 147 H3: Dynamic List Configuration
 148
 149
 150 H2: Reverse Group Membership Maintenance
 151
 152
 153 H3: Member Of Configuration
 154
 155
 156 H2: The Proxy Cache Engine
 157
 158 {{TERM:LDAP}} servers typically hold one or more subtrees of a
 159 {{TERM:DIT}}. Replica (or shadow) servers hold shadow copies of
 160 entries held by one or more master servers.  Changes are propagated
 161 from the master server to replica (slave) servers using LDAP Sync
 162 replication.  An LDAP cache is a special type of replica which holds
 163 entries corresponding to search filters instead of subtrees.
 164
 165 H3: Overview
 166
 167 The proxy cache extension of slapd is designed to improve the
 168 responsiveness of the ldap and meta backends. It handles a search
 169 request (query)
 170 by first determining whether it is contained in any cached search
 171 filter. Contained requests are answered from the proxy cache's local
 172 database. Other requests are passed on to the underlying ldap or
 173 meta backend and processed as usual.
 174
 175 E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and
 176 {{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}}
 177
 178 Correct matching rules and syntaxes are used while comparing
 179 assertions for query containment. To simplify the query containment
 180 problem, a list of cacheable "templates" (defined below) is specified
 181 at configuration time. A query is cached or answered only if it
 182 belongs to one of these templates. The entries corresponding to
 183 cached queries are stored in the proxy cache local database while
 184 its associated meta information (filter, scope, base, attributes)
 185 is stored in main memory.
 186
 187 A template is a prototype for generating LDAP search requests.
 188 Templates are described by a prototype search filter and a list of
 189 attributes which are required in queries generated from the template.
 190 The representation for prototype filter is similar to {{REF:RFC4515}},
 191 except that the assertion values are missing. Examples of prototype
 192 filters are: (sn=),(&(sn=)(givenname=)) which are instantiated by
 193 search filters (sn=Doe) and (&(sn=Doe)(givenname=John)) respectively.
 194
 195 The cache replacement policy removes the least recently used (LRU)
 196 query and entries belonging to only that query. Queries are allowed
 197 a maximum time to live (TTL) in the cache thus providing weak
 198 consistency. A background task periodically checks the cache for
 199 expired queries and removes them.
 200
 201 The Proxy Cache paper
 202 ({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides
 203 design and implementation details.
 204
 205
 206 H3: Proxy Cache Configuration
 207
 208 The cache configuration specific directives described below must
 209 appear after a {{EX:overlay proxycache}} directive within a
 210 {{EX:"database meta"}} or {{EX:database ldap}} section of
 211 the server's {{slapd.conf}}(5) file.
 212
 213 H4: Setting cache parameters
 214
 215 > proxyCache <DB> <maxentries> <nattrsets> <entrylimit> <period>
 216
 217 This directive enables proxy caching and sets general cache
 218 parameters.  The <DB> parameter specifies which underlying database
 219 is to be used to hold cached entries.  It should be set to
 220 {{EX:bdb}} or {{EX:hdb}}.  The <maxentries> parameter specifies the
 221 total number of entries which may be held in the cache.  The
 222 <nattrsets> parameter specifies the total number of attribute sets
 223 (as specified by the {{EX:proxyAttrSet}} directive) that may be
 224 defined.  The <entrylimit> parameter specifies the maximum number of
 225 entries in a cacheable query.  The <period> specifies the consistency
 226 check period (in seconds).  In each period, queries with expired
 227 TTLs are removed.
 228
 229 H4: Defining attribute sets
 230
 231 > proxyAttrset <index> <attrs...>
 232
 233 Used to associate a set of attributes to an index. Each attribute
 234 set is associated with an index number from 0 to <numattrsets>-1.
 235 These indices are used by the proxyTemplate directive to define
 236 cacheable templates.
 237
 238 H4: Specifying cacheable templates
 239
 240 > proxyTemplate <prototype_string> <attrset_index> <TTL>
 241
 242 Specifies a cacheable template and the "time to live" (in sec) <TTL>
 243 for queries belonging to the template. A template is described by
 244 its prototype filter string and set of required attributes identified
 245 by <attrset_index>.
 246
 247
 248 H4: Example
 249
 250 An example {{slapd.conf}}(5) database section for a caching server
 251 which proxies for the {{EX:"dc=example,dc=com"}} subtree held
 252 at server {{EX:ldap.example.com}}.
 253
 254 >       database        ldap
 255 >       suffix          "dc=example,dc=com"
 256 >       rootdn          "dc=example,dc=com"
 257 >       uri             ldap://ldap.example.com/dc=example%2cdc=com
 258 >       overlay proxycache
 259 >       proxycache    bdb 100000 1 1000 100
 260 >       proxyAttrset  0 mail postaladdress telephonenumber
 261 >       proxyTemplate (sn=) 0 3600
 262 >       proxyTemplate (&(sn=)(givenName=)) 0 3600
 263 >       proxyTemplate (&(departmentNumber=)(secretary=*)) 0 3600
 264 >
 265 >       cachesize 20
 266 >       directory ./testrun/db.2.a
 267 >       index       objectClass eq
 268 >       index       cn,sn,uid,mail  pres,eq,sub
 269
 270
 271 H5: Cacheable Queries
 272
 273 A LDAP search query is cacheable when its filter matches one of the
 274 templates as defined in the "proxyTemplate" statements and when it references
 275 only the attributes specified in the corresponding attribute set.
 276 In the example above the attribute set number 0 defines that only the
 277 attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
 278 proxyTemplates.
 279
 280 H5: Examples:
 281
 282 >       Filter: (&(sn=Richard*)(givenName=jack))
 283 >       Attrs: mail telephoneNumber
 284
 285     is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
 286     attributes are contained in proxyAttrset 0.
 287
 288 >       Filter: (&(sn=Richard*)(telephoneNumber))
 289 >       Attrs: givenName
 290
 291     is not cacheable, because the filter does not match the template,
 292     nor is the attribute givenName stored in the cache
 293
 294 >       Filter: (|(sn=Richard*)(givenName=jack))
 295 >       Attrs: mail telephoneNumber
 296
 297     is not cacheable, because the filter does not match the template ( logical
 298     OR "|" condition instead of logical AND "&" )
 299
 300
 301 H2: Password Policies
 302
 303
 304 H3: Overview
 305
 306 This overlay provides a variety of password control mechanisms,
 307 e.g. password aging, password reuse and duplication control, mandatory
 308 password resets, etc.
 309
 310
 311 H3: Password Policy Configuration
 312
 313
 314 H2: Referential Integrity
 315
 316
 317 H3: Overview
 318
 319 This overlay can be used with a backend database such as slapd-bdb (5)
 320 to maintain the cohesiveness of a schema which utilizes reference
 321 attributes.
 322
 323
 324 H3: Referential Integrity Configuration
 325
 326
 327 H2: Return Code
 328
 329
 330 H3: Overview
 331
 332 This overlay is useful to test the behavior of clients when
 333 server-generated erroneous and/or unusual responses occur.
 334
 335
 336 H3: Return Code Configuration
 337
 338
 339 H2: Rewrite/Remap
 340
 341
 342 H3: Overview
 343
 344 It performs basic DN/data rewrite and
 345 objectClass/attributeType mapping.
 346
 347
 348 H3: Rewrite/Remap Configuration
 349
 350
 351 H2: Sync Provider
 352
 353
 354 H3: Overview
 355
 356 This overlay implements the provider-side support for syncrepl
 357 replication, including persistent search functionality
 358
 359
 360 H3: Sync Provider Configuration
 361
 362
 363 H2: Translucent Proxy
 364
 365
 366 H3: Overview
 367
 368 This overlay can be used with a backend database such as slapd-bdb (5)
 369 to create a "translucent proxy".
 370
 371 Content of entries retrieved from a remote LDAP server can be partially
 372 overridden by the database.
 373
 374
 375 H3: Translucent Proxy Configuration
 376
 377
 378 H2: Attribute Uniqueness
 379
 380
 381 H3: Overview
 382
 383 This overlay can be used with a backend database such as slapd-bdb (5)
 384 to enforce the uniqueness of some or all attributes within a subtree.
 385
 386
 387 H3: Attribute Uniqueness Configuration
 388
 389
 390 H2: Value Sorting
 391
 392
 393 H3: Overview
 394
 395 This overlay can be used to enforce a specific order for the values
 396 of an attribute when it is returned in a search.
 397
 398
 399 H3: Value Sorting Configuration
 400
 401
 402 H2: Overlay Stacking
 403
 404
 405 H3: Overview
 406
 407
 408 H3: Example Scenarios
 409
 410
 411 H4: Samba