1# OpenLDAP: pkg/openldap-guide/admin/overlays.sdf,v 1.8.2.30 2010/04/15 18:25:42 quanah Exp 2# Copyright 2007-2010 The OpenLDAP Foundation, All Rights Reserved. 3# COPYING RESTRICTIONS APPLY, see COPYRIGHT. 4 5H1: Overlays 6 7Overlays are software components that provide hooks to functions analogous to 8those provided by backends, which can be stacked on top of the backend calls 9and as callbacks on top of backend responses to alter their behavior. 10 11Overlays may be compiled statically into {{slapd}}, or when module support 12is enabled, they may be dynamically loaded. Most of the overlays 13are only allowed to be configured on individual databases. 14 15Some can be stacked on the {{EX:frontend}} as well, for global use. This means that 16they can be executed after a request is parsed and validated, but right before the 17appropriate database is selected. The main purpose is to affect operations 18regardless of the database they will be handled by, and, in some cases, 19to influence the selection of the database by massaging the request DN. 20 21Essentially, overlays represent a means to: 22 23 * customize the behavior of existing backends without changing the backend 24 code and without requiring one to write a new custom backend with 25 complete functionality 26 * write functionality of general usefulness that can be applied to 27 different backend types 28 29When using {{slapd.conf}}(5), overlays that are configured before any other 30databases are considered global, as mentioned above. In fact they are implicitly 31stacked on top of the {{EX:frontend}} database. They can also be explicitly 32configured as such: 33 34> database frontend 35> overlay <overlay name> 36 37Overlays are usually documented by separate specific man pages in section 5; 38the naming convention is 39 40> slapo-<overlay name> 41 42All distributed core overlays have a man page. Feel free to contribute to any, 43if you think there is anything missing in describing the behavior of the component 44and the implications of all the related configuration directives. 45 46Official overlays are located in 47 48> servers/slapd/overlays/ 49 50That directory also contains the file slapover.txt, which describes the 51rationale of the overlay implementation, and may serve as a guideline for the 52development of custom overlays. 53 54Contribware overlays are located in 55 56> contrib/slapd-modules/<overlay name>/ 57 58along with other types of run-time loadable components; they are officially 59distributed, but not maintained by the project. 60 61All the current overlays in OpenLDAP are listed and described in detail in the 62following sections. 63 64 65H2: Access Logging 66 67 68H3: Overview 69 70This overlay can record accesses to a given backend database on another 71database. 72 73This allows all of the activity on a given database to be reviewed using arbitrary 74LDAP queries, instead of just logging to local flat text files. Configuration 75options are available for selecting a subset of operation types to log, and to 76automatically prune older log records from the logging database. Log records 77are stored with audit schema to assure their readability whether viewed as LDIF 78or in raw form. 79 80It is also used for {{SECT:delta-syncrepl replication}} 81 82H3: Access Logging Configuration 83 84The following is a basic example that implements Access Logging: 85 86> database bdb 87> suffix dc=example,dc=com 88> ... 89> overlay accesslog 90> logdb cn=log 91> logops writes reads 92> logold (objectclass=person) 93> 94> database bdb 95> suffix cn=log 96> ... 97> index reqStart eq 98> access to * 99> by dn.base="cn=admin,dc=example,dc=com" read 100 101The following is an example used for {{SECT:delta-syncrepl replication}}: 102 103> database hdb 104> suffix cn=accesslog 105> directory /usr/local/var/openldap-accesslog 106> rootdn cn=accesslog 107> index default eq 108> index entryCSN,objectClass,reqEnd,reqResult,reqStart 109 110Accesslog overlay definitions for the primary db 111 112> database bdb 113> suffix dc=example,dc=com 114> ... 115> overlay accesslog 116> logdb cn=accesslog 117> logops writes 118> logsuccess TRUE 119> # scan the accesslog DB every day, and purge entries older than 7 days 120> logpurge 07+00:00 01+00:00 121 122An example search result against {{B:cn=accesslog}} might look like: 123 124> [ghenry@suretec ghenry]# ldapsearch -x -b cn=accesslog 125> # extended LDIF 126> # 127> # LDAPv3 128> # base <cn=accesslog> with scope subtree 129> # filter: (objectclass=*) 130> # requesting: ALL 131> # 132> 133> # accesslog 134> dn: cn=accesslog 135> objectClass: auditContainer 136> cn: accesslog 137> 138> # 20080110163829.000004Z, accesslog 139> dn: reqStart=20080110163829.000004Z,cn=accesslog 140> objectClass: auditModify 141> reqStart: 20080110163829.000004Z 142> reqEnd: 20080110163829.000005Z 143> reqType: modify 144> reqSession: 196696 145> reqAuthzID: cn=admin,dc=suretecsystems,dc=com 146> reqDN: uid=suretec-46022f8$,ou=Users,dc=suretecsystems,dc=com 147> reqResult: 0 148> reqMod: sambaPwdCanChange:- ###CENSORED### 149> reqMod: sambaPwdCanChange:+ ###CENSORED### 150> reqMod: sambaNTPassword:- ###CENSORED### 151> reqMod: sambaNTPassword:+ ###CENSORED### 152> reqMod: sambaPwdLastSet:- ###CENSORED### 153> reqMod: sambaPwdLastSet:+ ###CENSORED### 154> reqMod: entryCSN:= 20080110163829.095157Z#000000#000#000000 155> reqMod: modifiersName:= cn=admin,dc=suretecsystems,dc=com 156> reqMod: modifyTimestamp:= 20080110163829Z 157> 158> # search result 159> search: 2 160> result: 0 Success 161> 162> # numResponses: 3 163> # numEntries: 2 164 165 166H3: Further Information 167 168{{slapo-accesslog(5)}} and the {{SECT:delta-syncrepl replication}} section. 169 170 171H2: Audit Logging 172 173The Audit Logging overlay can be used to record all changes on a given backend database to a specified log file. 174 175H3: Overview 176 177If the need arises whereby changes need to be logged as standard LDIF, then the auditlog overlay {{B:slapo-auditlog (5)}} 178can be used. Full examples are available in the man page {{B:slapo-auditlog (5)}} 179 180H3: Audit Logging Configuration 181 182If the directory is running vi {{F:slapd.d}}, then the following LDIF could be used to add the overlay to the overlay list 183in {{B:cn=config}} and set what file the {{TERM:LDIF}} gets logged to (adjust to suit) 184 185> dn: olcOverlay=auditlog,olcDatabase={1}hdb,cn=config 186> changetype: add 187> objectClass: olcOverlayConfig 188> objectClass: olcAuditLogConfig 189> olcOverlay: auditlog 190> olcAuditlogFile: /tmp/auditlog.ldif 191 192 193In this example for testing, we are logging changes to {{F:/tmp/auditlog.ldif}} 194 195A typical {{TERM:LDIF}} file created by {{B:slapo-auditlog(5)}} would look like: 196 197> # add 1196797576 dc=suretecsystems,dc=com cn=admin,dc=suretecsystems,dc=com 198> dn: dc=suretecsystems,dc=com 199> changetype: add 200> objectClass: dcObject 201> objectClass: organization 202> dc: suretecsystems 203> o: Suretec Systems Ltd. 204> structuralObjectClass: organization 205> entryUUID: 1606f8f8-f06e-1029-8289-f0cc9d81e81a 206> creatorsName: cn=admin,dc=suretecsystems,dc=com 207> modifiersName: cn=admin,dc=suretecsystems,dc=com 208> createTimestamp: 20051123130912Z 209> modifyTimestamp: 20051123130912Z 210> entryCSN: 20051123130912.000000Z#000001#000#000000 211> auditContext: cn=accesslog 212> # end add 1196797576 213> 214> # add 1196797577 dc=suretecsystems,dc=com cn=admin,dc=suretecsystems,dc=com 215> dn: ou=Groups,dc=suretecsystems,dc=com 216> changetype: add 217> objectClass: top 218> objectClass: organizationalUnit 219> ou: Groups 220> structuralObjectClass: organizationalUnit 221> entryUUID: 160aaa2a-f06e-1029-828a-f0cc9d81e81a 222> creatorsName: cn=admin,dc=suretecsystems,dc=com 223> modifiersName: cn=admin,dc=suretecsystems,dc=com 224> createTimestamp: 20051123130912Z 225> modifyTimestamp: 20051123130912Z 226> entryCSN: 20051123130912.000000Z#000002#000#000000 227> # end add 1196797577 228 229 230H3: Further Information 231 232{{:slapo-auditlog(5)}} 233 234 235H2: Chaining 236 237 238H3: Overview 239 240The chain overlay provides basic chaining capability to the underlying 241database. 242 243What is chaining? It indicates the capability of a DSA to follow referrals on 244behalf of the client, so that distributed systems are viewed as a single 245virtual DSA by clients that are otherwise unable to "chase" (i.e. follow) 246referrals by themselves. 247 248The chain overlay is built on top of the ldap backend; it is compiled by 249default when {{B:--enable-ldap}}. 250 251 252H3: Chaining Configuration 253 254In order to demonstrate how this overlay works, we shall discuss a typical 255scenario which might be one master server and three Syncrepl slaves. 256 257On each replica, add this near the top of the {{slapd.conf}}(5) file 258(global), before any database definitions: 259 260> overlay chain 261> chain-uri "ldap://ldapmaster.example.com" 262> chain-idassert-bind bindmethod="simple" 263> binddn="cn=Manager,dc=example,dc=com" 264> credentials="<secret>" 265> mode="self" 266> chain-tls start 267> chain-return-error TRUE 268 269Add this below your {{syncrepl}} statement: 270 271> updateref "ldap://ldapmaster.example.com/" 272 273The {{B:chain-tls}} statement enables TLS from the slave to the ldap master. 274The DITs are exactly the same between these machines, therefore whatever user 275bound to the slave will also exist on the master. If that DN does not have 276update privileges on the master, nothing will happen. 277 278You will need to restart the slave after these {{slapd.conf}} changes. 279Then, if you are using {{loglevel stats}} (256), you can monitor an 280{{ldapmodify}} on the slave and the master. (If you're using {{cn=config}} 281no restart is required.) 282 283Now start an {{ldapmodify}} on the slave and watch the logs. You should expect 284something like: 285 286> 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) 287> Sep 6 09:27:25 slave1 slapd[29274]: conn=11 op=0 STARTTLS 288> Sep 6 09:27:25 slave1 slapd[29274]: conn=11 op=0 RESULT oid= err=0 text= 289> Sep 6 09:27:25 slave1 slapd[29274]: conn=11 fd=31 TLS established tls_ssf=256 ssf=256 290> Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=1 BIND dn="uid=user1,ou=people,dc=example,dc=com" method=128 291> 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 292> Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=1 RESULT tag=97 err=0 text= 293> Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD dn="uid=user1,ou=People,dc=example,dc=com" 294> Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD attr=mail 295> Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 RESULT tag=103 err=0 text= 296> Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=3 UNBIND 297> Sep 6 09:27:28 slave1 slapd[29274]: conn=11 fd=31 closed 298> Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: LDAP_RES_SEARCH_ENTRY(LDAP_SYNC_MODIFY) 299> Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_search (0) 300> Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: uid=user1,ou=People,dc=example,dc=com 301> Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_modify (0) 302 303And on the master you will see this: 304 305> Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 PROXYAUTHZ dn="uid=user1,ou=people,dc=example,dc=com" 306> Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD dn="uid=user1,ou=People,dc=example,dc=com" 307> Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD attr=mail 308> Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 RESULT tag=103 err=0 text= 309 310Note: You can clearly see the PROXYAUTHZ line on the master, indicating the 311proper identity assertion for the update on the master. Also note the slave 312immediately receiving the Syncrepl update from the master. 313 314H3: Handling Chaining Errors 315 316By default, if chaining fails, the original referral is returned to the client 317under the assumption that the client might want to try and follow the referral. 318 319With the following directive however, if the chaining fails at the provider 320side, the actual error is returned to the client. 321 322> chain-return-error TRUE 323 324 325H3: Read-Back of Chained Modifications 326 327Occasionally, applications want to read back the data that they just wrote. 328If a modification requested to a shadow server was silently chained to its 329producer, an immediate read could result in receiving data not yet synchronized. 330In those cases, clients should use the {{B:dontusecopy}} control to ensure 331they are directed to the authoritative source for that piece of data. 332 333This control usually causes a referral to the actual source of the data 334to be returned. However, when the {{slapo-chain(5)}} overlay is used, 335it intercepts the referral being returned in response to the 336{{B:dontusecopy}} control, and tries to fetch the requested data. 337 338 339H3: Further Information 340 341{{:slapo-chain(5)}} 342 343 344H2: Constraints 345 346 347H3: Overview 348 349This overlay enforces a regular expression constraint on all values 350of specified attributes during an LDAP modify request that contains add or modify 351commands. It is used to enforce a more rigorous syntax when the underlying attribute 352syntax is too general. 353 354 355H3: Constraint Configuration 356 357Configuration via {{slapd.conf}}(5) would look like: 358 359> overlay constraint 360> constraint_attribute mail regex ^[[:alnum:]]+@mydomain.com$ 361> constraint_attribute title uri 362> ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog) 363 364A specification like the above would reject any {{mail}} attribute which did not 365look like {{<alpha-numeric string>@mydomain.com}}. 366 367It would also reject any title attribute whose values were not listed in the 368title attribute of any {{titleCatalog}} entries in the given scope. 369 370An example for use with {{cn=config}}: 371 372> dn: olcOverlay=constraint,olcDatabase={1}hdb,cn=config 373> changetype: add 374> objectClass: olcOverlayConfig 375> objectClass: olcConstraintConfig 376> olcOverlay: constraint 377> olcConstraintAttribute: mail regex ^[[:alnum:]]+@mydomain.com$ 378> olcConstraintAttribute: title uri ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog) 379 380 381H3: Further Information 382 383{{:slapo-constraint(5)}} 384 385 386H2: Dynamic Directory Services 387 388 389H3: Overview 390 391The {{dds}} overlay to {{slapd}}(8) implements dynamic objects as per {{REF:RFC2589}}. 392The name {{dds}} stands for Dynamic Directory Services. It allows to define 393dynamic objects, characterized by the {{dynamicObject}} objectClass. 394 395Dynamic objects have a limited lifetime, determined by a time-to-live (TTL) 396that can be refreshed by means of a specific refresh extended operation. This 397operation allows to set the Client Refresh Period (CRP), namely the period 398between refreshes that is required to preserve the dynamic object from expiration. 399The expiration time is computed by adding the requested TTL to the current time. 400When dynamic objects reach the end of their lifetime without being further 401refreshed, they are automatically {{deleted}}. There is no guarantee of immediate 402deletion, so clients should not count on it. 403 404H3: Dynamic Directory Service Configuration 405 406A usage of dynamic objects might be to implement dynamic meetings; in this case, 407all the participants to the meeting are allowed to refresh the meeting object, 408but only the creator can delete it (otherwise it will be deleted when the TTL expires). 409 410If we add the overlay to an example database, specifying a Max TTL of 1 day, a 411min of 10 seconds, with a default TTL of 1 hour. We'll also specify an interval 412of 120 (less than 60s might be too small) seconds between expiration checks and a 413tolerance of 5 second (lifetime of a dynamic object will be {{entryTtl + tolerance}}). 414 415> overlay dds 416> dds-max-ttl 1d 417> dds-min-ttl 10s 418> dds-default-ttl 1h 419> dds-interval 120s 420> dds-tolerance 5s 421 422and add an index: 423 424> entryExpireTimestamp 425 426Creating a meeting is as simple as adding the following: 427 428> dn: cn=OpenLDAP Documentation Meeting,ou=Meetings,dc=example,dc=com 429> objectClass: groupOfNames 430> objectClass: dynamicObject 431> cn: OpenLDAP Documentation Meeting 432> member: uid=ghenry,ou=People,dc=example,dc=com 433> member: uid=hyc,ou=People,dc=example,dc=com 434 435H4: Dynamic Directory Service ACLs 436 437Allow users to start a meeting and to join it; restrict refresh to the {{member}}; 438restrict delete to the creator: 439 440> access to attrs=userPassword 441> by self write 442> by * read 443> 444> access to dn.base="ou=Meetings,dc=example,dc=com" 445> attrs=children 446> by users write 447> 448> access to dn.onelevel="ou=Meetings,dc=example,dc=com" 449> attrs=entry 450> by dnattr=creatorsName write 451> by * read 452> 453> access to dn.onelevel="ou=Meetings,dc=example,dc=com" 454> attrs=participant 455> by dnattr=creatorsName write 456> by users selfwrite 457> by * read 458> 459> access to dn.onelevel="ou=Meetings,dc=example,dc=com" 460> attrs=entryTtl 461> by dnattr=member manage 462> by * read 463 464In simple terms, the user who created the {{OpenLDAP Documentation Meeting}} can add new attendees, 465refresh the meeting using (basically complete control): 466 467> ldapexop -x -H ldap://ldaphost "refresh" "cn=OpenLDAP Documentation Meeting,ou=Meetings,dc=example,dc=com" "120" -D "uid=ghenry,ou=People,dc=example,dc=com" -W 468 469Any user can join the meeting, but not add another attendee, but they can refresh the meeting. The ACLs above are quite straight forward to understand. 470 471 472H3: Further Information 473 474{{:slapo-dds(5)}} 475 476 477H2: Dynamic Groups 478 479 480H3: Overview 481 482This overlay extends the Compare operation to detect 483members of a dynamic group. This overlay is now deprecated 484as all of its functions are available using the 485{{SECT:Dynamic Lists}} overlay. 486 487 488H3: Dynamic Group Configuration 489 490 491H2: Dynamic Lists 492 493 494H3: Overview 495 496This overlay allows expansion of dynamic groups and lists. Instead of having the 497group members or list attributes hard coded, this overlay allows us to define 498an LDAP search whose results will make up the group or list. 499 500H3: Dynamic List Configuration 501 502This module can behave both as a dynamic list and dynamic group, depending on 503the configuration. The syntax is as follows: 504 505> overlay dynlist 506> dynlist-attrset <group-oc> <URL-ad> [member-ad] 507 508The parameters to the {{F:dynlist-attrset}} directive have the following meaning: 509* {{F:<group-oc>}}: specifies which object class triggers the subsequent LDAP search. 510Whenever an entry with this object class is retrieved, the search is performed. 511* {{F:<URL-ad>}}: is the name of the attribute which holds the search URI. It 512has to be a subtype of {{F:labeledURI}}. The attributes and values present in 513the search result are added to the entry unless {{F:member-ad}} is used (see 514below). 515* {{F:member-ad}}: if present, changes the overlay behavior into a dynamic group. 516Instead of inserting the results of the search in the entry, the distinguished name 517of the results are added as values of this attribute. 518 519Here is an example which will allow us to have an email alias which automatically 520expands to all user's emails according to our LDAP filter: 521 522In {{slapd.conf}}(5): 523 524> overlay dynlist 525> dynlist-attrset nisMailAlias labeledURI 526 527This means that whenever an entry which has the {{F:nisMailAlias}} object class is 528retrieved, the search specified in the {{F:labeledURI}} attribute is performed. 529 530Let's say we have this entry in our directory: 531 532> cn=all,ou=aliases,dc=example,dc=com 533> cn: all 534> objectClass: nisMailAlias 535> labeledURI: ldap:///ou=People,dc=example,dc=com?mail?one?(objectClass=inetOrgPerson) 536 537If this entry is retrieved, the search specified in {{F:labeledURI}} will be 538performed and the results will be added to the entry just as if they have always 539been there. In this case, the search filter selects all entries directly 540under {{F:ou=People}} that have the {{F:inetOrgPerson}} object class and retrieves 541the {{F:mail}} attribute, if it exists. 542 543This is what gets added to the entry when we have two users under {{F:ou=People}} 544that match the filter: 545!import "allmail-en.png"; align="center"; title="Dynamic list for email aliases" 546FT[align="Center"] Figure X.Y: Dynamic List for all emails 547 548The configuration for a dynamic group is similar. Let's see an example which would 549automatically populate an {{F:allusers}} group with all the user accounts in the 550directory. 551 552In {{F:slapd.conf}}(5): 553 554> include /path/to/dyngroup.schema 555> ... 556> overlay dynlist 557> dynlist-attrset groupOfURLs labeledURI member 558+ 559+Note: We must include the {{F:dyngroup.schema}} file that defines the 560+{{F:groupOfURLs}} objectClass used in this example. 561 562Let's apply it to the following entry: 563 564> cn=allusers,ou=group,dc=example,dc=com 565> cn: all 566> objectClass: groupOfURLs 567> labeledURI: ldap:///ou=people,dc=example,dc=com??one?(objectClass=inetOrgPerson) 568 569The behavior is similar to the dynamic list configuration we had before: 570whenever an entry with the {{F:groupOfURLs}} object class is retrieved, the 571search specified in the {{F:labeledURI}} attribute is performed. But this time, 572only the distinguished names of the results are added, and as values of the 573{{F:member}} attribute. 574 575This is what we get: 576!import "allusersgroup-en.png"; align="center"; title="Dynamic group for all users" 577FT[align="Center"] Figure X.Y: Dynamic Group for all users 578 579Note that a side effect of this scheme of dynamic groups is that the members 580need to be specified as full DNs. So, if you are planning in using this for 581{{F:posixGroup}}s, be sure to use RFC2307bis and some attribute which can hold 582distinguished names. The {{F:memberUid}} attribute used in the {{F:posixGroup}} 583object class can hold only names, not DNs, and is therefore not suitable for 584dynamic groups. 585 586 587H3: Further Information 588 589{{:slapo-dynlist(5)}} 590 591 592H2: Reverse Group Membership Maintenance 593 594H3: Overview 595 596In some scenarios, it may be desirable for a client to be able to determine 597which groups an entry is a member of, without performing an additional search. 598Examples of this are applications using the {{TERM:DIT}} for access control 599based on group authorization. 600 601The {{B:memberof}} overlay updates an attribute (by default {{B:memberOf}}) whenever 602changes occur to the membership attribute (by default {{B:member}}) of entries of the 603objectclass (by default {{B:groupOfNames}}) configured to trigger updates. 604 605Thus, it provides maintenance of the list of groups an entry is a member of, 606when usual maintenance of groups is done by modifying the members on the group 607entry. 608 609H3: Member Of Configuration 610 611The typical use of this overlay requires just enabling the overlay for a 612specific database. For example, with the following minimal slapd.conf: 613 614> include /usr/share/openldap/schema/core.schema 615> include /usr/share/openldap/schema/cosine.schema 616> 617> authz-regexp "gidNumber=0\\\+uidNumber=0,cn=peercred,cn=external,cn=auth" 618> "cn=Manager,dc=example,dc=com" 619> database bdb 620> suffix "dc=example,dc=com" 621> rootdn "cn=Manager,dc=example,dc=com" 622> rootpw secret 623> directory /var/lib/ldap2.4 624> checkpoint 256 5 625> index objectClass eq 626> index uid eq,sub 627> 628> overlay memberof 629 630adding the following ldif: 631 632> cat memberof.ldif 633> dn: dc=example,dc=com 634> objectclass: domain 635> dc: example 636> 637> dn: ou=Group,dc=example,dc=com 638> objectclass: organizationalUnit 639> ou: Group 640> 641> dn: ou=People,dc=example,dc=com 642> objectclass: organizationalUnit 643> ou: People 644> 645> dn: uid=test1,ou=People,dc=example,dc=com 646> objectclass: account 647> uid: test1 648> 649> dn: cn=testgroup,ou=Group,dc=example,dc=com 650> objectclass: groupOfNames 651> cn: testgroup 652> member: uid=test1,ou=People,dc=example,dc=com 653 654Results in the following output from a search on the test1 user: 655 656> # ldapsearch -LL -Y EXTERNAL -H ldapi:/// "(uid=test1)" -b dc=example,dc=com memberOf 657> SASL/EXTERNAL authentication started 658> SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth 659> SASL SSF: 0 660> version: 1 661> 662> dn: uid=test1,ou=People,dc=example,dc=com 663> memberOf: cn=testgroup,ou=Group,dc=example,dc=com 664 665Note that the {{B:memberOf}} attribute is an operational attribute, so it must be 666requested explicitly. 667 668 669H3: Further Information 670 671{{:slapo-memberof(5)}} 672 673 674H2: The Proxy Cache Engine 675 676{{TERM:LDAP}} servers typically hold one or more subtrees of a 677{{TERM:DIT}}. Replica (or shadow) servers hold shadow copies of 678entries held by one or more master servers. Changes are propagated 679from the master server to replica (slave) servers using LDAP Sync 680replication. An LDAP cache is a special type of replica which holds 681entries corresponding to search filters instead of subtrees. 682 683H3: Overview 684 685The proxy cache extension of slapd is designed to improve the 686responsiveness of the ldap and meta backends. It handles a search 687request (query) 688by first determining whether it is contained in any cached search 689filter. Contained requests are answered from the proxy cache's local 690database. Other requests are passed on to the underlying ldap or 691meta backend and processed as usual. 692 693E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and 694{{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}} 695 696Correct matching rules and syntaxes are used while comparing 697assertions for query containment. To simplify the query containment 698problem, a list of cacheable "templates" (defined below) is specified 699at configuration time. A query is cached or answered only if it 700belongs to one of these templates. The entries corresponding to 701cached queries are stored in the proxy cache local database while 702its associated meta information (filter, scope, base, attributes) 703is stored in main memory. 704 705A template is a prototype for generating LDAP search requests. 706Templates are described by a prototype search filter and a list of 707attributes which are required in queries generated from the template. 708The representation for prototype filter is similar to {{REF:RFC4515}}, 709except that the assertion values are missing. Examples of prototype 710filters are: (sn=),(&(sn=)(givenname=)) which are instantiated by 711search filters (sn=Doe) and (&(sn=Doe)(givenname=John)) respectively. 712 713The cache replacement policy removes the least recently used (LRU) 714query and entries belonging to only that query. Queries are allowed 715a maximum time to live (TTL) in the cache thus providing weak 716consistency. A background task periodically checks the cache for 717expired queries and removes them. 718 719The Proxy Cache paper 720({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides 721design and implementation details. 722 723 724H3: Proxy Cache Configuration 725 726The cache configuration specific directives described below must 727appear after a {{EX:overlay proxycache}} directive within a 728{{EX:"database meta"}} or {{EX:database ldap}} section of 729the server's {{slapd.conf}}(5) file. 730 731H4: Setting cache parameters 732 733> proxyCache <DB> <maxentries> <nattrsets> <entrylimit> <period> 734 735This directive enables proxy caching and sets general cache 736parameters. The <DB> parameter specifies which underlying database 737is to be used to hold cached entries. It should be set to 738{{EX:bdb}} or {{EX:hdb}}. The <maxentries> parameter specifies the 739total number of entries which may be held in the cache. The 740<nattrsets> parameter specifies the total number of attribute sets 741(as specified by the {{EX:proxyAttrSet}} directive) that may be 742defined. The <entrylimit> parameter specifies the maximum number of 743entries in a cacheable query. The <period> specifies the consistency 744check period (in seconds). In each period, queries with expired 745TTLs are removed. 746 747H4: Defining attribute sets 748 749> proxyAttrset <index> <attrs...> 750 751Used to associate a set of attributes to an index. Each attribute 752set is associated with an index number from 0 to <numattrsets>-1. 753These indices are used by the proxyTemplate directive to define 754cacheable templates. 755 756H4: Specifying cacheable templates 757 758> proxyTemplate <prototype_string> <attrset_index> <TTL> 759 760Specifies a cacheable template and the "time to live" (in sec) <TTL> 761for queries belonging to the template. A template is described by 762its prototype filter string and set of required attributes identified 763by <attrset_index>. 764 765 766H4: Example 767 768An example {{slapd.conf}}(5) database section for a caching server 769which proxies for the {{EX:"dc=example,dc=com"}} subtree held 770at server {{EX:ldap.example.com}}. 771 772> database ldap 773> suffix "dc=example,dc=com" 774> rootdn "dc=example,dc=com" 775> uri ldap://ldap.example.com/ 776> overlay proxycache 777> proxycache bdb 100000 1 1000 100 778> proxyAttrset 0 mail postaladdress telephonenumber 779> proxyTemplate (sn=) 0 3600 780> proxyTemplate (&(sn=)(givenName=)) 0 3600 781> proxyTemplate (&(departmentNumber=)(secretary=*)) 0 3600 782> 783> cachesize 20 784> directory ./testrun/db.2.a 785> index objectClass eq 786> index cn,sn,uid,mail pres,eq,sub 787 788 789H5: Cacheable Queries 790 791A LDAP search query is cacheable when its filter matches one of the 792templates as defined in the "proxyTemplate" statements and when it references 793only the attributes specified in the corresponding attribute set. 794In the example above the attribute set number 0 defines that only the 795attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following 796proxyTemplates. 797 798H5: Examples: 799 800> Filter: (&(sn=Richard*)(givenName=jack)) 801> Attrs: mail telephoneNumber 802 803 is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its 804 attributes are contained in proxyAttrset 0. 805 806> Filter: (&(sn=Richard*)(telephoneNumber)) 807> Attrs: givenName 808 809 is not cacheable, because the filter does not match the template, 810 nor is the attribute givenName stored in the cache 811 812> Filter: (|(sn=Richard*)(givenName=jack)) 813> Attrs: mail telephoneNumber 814 815 is not cacheable, because the filter does not match the template ( logical 816 OR "|" condition instead of logical AND "&" ) 817 818 819H3: Further Information 820 821{{:slapo-pcache(5)}} 822 823 824H2: Password Policies 825 826 827H3: Overview 828 829This overlay follows the specifications contained in the draft RFC titled 830draft-behera-ldap-password-policy-09. While the draft itself is expired, it has 831been implemented in several directory servers, including slapd. Nonetheless, 832it is important to note that it is a draft, meaning that it is subject to change 833and is a work-in-progress. 834 835The key abilities of the password policy overlay are as follows: 836 837* Enforce a minimum length for new passwords 838* Make sure passwords are not changed too frequently 839* Cause passwords to expire, provide warnings before they need to be changed, and allow a fixed number of 'grace' logins to allow them to be changed after they have expired 840* Maintain a history of passwords to prevent password re-use 841* Prevent password guessing by locking a password for a specified period of time after repeated authentication failures 842* Force a password to be changed at the next authentication 843* Set an administrative lock on an account 844* Support multiple password policies on a default or a per-object basis. 845* Perform arbitrary quality checks using an external loadable module. This is a non-standard extension of the draft RFC. 846 847 848H3: Password Policy Configuration 849 850Instantiate the module in the database where it will be used, after adding the 851new ppolicy schema and loading the ppolicy module. The following example shows 852the ppolicy module being added to the database that handles the naming 853context "dc=example,dc=com". In this example we are also specifying the DN of 854a policy object to use if none other is specified in a user's object. 855 856> database bdb 857> suffix "dc=example,dc=com" 858> [...additional database configuration directives go here...] 859> 860> overlay ppolicy 861> ppolicy_default "cn=default,ou=policies,dc=example,dc=com" 862 863 864Now we need a container for the policy objects. In our example the password 865policy objects are going to be placed in a section of the tree called 866"ou=policies,dc=example,dc=com": 867 868> dn: ou=policies,dc=example,dc=com 869> objectClass: organizationalUnit 870> objectClass: top 871> ou: policies 872 873 874The default policy object that we are creating defines the following policies: 875 876* The user is allowed to change his own password. Note that the directory ACLs for this attribute can also affect this ability (pwdAllowUserChange: TRUE). 877* The name of the password attribute is "userPassword" (pwdAttribute: userPassword). Note that this is the only value that is accepted by OpenLDAP for this attribute. 878* The server will check the syntax of the password. If the server is unable to check the syntax (i.e., it was hashed or otherwise encoded by the client) it will return an error refusing the password (pwdCheckQuality: 2). 879* When a client includes the Password Policy Request control with a bind request, the server will respond with a password expiration warning if it is going to expire in ten minutes or less (pwdExpireWarning: 600). The warnings themselves are returned in a Password Policy Response control. 880* When the password for a DN has expired, the server will allow five additional "grace" logins (pwdGraceAuthNLimit: 5). 881* The server will maintain a history of the last five passwords that were used for a DN (pwdInHistory: 5). 882* The server will lock the account after the maximum number of failed bind attempts has been exceeded (pwdLockout: TRUE). 883* When the server has locked an account, the server will keep it locked until an administrator unlocks it (pwdLockoutDuration: 0) 884* The server will reset its failed bind count after a period of 30 seconds. 885* Passwords will not expire (pwdMaxAge: 0). 886* Passwords can be changed as often as desired (pwdMinAge: 0). 887* Passwords must be at least 5 characters in length (pwdMinLength: 5). 888* The password does not need to be changed at the first bind or when the administrator has reset the password (pwdMustChange: FALSE) 889* The current password does not need to be included with password change requests (pwdSafeModify: FALSE) 890* The server will only allow five failed binds in a row for a particular DN (pwdMaxFailure: 5). 891 892 893The actual policy would be: 894 895> dn: cn=default,ou=policies,dc=example,dc=com 896> cn: default 897> objectClass: pwdPolicy 898> objectClass: person 899> objectClass: top 900> pwdAllowUserChange: TRUE 901> pwdAttribute: userPassword 902> pwdCheckQuality: 2 903> pwdExpireWarning: 600 904> pwdFailureCountInterval: 30 905> pwdGraceAuthNLimit: 5 906> pwdInHistory: 5 907> pwdLockout: TRUE 908> pwdLockoutDuration: 0 909> pwdMaxAge: 0 910> pwdMaxFailure: 5 911> pwdMinAge: 0 912> pwdMinLength: 5 913> pwdMustChange: FALSE 914> pwdSafeModify: FALSE 915> sn: dummy value 916 917You can create additional policy objects as needed. 918 919 920There are two ways password policy can be applied to individual objects: 921 9221. The pwdPolicySubentry in a user's object - If a user's object has a 923pwdPolicySubEntry attribute specifying the DN of a policy object, then 924the policy defined by that object is applied. 925 9262. Default password policy - If there is no specific pwdPolicySubentry set 927for an object, and the password policy module was configured with the DN of a 928default policy object and if that object exists, then the policy defined in 929that object is applied. 930 931Please see {{slapo-ppolicy(5)}} for complete explanations of features and discussion of 932 "Password Management Issues" at {{URL:http://www.symas.com/blog/?page_id=66}} 933 934 935H3: Further Information 936 937{{:slapo-ppolicy(5)}} 938 939 940H2: Referential Integrity 941 942 943H3: Overview 944 945This overlay can be used with a backend database such as slapd-bdb(5) 946to maintain the cohesiveness of a schema which utilizes reference 947attributes. 948 949Whenever a {{modrdn}} or {{delete}} is performed, that is, when an entry's DN 950is renamed or an entry is removed, the server will search the directory for 951references to this DN (in selected attributes: see below) and update them 952accordingly. If it was a {{delete}} operation, the reference is deleted. If it 953was a {{modrdn}} operation, then the reference is updated with the new DN. 954 955For example, a very common administration task is to maintain group membership 956lists, specially when users are removed from the directory. When an 957user account is deleted or renamed, all groups this user is a member of have to be 958updated. LDAP administrators usually have scripts for that. But we can use the 959{{F:refint}} overlay to automate this task. In this example, if the user is 960removed from the directory, the overlay will take care to remove the user from 961all the groups he/she was a member of. No more scripting for this. 962 963H3: Referential Integrity Configuration 964 965The configuration for this overlay is as follows: 966 967> overlay refint 968> refint_attributes <attribute [attribute ...]> 969> refint_nothing <string> 970 971* {{F:refint_attributes}}: this parameter specifies a space separated list of 972attributes which will have the referential integrity maintained. When an entry is 973removed or has its DN renamed, the server will do an internal search for any of the 974{{F:refint_attributes}} that point to the affected DN and update them accordingly. IMPORTANT: 975the attributes listed here must have the {{F:distinguishedName}} syntax, that is, 976hold DNs as values. 977* {{F:refint_nothing}}: some times, while trying to maintain the referential 978integrity, the server has to remove the last attribute of its kind from an 979entry. This may be prohibited by the schema: for example, the 980{{F:groupOfNames}} object class requires at least one member. In these cases, 981the server will add the attribute value specified in {{F:refint_nothing}} 982to the entry. 983 984To illustrate this overlay, we will use the group membership scenario. 985 986In {{F:slapd.conf}}: 987 988> overlay refint 989> refint_attributes member 990> refint_nothing "cn=admin,dc=example,dc=com" 991 992This configuration tells the overlay to maintain the referential integrity of the {{F:member}} 993attribute. This attribute is used in the {{F:groupOfNames}} object class which always needs 994a member, so we add the {{F:refint_nothing}} directive to fill in the group with a standard 995member should all the members vanish. 996 997If we have the following group membership, the refint overlay will 998automatically remove {{F:john}} from the group if his entry is removed from the 999directory: 1000 1001!import "refint.png"; align="center"; title="Group membership" 1002FT[align="Center"] Figure X.Y: Maintaining referential integrity in groups 1003 1004Notice that if we rename ({{F:modrdn}}) the {{F:john}} entry to, say, {{F:jsmith}}, the refint 1005overlay will also rename the reference in the {{F:member}} attribute, so the group membership 1006stays correct. 1007 1008If we removed all users from the directory who are a member of this group, then the end result 1009would be a single member in the group: {{F:cn=admin,dc=example,dc=com}}. This is the 1010{{F:refint_nothing}} parameter kicking into action so that the schema is not violated. 1011 1012 1013H3: Further Information 1014 1015{{:slapo-refint(5)}} 1016 1017 1018H2: Return Code 1019 1020 1021H3: Overview 1022 1023This overlay is useful to test the behavior of clients when 1024server-generated erroneous and/or unusual responses occur, 1025for example; error codes, referrals, excessive response times and so on. 1026 1027This would be classed as a debugging tool whilst developing client software 1028or additional Overlays. 1029 1030For detailed information, please see the {{slapo-retcode(5)}} man page. 1031 1032 1033H3: Return Code Configuration 1034 1035The retcode overlay utilizes the "return code" schema described in the man page. 1036This schema is specifically designed for use with this overlay and is not intended 1037to be used otherwise. 1038 1039Note: The necessary schema is loaded automatically by the overlay. 1040 1041An example configuration might be: 1042 1043> overlay retcode 1044> retcode-parent "ou=RetCodes,dc=example,dc=com" 1045> include ./retcode.conf 1046> 1047> retcode-item "cn=Unsolicited" 0x00 unsolicited="0" 1048> retcode-item "cn=Notice of Disconnect" 0x00 unsolicited="1.3.6.1.4.1.1466.20036" 1049> retcode-item "cn=Pre-disconnect" 0x34 flags="pre-disconnect" 1050> retcode-item "cn=Post-disconnect" 0x34 flags="post-disconnect" 1051 1052Note: {{retcode.conf}} can be found in the openldap source at: {{F:tests/data/retcode.conf}} 1053 1054An excerpt of a {{F:retcode.conf}} would be something like: 1055 1056> retcode-item "cn=success" 0x00 1057> 1058> retcode-item "cn=success w/ delay" 0x00 sleeptime=2 1059> 1060> retcode-item "cn=operationsError" 0x01 1061> retcode-item "cn=protocolError" 0x02 1062> retcode-item "cn=timeLimitExceeded" 0x03 op=search 1063> retcode-item "cn=sizeLimitExceeded" 0x04 op=search 1064> retcode-item "cn=compareFalse" 0x05 op=compare 1065> retcode-item "cn=compareTrue" 0x06 op=compare 1066> retcode-item "cn=authMethodNotSupported" 0x07 1067> retcode-item "cn=strongAuthNotSupported" 0x07 text="same as authMethodNotSupported" 1068> retcode-item "cn=strongAuthRequired" 0x08 1069> retcode-item "cn=strongerAuthRequired" 0x08 text="same as strongAuthRequired" 1070 1071Please see {{F:tests/data/retcode.conf}} for a complete {{F:retcode.conf}} 1072 1073 1074H3: Further Information 1075 1076{{:slapo-retcode(5)}} 1077 1078 1079H2: Rewrite/Remap 1080 1081 1082H3: Overview 1083 1084It performs basic DN/data rewrite and objectClass/attributeType mapping. Its 1085usage is mostly intended to provide virtual views of existing data either 1086remotely, in conjunction with the proxy backend described in {{slapd-ldap(5)}}, 1087or locally, in conjunction with the relay backend described in {{slapd-relay(5)}}. 1088 1089This overlay is extremely configurable and advanced, therefore recommended 1090reading is the {{slapo-rwm(5)}} man page. 1091 1092 1093H3: Rewrite/Remap Configuration 1094 1095 1096H3: Further Information 1097 1098{{:slapo-rwm(5)}} 1099 1100 1101H2: Sync Provider 1102 1103 1104H3: Overview 1105 1106This overlay implements the provider-side support for the LDAP Content Synchronization 1107({{REF:RFC4533}}) as well as syncrepl replication support, including persistent search functionality. 1108 1109H3: Sync Provider Configuration 1110 1111There is very little configuration needed for this overlay, in fact for many situations merely loading 1112the overlay will suffice. 1113 1114However, because the overlay creates a contextCSN attribute in the root entry of the database which is 1115updated for every write operation performed against the database and only updated in memory, it is 1116recommended to configure a checkpoint so that the contextCSN is written into the underlying database to 1117minimize recovery time after an unclean shutdown: 1118 1119> overlay syncprov 1120> syncprov-checkpoint 100 10 1121 1122For every 100 operations or 10 minutes, which ever is sooner, the contextCSN will be checkpointed. 1123 1124The four configuration directives available are {{B:syncprov-checkpoint}}, {{B:syncprov-sessionlog}}, 1125{{B:syncprov-nopresent}} and {{B:syncprov-reloadhint}} which are covered in the man page discussing 1126various other scenarios where this overlay can be used. 1127 1128H3: Further Information 1129 1130The {{:slapo-syncprov(5)}} man page and the {{SECT:Configuring the different replication types}} section 1131 1132 1133H2: Translucent Proxy 1134 1135 1136H3: Overview 1137 1138This overlay can be used with a backend database such as {{:slapd-bdb}}(5) 1139to create a "translucent proxy". 1140 1141Entries retrieved from a remote LDAP server may have some or all attributes 1142overridden, or new attributes added, by entries in the local database before 1143being presented to the client. 1144 1145A search operation is first populated with entries from the remote LDAP server, 1146the attributes of which are then overridden with any attributes defined in the 1147local database. Local overrides may be populated with the add, modify, and 1148modrdn operations, the use of which is restricted to the root user of the 1149translucent local database. 1150 1151A compare operation will perform a comparison with attributes defined in the 1152local database record (if any) before any comparison is made with data in the 1153remote database. 1154 1155 1156H3: Translucent Proxy Configuration 1157 1158There are various options available with this overlay, but for this example we 1159will demonstrate adding new attributes to a remote entry and also searching 1160against these newly added local attributes. For more information about overriding remote 1161entries and search configuration, please see {{:slapo-translucent(5)}} 1162 1163Note: The Translucent Proxy overlay will disable schema checking in the local 1164database, so that an entry consisting of overlay attributes need not adhere 1165 to the complete schema. 1166 1167First we configure the overlay in the normal manner: 1168 1169> include /usr/local/etc/openldap/schema/core.schema 1170> include /usr/local/etc/openldap/schema/cosine.schema 1171> include /usr/local/etc/openldap/schema/nis.schema 1172> include /usr/local/etc/openldap/schema/inetorgperson.schema 1173> 1174> pidfile ./slapd.pid 1175> argsfile ./slapd.args 1176> 1177> database bdb 1178> suffix "dc=suretecsystems,dc=com" 1179> rootdn "cn=trans,dc=suretecsystems,dc=com" 1180> rootpw secret 1181> directory ./openldap-data 1182> 1183> index objectClass eq 1184> 1185> overlay translucent 1186> translucent_local carLicense 1187> 1188> uri ldap://192.168.X.X:389 1189> lastmod off 1190> acl-bind binddn="cn=admin,dc=suretecsystems,dc=com" credentials="blahblah" 1191 1192You will notice the overlay directive and a directive to say what attribute we 1193want to be able to search against in the local database. We must also load the 1194ldap backend which will connect to the remote directory server. 1195 1196Now we take an example LDAP group: 1197 1198> # itsupport, Groups, suretecsystems.com 1199> dn: cn=itsupport,ou=Groups,dc=suretecsystems,dc=com 1200> objectClass: posixGroup 1201> objectClass: sambaGroupMapping 1202> cn: itsupport 1203> gidNumber: 1000 1204> sambaSID: S-1-5-21-XXX 1205> sambaGroupType: 2 1206> displayName: itsupport 1207> memberUid: ghenry 1208> memberUid: joebloggs 1209 1210and create an LDIF file we can use to add our data to the local database, using 1211 some pretty strange choices of new attributes for demonstration purposes: 1212 1213> [ghenry@suretec test_configs]$ cat test-translucent-add.ldif 1214> dn: cn=itsupport,ou=Groups,dc=suretecsystems,dc=com 1215> businessCategory: frontend-override 1216> carLicense: LIVID 1217> employeeType: special 1218> departmentNumber: 9999999 1219> roomNumber: 41L-535 1220 1221Searching against the proxy gives: 1222 1223> [ghenry@suretec test_configs]$ ldapsearch -x -H ldap://127.0.0.1:9001 "(cn=itsupport)" 1224> # itsupport, Groups, OxObjects, suretecsystems.com 1225> dn: cn=itsupport,ou=Groups,ou=OxObjects,dc=suretecsystems,dc=com 1226> objectClass: posixGroup 1227> objectClass: sambaGroupMapping 1228> cn: itsupport 1229> gidNumber: 1003 1230> SAMBASID: S-1-5-21-XXX 1231> SAMBAGROUPTYPE: 2 1232> displayName: itsupport 1233> memberUid: ghenry 1234> memberUid: joebloggs 1235> roomNumber: 41L-535 1236> departmentNumber: 9999999 1237> employeeType: special 1238> carLicense: LIVID 1239> businessCategory: frontend-override 1240 1241Here we can see that the 5 new attributes are added to the remote entry before 1242being returned to the our client. 1243 1244Because we have configured a local attribute to search against: 1245 1246> overlay translucent 1247> translucent_local carLicense 1248 1249we can also search for that to return the completely fabricated entry: 1250 1251> ldapsearch -x -H ldap://127.0.0.1:9001 (carLicense=LIVID) 1252 1253This is an extremely feature because you can then extend a remote directory server 1254locally and also search against the local entries. 1255 1256Note: Because the translucent overlay does not perform any DN rewrites, the local 1257 and remote database instances must have the same suffix. Other configurations 1258will probably fail with No Such Object and other errors 1259 1260H3: Further Information 1261 1262{{:slapo-translucent(5)}} 1263 1264 1265H2: Attribute Uniqueness 1266 1267 1268H3: Overview 1269 1270This overlay can be used with a backend database such as {{slapd-bdb(5)}} 1271to enforce the uniqueness of some or all attributes within a subtree. 1272 1273 1274H3: Attribute Uniqueness Configuration 1275 1276This overlay is only effective on new data from the point the overlay is enabled. To 1277check uniqueness for existing data, you can export and import your data again via the 1278LDAP Add operation, which will not be suitable for large amounts of data, unlike {{B:slapcat}}. 1279 1280For the following example, if uniqueness were enforced for the {{B:mail}} attribute, 1281the subtree would be searched for any other records which also have a {{B:mail}} attribute 1282containing the same value presented with an {{B:add}}, {{B:modify}} or {{B:modrdn}} operation 1283which are unique within the configured scope. If any are found, the request is rejected. 1284 1285Note: If no attributes are specified, for example {{B:ldap:///??sub?}}, then the URI applies to all non-operational attributes. However, 1286the keyword {{B:ignore}} can be specified to exclude certain non-operational attributes. 1287 1288To search at the base dn of the current backend database ensuring uniqueness of the {{B:mail}} 1289attribute, we simply add the following configuration: 1290 1291> overlay unique 1292> unique_uri ldap:///?mail?sub? 1293 1294For an existing entry of: 1295 1296> dn: cn=gavin,dc=suretecsystems,dc=com 1297> objectClass: top 1298> objectClass: inetorgperson 1299> cn: gavin 1300> sn: henry 1301> mail: ghenry@suretecsystems.com 1302 1303and we then try to add a new entry of: 1304 1305> dn: cn=robert,dc=suretecsystems,dc=com 1306> objectClass: top 1307> objectClass: inetorgperson 1308> cn: robert 1309> sn: jones 1310> mail: ghenry@suretecsystems.com 1311 1312would result in an error like so: 1313 1314> adding new entry "cn=robert,dc=example,dc=com" 1315> ldap_add: Constraint violation (19) 1316> additional info: some attributes not unique 1317 1318The overlay can have multiple URIs specified within a domain, allowing complex 1319selections of objects and also have multiple {{B:unique_uri}} statements or 1320{{B:olcUniqueURI}} attributes which will create independent domains. 1321 1322For more information and details about the {{B:strict}} and {{B:ignore}} keywords, 1323please see the {{:slapo-unique(5)}} man page. 1324 1325H3: Further Information 1326 1327{{:slapo-unique(5)}} 1328 1329 1330H2: Value Sorting 1331 1332 1333H3: Overview 1334 1335The Value Sorting overlay can be used with a backend database to sort the 1336values of specific multi-valued attributes within a subtree. The sorting occurs 1337whenever the attributes are returned in a search response. 1338 1339H3: Value Sorting Configuration 1340 1341Sorting can be specified in ascending or descending order, using either numeric 1342or alphanumeric sort methods. Additionally, a "weighted" sort can be specified, 1343 which uses a numeric weight prepended to the attribute values. 1344 1345The weighted sort is always performed in ascending order, but may be combined 1346with the other methods for values that all have equal weights. The weight is 1347specified by prepending an integer weight {<weight>} in front of each value 1348of the attribute for which weighted sorting is desired. This weighting factor 1349is stripped off and never returned in search results. 1350 1351Here are a few examples: 1352 1353> loglevel sync stats 1354> 1355> database hdb 1356> suffix "dc=suretecsystems,dc=com" 1357> directory /usr/local/var/openldap-data 1358> 1359> ...... 1360> 1361> overlay valsort 1362> valsort-attr memberUid ou=Groups,dc=suretecsystems,dc=com alpha-ascend 1363 1364For example, ascend: 1365 1366> # sharedemail, Groups, suretecsystems.com 1367> dn: cn=sharedemail,ou=Groups,dc=suretecsystems,dc=com 1368> objectClass: posixGroup 1369> objectClass: top 1370> cn: sharedemail 1371> gidNumber: 517 1372> memberUid: admin 1373> memberUid: dovecot 1374> memberUid: laura 1375> memberUid: suretec 1376 1377For weighted, we change our data to: 1378 1379> # sharedemail, Groups, suretecsystems.com 1380> dn: cn=sharedemail,ou=Groups,dc=suretecsystems,dc=com 1381> objectClass: posixGroup 1382> objectClass: top 1383> cn: sharedemail 1384> gidNumber: 517 1385> memberUid: {4}admin 1386> memberUid: {2}dovecot 1387> memberUid: {1}laura 1388> memberUid: {3}suretec 1389 1390and change the config to: 1391 1392> overlay valsort 1393> valsort-attr memberUid ou=Groups,dc=suretecsystems,dc=com weighted 1394 1395Searching now results in: 1396 1397> # sharedemail, Groups, OxObjects, suretecsystems.com 1398> dn: cn=sharedemail,ou=Groups,ou=OxObjects,dc=suretecsystems,dc=com 1399> objectClass: posixGroup 1400> objectClass: top 1401> cn: sharedemail 1402> gidNumber: 517 1403> memberUid: laura 1404> memberUid: dovecot 1405> memberUid: suretec 1406> memberUid: admin 1407 1408 1409H3: Further Information 1410 1411{{:slapo-valsort(5)}} 1412 1413 1414H2: Overlay Stacking 1415 1416 1417H3: Overview 1418 1419Overlays can be stacked, which means that more than one overlay 1420can be instantiated for each database, or for the {{EX:frontend}}. 1421As a consequence, each overlays function is called, if defined, 1422when overlay execution is invoked. 1423Multiple overlays are executed in reverse order (as a stack) 1424with respect to their definition in slapd.conf (5), or with respect 1425to their ordering in the config database, as documented in slapd-config (5). 1426 1427 1428H3: Example Scenarios 1429 1430 1431H4: Samba 1432