git.sur5r.net Git - openldap/blob - doc/guide/admin/overlays.sdf

   1 # Copyright 2007 The OpenLDAP Foundation, All Rights Reserved.
   2 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
   3
   4 H1: Overlays
   5
   6
   7 H2: Access Logging
   8
   9
  10 H3: Overview
  11
  12
  13 H3: Access Logging Configuration
  14
  15
  16 H2: Audit Logging
  17
  18
  19 H3: Overview
  20
  21
  22 H3: Audit Logging Configuration
  23
  24
  25 H2: Constraints
  26
  27
  28 H3: Overview
  29
  30
  31 H3: Constraint Configuration
  32
  33
  34 H2: Dynamic Directory Services
  35
  36
  37 H3: Overview
  38
  39
  40 H3: Dynamic Directory Service Configuration
  41
  42
  43 H2: Dynamic Groups
  44
  45
  46 H3: Overview
  47
  48
  49 H3: Dynamic Group Configuration
  50
  51
  52 H2: Dynamic Lists
  53
  54
  55 H3: Overview
  56
  57
  58 H3: Dynamic List Configuration
  59
  60
  61 H2: The Proxy Cache Engine
  62
  63 {{TERM:LDAP}} servers typically hold one or more subtrees of a
  64 {{TERM:DIT}}. Replica (or shadow) servers hold shadow copies of
  65 entries held by one or more master servers.  Changes are propagated
  66 from the master server to replica (slave) servers using LDAP Sync
  67 replication.  An LDAP cache is a special type of replica which holds
  68 entries corresponding to search filters instead of subtrees.
  69
  70 H3: Overview
  71
  72 The proxy cache extension of slapd is designed to improve the
  73 responseiveness of the ldap and meta backends. It handles a search
  74 request (query)
  75 by first determining whether it is contained in any cached search
  76 filter. Contained requests are answered from the proxy cache's local
  77 database. Other requests are passed on to the underlying ldap or
  78 meta backend and processed as usual.
  79
  80 E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and
  81 {{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}}
  82
  83 Correct matching rules and syntaxes are used while comparing
  84 assertions for query containment. To simplify the query containment
  85 problem, a list of cacheable "templates" (defined below) is specified
  86 at configuration time. A query is cached or answered only if it
  87 belongs to one of these templates. The entries corresponding to
  88 cached queries are stored in the proxy cache local database while
  89 its associated meta information (filter, scope, base, attributes)
  90 is stored in main memory.
  91
  92 A template is a prototype for generating LDAP search requests.
  93 Templates are described by a prototype search filter and a list of
  94 attributes which are required in queries generated from the template.
  95 The representation for prototype filter is similar to {{REF:RFC4515}},
  96 except that the assertion values are missing. Examples of prototype
  97 filters are: (sn=),(&(sn=)(givenname=)) which are instantiated by
  98 search filters (sn=Doe) and (&(sn=Doe)(givenname=John)) respectively.
  99
 100 The cache replacement policy removes the least recently used (LRU)
 101 query and entries belonging to only that query. Queries are allowed
 102 a maximum time to live (TTL) in the cache thus providing weak
 103 consistency. A background task periodically checks the cache for
 104 expired queries and removes them.
 105
 106 The Proxy Cache paper
 107 ({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides
 108 design and implementation details.
 109
 110
 111 H3: Proxy Cache Configuration
 112
 113 The cache configuration specific directives described below must
 114 appear after a {{EX:overlay proxycache}} directive within a
 115 {{EX:"database meta"}} or {{EX:database ldap}} section of
 116 the server's {{slapd.conf}}(5) file.
 117
 118 H4: Setting cache parameters
 119
 120 > proxyCache <DB> <maxentries> <nattrsets> <entrylimit> <period>
 121
 122 This directive enables proxy caching and sets general cache
 123 parameters.  The <DB> parameter specifies which underlying database
 124 is to be used to hold cached entries.  It should be set to
 125 {{EX:bdb}} or {{EX:hdb}}.  The <maxentries> parameter specifies the
 126 total number of entries which may be held in the cache.  The
 127 <nattrsets> parameter specifies the total number of attribute sets
 128 (as specified by the {{EX:proxyAttrSet}} directive) that may be
 129 defined.  The <entrylimit> parameter specifies the maximum number of
 130 entries in a cachable query.  The <period> specifies the consistency
 131 check period (in seconds).  In each period, queries with expired
 132 TTLs are removed.
 133
 134 H4: Defining attribute sets
 135
 136 > proxyAttrset <index> <attrs...>
 137
 138 Used to associate a set of attributes to an index. Each attribute
 139 set is associated with an index number from 0 to <numattrsets>-1.
 140 These indices are used by the proxyTemplate directive to define
 141 cacheable templates.
 142
 143 H4: Specifying cacheable templates
 144
 145 > proxyTemplate <prototype_string> <attrset_index> <TTL>
 146
 147 Specifies a cacheable template and the "time to live" (in sec) <TTL>
 148 for queries belonging to the template. A template is described by
 149 its prototype filter string and set of required attributes identified
 150 by <attrset_index>.
 151
 152
 153 H4: Example
 154
 155 An example {{slapd.conf}}(5) database section for a caching server
 156 which proxies for the {{EX:"dc=example,dc=com"}} subtree held
 157 at server {{EX:ldap.example.com}}.
 158
 159 >       database        ldap
 160 >       suffix          "dc=example,dc=com"
 161 >       rootdn          "dc=example,dc=com"
 162 >       uri             ldap://ldap.example.com/dc=example%2cdc=com
 163 >       overlay proxycache
 164 >       proxycache    bdb 100000 1 1000 100
 165 >       proxyAttrset  0 mail postaladdress telephonenumber
 166 >       proxyTemplate (sn=) 0 3600
 167 >       proxyTemplate (&(sn=)(givenName=)) 0 3600
 168 >       proxyTemplate (&(departmentNumber=)(secretary=*)) 0 3600
 169 >
 170 >       cachesize 20
 171 >       directory ./testrun/db.2.a
 172 >       index       objectClass eq
 173 >       index       cn,sn,uid,mail  pres,eq,sub
 174
 175
 176 H5: Cacheable Queries
 177
 178 A LDAP search query is cacheable when its filter matches one of the
 179 templates as defined in the "proxyTemplate" statements and when it references
 180 only the attributes specified in the corresponding attribute set.
 181 In the example above the attribute set number 0 defines that only the
 182 attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
 183 proxyTemplates.
 184
 185 H5: Examples:
 186
 187 >       Filter: (&(sn=Richard*)(givenName=jack))
 188 >       Attrs: mail telephoneNumber
 189
 190     is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
 191     attributes are contained in proxyAttrset 0.
 192
 193 >       Filter: (&(sn=Richard*)(telephoneNumber))
 194 >       Attrs: givenName
 195
 196     is not cacheable, because the filter does not match the template,
 197     nor is the attribute givenName stored in the cache
 198
 199 >       Filter: (|(sn=Richard*)(givenName=jack))
 200 >       Attrs: mail telephoneNumber
 201
 202     is not cacheable, because the filter does not match the template ( logical
 203     OR "|" condition instead of logical AND "&" )
 204
 205
 206 H2: Password Policies
 207
 208
 209 H3: Overview
 210
 211
 212 H3: Password Policy Configuration
 213
 214
 215 H2: Referential Integrity
 216
 217
 218 H3: Overview
 219
 220
 221 H3: Referential Integrity Configuration
 222
 223
 224 H2: Return Code
 225
 226
 227 H3: Overview
 228
 229
 230 H3: Return Code Configuration
 231
 232
 233 H2: Rewrite/Remap
 234
 235
 236 H3: Overview
 237
 238
 239 H3: Rewrite/Remap Configuration
 240
 241
 242 H2: Sync Provider
 243
 244
 245 H3: Overview
 246
 247
 248 H3: Sync Provider Configuration
 249
 250
 251 H2: Translucent Proxy
 252
 253
 254 H3: Overview
 255
 256
 257 H3: Translucent Proxy Configuration
 258
 259
 260 H2: Attribute Uniqueness
 261
 262
 263 H3: Overview
 264
 265
 266 H3: Attribute Uniqueness Configuration
 267
 268
 269 H2: Value Sorting
 270
 271
 272 H3: Overview
 273
 274
 275 H3: Value Sorting Configuration
 276
 277
 278 H2: Overlay Stacking
 279
 280
 281 H3: Overview
 282
 283
 284 H3: Example Senarios
 285
 286
 287 H4: Samba