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