← Back to branch summary

~ttx/openldap/lucid-gssapi-495418

« back to all changes in this revision

Viewing changes to contrib/slapd-modules/addpartial/README

  • Committer: Bazaar Package Importer
  • Author(s): Mathias Gug
  • Date: 2008-07-10 14:45:49 UTC
  • Revision ID: james.westby@ubuntu.com-20080710144549-wck73med0e72gfyo
Tags: upstream-2.4.10
Import upstream version 2.4.10

Show diffs side-by-side

added added

removed removed

Lines of Context:
contrib/slapd-modules/addpartial/README
 
1
addpartial Overlay README
 
2
 
 
3
DESCRIPTION
 
4
    This package contains an OpenLDAP overlay called "addpartial" that 
 
5
    intercepts add requests, determines if the entry exists, determines what 
 
6
    attributes, if any, have changed, and modifies those attributes.  If the
 
7
    entry does not exist, the add request falls through and proceeds normally.
 
8
    If the entry exists but no changes have been detected, the client receives
 
9
    LDAP_SUCCESS (I suppose it is debatable what to do in this case, but this is
 
10
    the most clean for my use.  The LDAP_SUCCESS lets me know that the entry I
 
11
    sent slapd == the entry already in my slapd DB.  Perhaps this behavior
 
12
    should be configurable in the future).
 
13
 
 
14
    When a change is found, the addpartial overlay will replace all values for
 
15
    the attribute (if an attribute does not exist in the new entry but exists
 
16
    in the entry in the slapd DB, a replace will be done with an empty list of
 
17
    values).
 
18
 
 
19
    Once a modify takes place, the syncprov overlay will properly process the
 
20
    change, provided that addpartial is the first overlay to run.  Please see
 
21
    the CAVEATS for more specifics about this.
 
22
 
 
23
    The addpartial overlay makes it easy to replicate full entries to a slapd 
 
24
    instance without worrying about the differences between entries or even if
 
25
    the entry exists.  Using ldapadd to add entries, the addpartial overlay can
 
26
    compare about 500 records per second.  The intent of the addpartial overlay
 
27
    is to make it easy to replicate records from a source that is not an LDAP
 
28
    instance, such as a database.  The overlay is also useful in places where it
 
29
    is easier to create full entries rather than comparing an entry with an
 
30
    entry that must be retrieved (with ldapsearch or similar) from an existing
 
31
    slapd DB to find changes. 
 
32
 
 
33
    The addpartial overlay has been used in production since August 2004 and has
 
34
    processed millions of records without incident.
 
35
 
 
36
BUILDING
 
37
    A Makefile is included, please set your OPENLDAP_SRC directory properly.
 
38
 
 
39
INSTALLATION
 
40
    After compiling the addpartial overlay, add the following to your 
 
41
    slapd.conf:
 
42
 
 
43
    ### slapd.conf
 
44
    ...
 
45
    moduleload /path/to/addpartial-overlay.so
 
46
    ...
 
47
    # after database directive...
 
48
    # this overlay should be the last overlay in the config file to ensure that
 
49
    # it properly intercepts the add request
 
50
    overlay addpartial
 
51
    ...
 
52
    ### end slapd.conf
 
53
 
 
54
CAVEATS
 
55
    - In order to ensure that addpartial does what it needs to do, it should be
 
56
      the last overlay configured so it will run before the other overlays.
 
57
      This is especially important if you are using syncrepl, as the modify that
 
58
      addpartial does will muck with the locking that takes place in the
 
59
      syncprov overlay.