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