git.sur5r.net Git - openldap/blob - servers/slurpd/NOTES

   1 Written by Ganesan Rajagopal <rganesan@debian.org> and placed in the public
   2 domain.
   3
   4 Replication in OpenLDAP
   5 -----------------------
   6
   7 Please read "Section 10. Replication with slurpd" in the OpenLDAP guide for
   8 an overview and configuration of single-master replication. This document
   9 describes the internals of the replication mechanism.
  10
  11 slapd/repl.c contains routines add_replica_info() and
  12 add_replica_suffix(). add_replica_info() adds a new host to the list of
  13 replicas for a backend. add_replica_info() returns a number for the
  14 replica. add_replica_suffix() must then be called with the replica number to
  15 add a suffix that is hosted on this replica. add_replica_info() and add_replica_suffix() do not lock the
  16 replog_mutex.
  17
  18 Replicas are specified in the slapd.conf file. When slapd/config.c sees a
  19 "replica" line in slapd.conf, it calls add_replica_info() with the host
  20 specified in the "host=" directive and then calls add_replica_suffix() with
  21 the replica number and and the suffix specified in the "suffix="
  22 directive.
  23
  24 slapd writes out a replication log file containing LDIF change records for
  25 each configured replica for a suffix. The change records are generated for
  26 add, modify, delete and modrdn operations. A function called replog() is
  27 called at the end of the routines do_add (slapd/add.c),
  28 do_modify(slapd/modify.c), do_delete(slapd/delete.c) and
  29 do_modrdn(slapd/modrnd.c) to write out the change records.
  30
  31 In master/slave replication, updates are not allowed on slave
  32 replicas. Therefore replog() is not called if the suffix is configured with
  33 a updatedn (which indicates that this is a slave replica), instead a
  34 referral is returned back to the client. If multi-master replication is
  35 enabled, replog() is always called whenever any of the above updates happen
  36 unless the dn which is making the change is the updatedn. When the dn making
  37 the change is the same as the updatedn, it is assumed that this entry is
  38 being replicated by a slurpd instance on another host. (Note: For this
  39 reason, the updatedn must not be a "regular" admin/user object in
  40 multi-master replication).
  41
  42 The function replog() in slapd/repl.c generates the actual change
  43 records. Each change record is preceded by the list of replicas to which
  44 this change record needs to be replicated, the time when this change
  45 happened and the dn this change applies to. The pseudo code for replog() is
  46 follows
  47
  48 1. Check that a replog exists.
  49 2. Lock the replog mutex.
  50 3. Open and lock the replog file.
  51 4. Normalize the dn for the entry and write out a "replica:" entry for each
  52    replica with a matching suffix.
  53 5. Write out the the timestamp and the dn for the entry.
  54 6. Depending on the type of change, write out an appropriate changetype
  55    record.
  56 7. Close the replication log
  57 8. Unlock the replog mutex
  58
  59 slurpd has a file manager routine (function fm()) which watches for any
  60 change in the replication log. Whenever fm() detects a change in the
  61 replication log it locks the log, appends the records to slurpd's private
  62 copy of the replication log and truncates the log. See the slurpd/DESIGN
  63 file for a description of how slurpd works.
  64
  65 slapd can be configured to write out a replication log even if no replicas
  66 are configured. In this case the administrator has to truncate the
  67 replication log manually (under a lock!).