git.sur5r.net Git - openldap/blob - 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 addpartial overlay will write changes to the
  20     replog (using the slap_replog_cb).  If you are using syncrepl for
  21     replication, the syncprov overlay will properly process the change, provided
  22     that addpartial is the first overlay to run.  Please see the CAVEATS for
  23     more specifics about this.
  24
  25     The addpartial overlay makes it easy to replicate full entries to a slapd
  26     instance without worrying about the differences between entries or even if
  27     the entry exists.  Using ldapadd to add entries, the addpartial overlay can
  28     compare about 500 records per second.  The intent of the addpartial overlay
  29     is to make it easy to replicate records from a source that is not an LDAP
  30     instance, such as a database.  The overlay is also useful in places where it
  31     is easier to create full entries rather than comparing an entry with an
  32     entry that must be retrieved (with ldapsearch or similar) from an existing
  33     slapd DB to find changes.
  34
  35     The addpartial overlay has been used in production since August 2004 and has
  36     processed millions of records without incident.
  37
  38 BUILDING
  39     A Makefile is included, please set your OPENLDAP_SRC directory properly.
  40
  41 INSTALLATION
  42     After compiling the addpartial overlay, add the following to your
  43     slapd.conf:
  44
  45     ### slapd.conf
  46     ...
  47     moduleload /path/to/addpartial-overlay.so
  48     ...
  49     # after database directive...
  50     # this overlay should be the last overlay in the config file to ensure that
  51     # it properly intercepts the add request
  52     overlay addpartial
  53     ...
  54     ### end slapd.conf
  55
  56 CAVEATS
  57     - In order to ensure that addpartial does what it needs to do, it should be
  58       the last overlay configured so it will run before the other overlays.
  59       This is especially important if you are using syncrepl, as the modify that
  60       addpartial does will muck with the locking that takes place in the
  61       syncprov overlay.