# $OpenLDAP$
-# Copyright 2007-2008 The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 2007-2013 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Overlays
> chain-return-error TRUE
+H3: Read-Back of Chained Modifications
+
+Occasionally, applications want to read back the data that they just wrote.
+If a modification requested to a shadow server was silently chained to its
+provider, an immediate read could result in receiving data not yet synchronized.
+In those cases, clients should use the {{B:dontusecopy}} control to ensure
+they are directed to the authoritative source for that piece of data.
+
+This control usually causes a referral to the actual source of the data
+to be returned. However, when the {{slapo-chain(5)}} overlay is used,
+it intercepts the referral being returned in response to the
+{{B:dontusecopy}} control, and tries to fetch the requested data.
+
+
H3: Further Information
{{:slapo-chain(5)}}
Configuration via {{slapd.conf}}(5) would look like:
> overlay constraint
-> constraint_attribute mail regex ^[:alnum:]+@mydomain.com$
+> constraint_attribute mail regex ^[[:alnum:]]+@mydomain.com$
> constraint_attribute title uri
> ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)
> objectClass: olcOverlayConfig
> objectClass: olcConstraintConfig
> olcOverlay: constraint
-> olcConstraintAttribute: mail regex ^[:alnum:]+@mydomain.com$
+> olcConstraintAttribute: mail regex ^[[:alnum:]]+@mydomain.com$
> olcConstraintAttribute: title uri ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)
In {{F:slapd.conf}}(5):
+> include /path/to/dyngroup.schema
+> ...
> overlay dynlist
-> dynlist-attrset groupOfNames labeledURI member
+> dynlist-attrset groupOfURLs labeledURI member
++
++Note: We must include the {{F:dyngroup.schema}} file that defines the
++{{F:groupOfURLs}} objectClass used in this example.
Let's apply it to the following entry:
> cn=allusers,ou=group,dc=example,dc=com
> cn: all
-> objectClass: groupOfNames
+> objectClass: groupOfURLs
> labeledURI: ldap:///ou=people,dc=example,dc=com??one?(objectClass=inetOrgPerson)
The behavior is similar to the dynamic list configuration we had before:
-whenever an entry with the {{F:groupOfNames}} object class is retrieved, the
+whenever an entry with the {{F:groupOfURLs}} object class is retrieved, the
search specified in the {{F:labeledURI}} attribute is performed. But this time,
only the distinguished names of the results are added, and as values of the
{{F:member}} attribute.
> include /usr/share/openldap/schema/core.schema
> include /usr/share/openldap/schema/cosine.schema
-> modulepath /usr/lib/openldap
-> moduleload memberof.la
+>
> authz-regexp "gidNumber=0\\\+uidNumber=0,cn=peercred,cn=external,cn=auth"
> "cn=Manager,dc=example,dc=com"
> database bdb
H3: Proxy Cache Configuration
The cache configuration specific directives described below must
-appear after a {{EX:overlay proxycache}} directive within a
-{{EX:"database meta"}} or {{EX:database ldap}} section of
+appear after a {{EX:overlay pcache}} directive within a
+{{EX:"database meta"}} or {{EX:"database ldap"}} section of
the server's {{slapd.conf}}(5) file.
H4: Setting cache parameters
-> p
roxyCache <DB> <maxentries> <nattrsets> <entrylimit> <period>
+> p
cache <DB> <maxentries> <nattrsets> <entrylimit> <period>
This directive enables proxy caching and sets general cache
parameters. The <DB> parameter specifies which underlying database
{{EX:bdb}} or {{EX:hdb}}. The <maxentries> parameter specifies the
total number of entries which may be held in the cache. The
<nattrsets> parameter specifies the total number of attribute sets
-(as specified by the {{EX:proxyAttrSet}} directive) that may be
+(as specified by the {{EX:pcacheAttrset}} directive) that may be
defined. The <entrylimit> parameter specifies the maximum number of
entries in a cacheable query. The <period> specifies the consistency
check period (in seconds). In each period, queries with expired
H4: Defining attribute sets
-> p
roxyAttrset <index> <attrs...>
+> p
cacheAttrset <index> <attrs...>
Used to associate a set of attributes to an index. Each attribute
set is associated with an index number from 0 to <numattrsets>-1.
-These indices are used by the proxyTemplate directive to define
+These indices are used by the pcacheTemplate directive to define
cacheable templates.
H4: Specifying cacheable templates
-> p
roxyTemplate <prototype_string> <attrset_index> <TTL>
+> p
cacheTemplate <prototype_string> <attrset_index> <TTL>
Specifies a cacheable template and the "time to live" (in sec) <TTL>
for queries belonging to the template. A template is described by
by <attrset_index>.
-H4: Example
+H4: Example for slapd.conf
An example {{slapd.conf}}(5) database section for a caching server
which proxies for the {{EX:"dc=example,dc=com"}} subtree held
> suffix "dc=example,dc=com"
> rootdn "dc=example,dc=com"
> uri ldap://ldap.example.com/
-> overlay proxycache
-> proxycache bdb 100000 1 1000 100
-> proxyAttrset 0 mail postaladdress telephonenumber
-> proxyTemplate (sn=) 0 3600
-> proxyTemplate (&(sn=)(givenName=)) 0 3600
-> proxyTemplate (&(departmentNumber=)(secretary=*)) 0 3600
+> overlay pcache
+> pcache hdb 100000 1 1000 100
+> pcacheAttrset 0 mail postaladdress telephonenumber
+> pcacheTemplate (sn=) 0 3600
+> pcacheTemplate (&(sn=)(givenName=)) 0 3600
+> pcacheTemplate (&(departmentNumber=)(secretary=*)) 0 3600
>
> cachesize 20
> directory ./testrun/db.2.a
> index objectClass eq
> index cn,sn,uid,mail pres,eq,sub
+H4: Example for slapd-config
+
+The same example as a LDIF file for back-config for a caching server
+which proxies for the {{EX:"dc=example,dc=com"}} subtree held
+at server {{EX:ldap.example.com}}.
+
+> dn: olcDatabase={2}ldap,cn=config
+> objectClass: olcDatabaseConfig
+> objectClass: olcLDAPConfig
+> olcDatabase: {2}ldap
+> olcSuffix: dc=example,dc=com
+> olcRootDN: dc=example,dc=com
+> olcDbURI: "ldap://ldap.example.com"
+>
+> dn: olcOverlay={0}pcache,olcDatabase={2}ldap,cn=config
+> objectClass: olcOverlayConfig
+> objectClass: olcPcacheConfig
+> olcOverlay: {0}pcache
+> olcPcache: hdb 100000 1 1000 100
+> olcPcacheAttrset: 0 mail postalAddress telephoneNumber
+> olcPcacheTemplate: "(sn=)" 0 3600 0 0 0
+> olcPcacheTemplate: "(&(sn=)(givenName=))" 0 3600 0 0 0
+> olcPcacheTemplate: "(&(departmentNumber=)(secretary=))" 0 3600
+>
+> dn: olcDatabase={0}hdb,olcOverlay={0}pcache,olcDatabase={2}ldap,cn=config
+> objectClass: olcHdbConfig
+> objectClass: olcPcacheDatabase
+> olcDatabase: {0}hdb
+> olcDbDirectory: ./testrun/db.2.a
+> olcDbCacheSize: 20
+> olcDbIndex: objectClass eq
+> olcDbIndex: cn,sn,uid,mail pres,eq,sub
+
H5: Cacheable Queries
A LDAP search query is cacheable when its filter matches one of the
-templates as defined in the "proxyTemplate" statements and when it references
+templates as defined in the "pcacheTemplate" statements and when it references
only the attributes specified in the corresponding attribute set.
In the example above the attribute set number 0 defines that only the
attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
-proxyTemplates.
+pcacheTemplates.
H5: Examples:
> Attrs: mail telephoneNumber
is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
- attributes are contained in proxyAttrset 0.
+ attributes are contained in pcacheAttrset 0.
> Filter: (&(sn=Richard*)(telephoneNumber))
> Attrs: givenName
that object is applied.
Please see {{slapo-ppolicy(5)}} for complete explanations of features and discussion of
- "Password Management Issues" at {{URL:http://www.connexitor.com/forums/viewtopic.php?f=6&t=25}}
+ "Password Management Issues" at {{URL:http://www.symas.com/blog/?page_id=66}}
H3: Further Information
would be a single member in the group: {{F:cn=admin,dc=example,dc=com}}. This is the
{{F:refint_nothing}} parameter kicking into action so that the schema is not violated.
+The {{rootdn}} must be set for the database as refint runs as the {{rootdn}} to gain access to
+make its updates. The {{rootpw}} does not need to be set.
H3: Further Information
H3: Overview
-This overlay implements the provider-side support for syncrepl
-replication, including persistent search functionality
-
+This overlay implements the provider-side support for the LDAP Content Synchronization
+({{REF:RFC4533}}) as well as syncrepl replication support, including persistent search functionality.
H3: Sync Provider Configuration
+There is very little configuration needed for this overlay, in fact for many situations merely loading
+the overlay will suffice.
+
+However, because the overlay creates a contextCSN attribute in the root entry of the database which is
+updated for every write operation performed against the database and only updated in memory, it is
+recommended to configure a checkpoint so that the contextCSN is written into the underlying database to
+minimize recovery time after an unclean shutdown:
+
+> overlay syncprov
+> syncprov-checkpoint 100 10
+
+For every 100 operations or 10 minutes, which ever is sooner, the contextCSN will be checkpointed.
+
+The four configuration directives available are {{B:syncprov-checkpoint}}, {{B:syncprov-sessionlog}},
+{{B:syncprov-nopresent}} and {{B:syncprov-reloadhint}} which are covered in the man page discussing
+various other scenarios where this overlay can be used.
H3: Further Information
-{{:slapo-syncprov(5)}}
+The {{:slapo-syncprov(5)}} man page and the {{SECT:Configuring the different replication types}} section
H2: Translucent Proxy
> pidfile ./slapd.pid
> argsfile ./slapd.args
>
-> modulepath /usr/local/libexec/openldap
-> moduleload back_bdb.la
-> moduleload back_ldap.la
-> moduleload translucent.la
->
> database bdb
> suffix "dc=suretecsystems,dc=com"
> rootdn "cn=trans,dc=suretecsystems,dc=com"
H3: Overview
-This overlay can be used with a backend database such as slapd-bdb (5)
+This overlay can be used with a backend database such as {{slapd-bdb(5)}}
to enforce the uniqueness of some or all attributes within a subtree.
H3: Attribute Uniqueness Configuration
+This overlay is only effective on new data from the point the overlay is enabled. To
+check uniqueness for existing data, you can export and import your data again via the
+LDAP Add operation, which will not be suitable for large amounts of data, unlike {{B:slapcat}}.
+
+For the following example, if uniqueness were enforced for the {{B:mail}} attribute,
+the subtree would be searched for any other records which also have a {{B:mail}} attribute
+containing the same value presented with an {{B:add}}, {{B:modify}} or {{B:modrdn}} operation
+which are unique within the configured scope. If any are found, the request is rejected.
+
+Note: If no attributes are specified, for example {{B:ldap:///??sub?}}, then the URI applies to all non-operational attributes. However,
+the keyword {{B:ignore}} can be specified to exclude certain non-operational attributes.
+
+To search at the base dn of the current backend database ensuring uniqueness of the {{B:mail}}
+attribute, we simply add the following configuration:
+
+> overlay unique
+> unique_uri ldap:///?mail?sub?
+
+For an existing entry of:
+
+> dn: cn=gavin,dc=suretecsystems,dc=com
+> objectClass: top
+> objectClass: inetorgperson
+> cn: gavin
+> sn: henry
+> mail: ghenry@suretecsystems.com
+
+and we then try to add a new entry of:
+
+> dn: cn=robert,dc=suretecsystems,dc=com
+> objectClass: top
+> objectClass: inetorgperson
+> cn: robert
+> sn: jones
+> mail: ghenry@suretecsystems.com
+
+would result in an error like so:
+
+> adding new entry "cn=robert,dc=example,dc=com"
+> ldap_add: Constraint violation (19)
+> additional info: some attributes not unique
+
+The overlay can have multiple URIs specified within a domain, allowing complex
+selections of objects and also have multiple {{B:unique_uri}} statements or
+{{B:olcUniqueURI}} attributes which will create independent domains.
+
+For more information and details about the {{B:strict}} and {{B:ignore}} keywords,
+please see the {{:slapo-unique(5)}} man page.
H3: Further Information
projects / openldap / blobdiff