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 In order to demonstrate how this overlay works, we shall discuss a typical
 102 scenario which might be one master server and three Syncrepl slaves.
 103
 104 On each replica, add this near the top of the file (global), before any database
 105 definitions:
 106
 107 >        overlay                    chain
 108 >        chain-uri                  "ldap://ldapmaster.example.com"
 109 >        chain-idassert-bind        bindmethod="simple"
 110 >                                   binddn="cn=Manager,dc=example,dc=com"
 111 >                                   credentials="<secret>"
 112 >                                   mode="self"
 113 >        chain-tls                  start
 114 >        chain-return-error         TRUE
 115
 116 Add this below your {{syncrepl}} statement:
 117
 118 >        updateref                  "ldap://ldapmaster.example.com/"
 119
 120 The {{B:chain-tls}} statement enables TLS from the slave to the ldap master.
 121 The DITs are exactly the same between these machines, therefore whatever user
 122 bound to the slave will also exist on the master. If that DN does not have
 123 update privileges on the master, nothing will happen.
 124
 125 You will need to restart the slave after these changes. Then, if you are using
 126 {{loglevel 256}}, you can monitor an {{ldapmodify}} on the slave and the master.
 127
 128 Now start an {{ldapmodify}} on the slave and watch the logs. You should expect
 129 something like:
 130
 131 >        Sep  6 09:27:25 slave1 slapd[29274]: conn=11 fd=31 ACCEPT from IP=143.199.102.216:45181 (IP=143.199.102.216:389)
 132 >        Sep  6 09:27:25 slave1 slapd[29274]: conn=11 op=0 STARTTLS
 133 >        Sep  6 09:27:25 slave1 slapd[29274]: conn=11 op=0 RESULT oid= err=0 text=
 134 >        Sep  6 09:27:25 slave1 slapd[29274]: conn=11 fd=31 TLS established tls_ssf=256 ssf=256
 135 >        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=1 BIND dn="uid=user1,ou=people,dc=example,dc=com" method=128
 136 >        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=1 BIND dn="uid=user1,ou=People,dc=example,dc=com" mech=SIMPLE ssf=0
 137 >        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=1 RESULT tag=97 err=0 text=
 138 >        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD dn="uid=user1,ou=People,dc=example,dc=com"
 139 >        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD attr=mail
 140 >        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=2 RESULT tag=103 err=0 text=
 141 >        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=3 UNBIND
 142 >        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 fd=31 closed
 143 >        Sep  6 09:27:28 slave1 slapd[29274]: syncrepl_entry: LDAP_RES_SEARCH_ENTRY(LDAP_SYNC_MODIFY)
 144 >        Sep  6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_search (0)
 145 >        Sep  6 09:27:28 slave1 slapd[29274]: syncrepl_entry: uid=user1,ou=People,dc=example,dc=com
 146 >        Sep  6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_modify (0)
 147
 148 And on the master you will see this:
 149
 150 >        Sep  6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 PROXYAUTHZ dn="uid=user1,ou=people,dc=example,dc=com"
 151 >        Sep  6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD dn="uid=user1,ou=People,dc=example,dc=com"
 152 >        Sep  6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD attr=mail
 153 >        Sep  6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 RESULT tag=103 err=0 text=
 154
 155 Note: You can clearly see the PROXYAUTHZ line on the master, indicating the
 156 proper identity assertion for the update on the master. Also note the slave
 157 immediately receiving the Syncrepl update from the master.
 158
 159 H3: Handling Chaining Errors
 160
 161 By default, if chaining fails, the original referral is returned to the client
 162 under the assumption that the client might want to try and follow the referral.
 163
 164 With the following directive however, if the chaining fails at the provider
 165 side, the actual error is returned to the client.
 166
 167 >        chain-return-error TRUE
 168
 169
 170 H2: Constraints
 171
 172
 173 H3: Overview
 174
 175 This overlay enforces a regular expression constraint on all values
 176 of specified attributes. It is used to enforce a more rigorous
 177 syntax when the underlying attribute syntax is too general.
 178
 179
 180 H3: Constraint Configuration
 181
 182
 183 H2: Dynamic Directory Services
 184
 185
 186 H3: Overview
 187
 188 This overlay supports dynamic objects, which have a limited life after
 189 which they expire and are automatically deleted.
 190
 191
 192 H3: Dynamic Directory Service Configuration
 193
 194
 195 H2: Dynamic Groups
 196
 197
 198 H3: Overview
 199
 200 This overlay extends the Compare operation to detect
 201 members of a dynamic group. This overlay is now deprecated
 202 as all of its functions are available using the
 203 {{SECT:Dynamic Lists}} overlay.
 204
 205
 206 H3: Dynamic Group Configuration
 207
 208
 209 H2: Dynamic Lists
 210
 211
 212 H3: Overview
 213
 214 This overlay allows expansion of dynamic groups and more.
 215
 216
 217 H3: Dynamic List Configuration
 218
 219
 220 H2: Reverse Group Membership Maintenance
 221
 222 H3: Overview
 223
 224 In some scenarios, it may be desirable for a client to be able to determine
 225 which groups an entry is a member of, without performing an additional search.
 226 Examples of this are applications using the {{TERM:DIT}} for access control
 227 based on group authorization.
 228
 229 The {{B:memberof}} overlay updates an attribute (by default {{B:memberOf}}) whenever
 230 changes occur to the membership attribute (by default {{B:member}}) of entries of the
 231 objectclass (by default {{B:groupOfNames}}) configured to trigger updates.
 232
 233 Thus, it provides maintenance of the list of groups an entry is a member of,
 234 when usual maintenance of groups is done by modifying the members on the group
 235 entry.
 236
 237 H3: Member Of Configuration
 238
 239 The typical use of this overlay requires just enabling the overlay for a
 240 specific database. For example, with the following minimal slapd.conf:
 241
 242 >        include /usr/share/openldap/schema/core.schema
 243 >        include /usr/share/openldap/schema/cosine.schema
 244 >        modulepath      /usr/lib/openldap
 245 >        moduleload      memberof.la
 246 >        authz-regexp "gidNumber=0\\\+uidNumber=0,cn=peercred,cn=external,cn=auth"
 247 >                "cn=Manager,dc=example,dc=com"
 248 >        database        bdb
 249 >        suffix          "dc=example,dc=com"
 250 >        rootdn          "cn=Manager,dc=example,dc=com"
 251 >        rootpw          secret
 252 >        directory       /var/lib/ldap2.4
 253 >        checkpoint 256 5
 254 >        index   objectClass   eq
 255 >        index   uid           eq,sub
 256 >
 257 >        overlay memberof
 258
 259 adding the following ldif:
 260
 261 >        cat memberof.ldif
 262 >        dn: dc=example,dc=com
 263 >        objectclass: domain
 264 >        dc: example
 265 >
 266 >        dn: ou=Group,dc=example,dc=com
 267 >        objectclass: organizationalUnit
 268 >        ou: Group
 269 >
 270 >        dn: ou=People,dc=example,dc=com
 271 >        objectclass: organizationalUnit
 272 >        ou: People
 273 >
 274 >        dn: uid=test1,ou=People,dc=example,dc=com
 275 >        objectclass: account
 276 >        uid: test1
 277 >
 278 >        dn: cn=testgroup,ou=Group,dc=example,dc=com
 279 >        objectclass: groupOfNames
 280 >        cn: testgroup
 281 >        member: uid=test1,ou=People,dc=example,dc=com
 282
 283 Results in the following output from a search on the test1 user:
 284
 285 > # ldapsearch -LL -Y EXTERNAL -H ldapi:/// "(uid=test1)" -b dc=example,dc=com memberOf
 286 > SASL/EXTERNAL authentication started
 287 > SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
 288 > SASL SSF: 0
 289 > version: 1
 290 >
 291 > dn: uid=test1,ou=People,dc=example,dc=com
 292 > memberOf: cn=testgroup,ou=Group,dc=example,dc=com
 293
 294 Note that the {{B:memberOf}} attribute is an operational attribute, so it must be
 295 requested explicitly.
 296
 297
 298 H2: The Proxy Cache Engine
 299
 300 {{TERM:LDAP}} servers typically hold one or more subtrees of a
 301 {{TERM:DIT}}. Replica (or shadow) servers hold shadow copies of
 302 entries held by one or more master servers.  Changes are propagated
 303 from the master server to replica (slave) servers using LDAP Sync
 304 replication.  An LDAP cache is a special type of replica which holds
 305 entries corresponding to search filters instead of subtrees.
 306
 307 H3: Overview
 308
 309 The proxy cache extension of slapd is designed to improve the
 310 responsiveness of the ldap and meta backends. It handles a search
 311 request (query)
 312 by first determining whether it is contained in any cached search
 313 filter. Contained requests are answered from the proxy cache's local
 314 database. Other requests are passed on to the underlying ldap or
 315 meta backend and processed as usual.
 316
 317 E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and
 318 {{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}}
 319
 320 Correct matching rules and syntaxes are used while comparing
 321 assertions for query containment. To simplify the query containment
 322 problem, a list of cacheable "templates" (defined below) is specified
 323 at configuration time. A query is cached or answered only if it
 324 belongs to one of these templates. The entries corresponding to
 325 cached queries are stored in the proxy cache local database while
 326 its associated meta information (filter, scope, base, attributes)
 327 is stored in main memory.
 328
 329 A template is a prototype for generating LDAP search requests.
 330 Templates are described by a prototype search filter and a list of
 331 attributes which are required in queries generated from the template.
 332 The representation for prototype filter is similar to {{REF:RFC4515}},
 333 except that the assertion values are missing. Examples of prototype
 334 filters are: (sn=),(&(sn=)(givenname=)) which are instantiated by
 335 search filters (sn=Doe) and (&(sn=Doe)(givenname=John)) respectively.
 336
 337 The cache replacement policy removes the least recently used (LRU)
 338 query and entries belonging to only that query. Queries are allowed
 339 a maximum time to live (TTL) in the cache thus providing weak
 340 consistency. A background task periodically checks the cache for
 341 expired queries and removes them.
 342
 343 The Proxy Cache paper
 344 ({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides
 345 design and implementation details.
 346
 347
 348 H3: Proxy Cache Configuration
 349
 350 The cache configuration specific directives described below must
 351 appear after a {{EX:overlay proxycache}} directive within a
 352 {{EX:"database meta"}} or {{EX:database ldap}} section of
 353 the server's {{slapd.conf}}(5) file.
 354
 355 H4: Setting cache parameters
 356
 357 > proxyCache <DB> <maxentries> <nattrsets> <entrylimit> <period>
 358
 359 This directive enables proxy caching and sets general cache
 360 parameters.  The <DB> parameter specifies which underlying database
 361 is to be used to hold cached entries.  It should be set to
 362 {{EX:bdb}} or {{EX:hdb}}.  The <maxentries> parameter specifies the
 363 total number of entries which may be held in the cache.  The
 364 <nattrsets> parameter specifies the total number of attribute sets
 365 (as specified by the {{EX:proxyAttrSet}} directive) that may be
 366 defined.  The <entrylimit> parameter specifies the maximum number of
 367 entries in a cacheable query.  The <period> specifies the consistency
 368 check period (in seconds).  In each period, queries with expired
 369 TTLs are removed.
 370
 371 H4: Defining attribute sets
 372
 373 > proxyAttrset <index> <attrs...>
 374
 375 Used to associate a set of attributes to an index. Each attribute
 376 set is associated with an index number from 0 to <numattrsets>-1.
 377 These indices are used by the proxyTemplate directive to define
 378 cacheable templates.
 379
 380 H4: Specifying cacheable templates
 381
 382 > proxyTemplate <prototype_string> <attrset_index> <TTL>
 383
 384 Specifies a cacheable template and the "time to live" (in sec) <TTL>
 385 for queries belonging to the template. A template is described by
 386 its prototype filter string and set of required attributes identified
 387 by <attrset_index>.
 388
 389
 390 H4: Example
 391
 392 An example {{slapd.conf}}(5) database section for a caching server
 393 which proxies for the {{EX:"dc=example,dc=com"}} subtree held
 394 at server {{EX:ldap.example.com}}.
 395
 396 >       database        ldap
 397 >       suffix          "dc=example,dc=com"
 398 >       rootdn          "dc=example,dc=com"
 399 >       uri             ldap://ldap.example.com/dc=example%2cdc=com
 400 >       overlay proxycache
 401 >       proxycache    bdb 100000 1 1000 100
 402 >       proxyAttrset  0 mail postaladdress telephonenumber
 403 >       proxyTemplate (sn=) 0 3600
 404 >       proxyTemplate (&(sn=)(givenName=)) 0 3600
 405 >       proxyTemplate (&(departmentNumber=)(secretary=*)) 0 3600
 406 >
 407 >       cachesize 20
 408 >       directory ./testrun/db.2.a
 409 >       index       objectClass eq
 410 >       index       cn,sn,uid,mail  pres,eq,sub
 411
 412
 413 H5: Cacheable Queries
 414
 415 A LDAP search query is cacheable when its filter matches one of the
 416 templates as defined in the "proxyTemplate" statements and when it references
 417 only the attributes specified in the corresponding attribute set.
 418 In the example above the attribute set number 0 defines that only the
 419 attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
 420 proxyTemplates.
 421
 422 H5: Examples:
 423
 424 >       Filter: (&(sn=Richard*)(givenName=jack))
 425 >       Attrs: mail telephoneNumber
 426
 427     is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
 428     attributes are contained in proxyAttrset 0.
 429
 430 >       Filter: (&(sn=Richard*)(telephoneNumber))
 431 >       Attrs: givenName
 432
 433     is not cacheable, because the filter does not match the template,
 434     nor is the attribute givenName stored in the cache
 435
 436 >       Filter: (|(sn=Richard*)(givenName=jack))
 437 >       Attrs: mail telephoneNumber
 438
 439     is not cacheable, because the filter does not match the template ( logical
 440     OR "|" condition instead of logical AND "&" )
 441
 442
 443 H2: Password Policies
 444
 445
 446 H3: Overview
 447
 448 This overlay provides a variety of password control mechanisms,
 449 e.g. password aging, password reuse and duplication control, mandatory
 450 password resets, etc.
 451
 452
 453 H3: Password Policy Configuration
 454
 455
 456 H2: Referential Integrity
 457
 458
 459 H3: Overview
 460
 461 This overlay can be used with a backend database such as slapd-bdb (5)
 462 to maintain the cohesiveness of a schema which utilizes reference
 463 attributes.
 464
 465
 466 H3: Referential Integrity Configuration
 467
 468
 469 H2: Return Code
 470
 471
 472 H3: Overview
 473
 474 This overlay is useful to test the behavior of clients when
 475 server-generated erroneous and/or unusual responses occur.
 476
 477
 478 H3: Return Code Configuration
 479
 480
 481 H2: Rewrite/Remap
 482
 483
 484 H3: Overview
 485
 486 It performs basic DN/data rewrite and
 487 objectClass/attributeType mapping.
 488
 489
 490 H3: Rewrite/Remap Configuration
 491
 492
 493 H2: Sync Provider
 494
 495
 496 H3: Overview
 497
 498 This overlay implements the provider-side support for syncrepl
 499 replication, including persistent search functionality
 500
 501
 502 H3: Sync Provider Configuration
 503
 504
 505 H2: Translucent Proxy
 506
 507
 508 H3: Overview
 509
 510 This overlay can be used with a backend database such as slapd-bdb (5)
 511 to create a "translucent proxy".
 512
 513 Content of entries retrieved from a remote LDAP server can be partially
 514 overridden by the database.
 515
 516
 517 H3: Translucent Proxy Configuration
 518
 519
 520 H2: Attribute Uniqueness
 521
 522
 523 H3: Overview
 524
 525 This overlay can be used with a backend database such as slapd-bdb (5)
 526 to enforce the uniqueness of some or all attributes within a subtree.
 527
 528
 529 H3: Attribute Uniqueness Configuration
 530
 531
 532 H2: Value Sorting
 533
 534
 535 H3: Overview
 536
 537 This overlay can be used to enforce a specific order for the values
 538 of an attribute when it is returned in a search.
 539
 540
 541 H3: Value Sorting Configuration
 542
 543
 544 H2: Overlay Stacking
 545
 546
 547 H3: Overview
 548
 549
 550 H3: Example Scenarios
 551
 552
 553 H4: Samba