From: Kurt Zeilenga Date: Sat, 8 Dec 2001 07:35:48 +0000 (+0000) Subject: Replication notes X-Git-Tag: LDBM_PRE_GIANT_RWLOCK~707 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=a250bc7890571aaa5d8b5469a0ea92a533ac12bc;p=openldap Replication notes written by Ganesan Rajagopal --- diff --git a/doc/devel/replication-notes.txt b/doc/devel/replication-notes.txt new file mode 100644 index 0000000000..c8b1ae9163 --- /dev/null +++ b/doc/devel/replication-notes.txt @@ -0,0 +1,67 @@ +Written by Ganesan Rajagopal and placed in the public +domain. + +Replication in OpenLDAP +----------------------- + +Please read "Section 10. Replication with slurpd" in the OpenLDAP guide for +an overview and configuration of single-master replication. This document +describes the internals of the replication mechanism. + +slapd/repl.c contains routines add_replica_info() and +add_replica_suffix(). add_replica_info() adds a new host to the list of +replicas for a backend. add_replica_info() returns a number for the +replica. add_replica_suffix() must then be called with the replica number to +add a suffix that is hosted on this replica. add_replica_info() and add_replica_suffix() do not lock the +replog_mutex. + +Replicas are specified in the slapd.conf file. When slapd/config.c sees a +"replica" line in slapd.conf, it calls add_replica_info() with the host +specified in the "host=" directive and then calls add_replica_suffix() with +the replica number and and the suffix specified in the "suffix=" +directive. + +slapd writes out a replication log file containing LDIF change records for +each configured replica for a suffix. The change records are generated for +add, modify, delete and modrdn operations. A function called replog() is +called at the end of the routines do_add (slapd/add.c), +do_modify(slapd/modify.c), do_delete(slapd/delete.c) and +do_modrdn(slapd/modrnd.c) to write out the change records. + +In master/slave replication, updates are not allowed on slave +replicas. Therefore replog() is not called if the suffix is configured with +a updatedn (which indicates that this is a slave replica), instead a +referral is returned back to the client. If multi-master replication is +enabled, replog() is always called whenever any of the above updates happen +unless the dn which is making the change is the updatedn. When the dn making +the change is the same as the updatedn, it is assumed that this entry is +being replicated by a slurpd instance on another host. (Note: For this +reason, the updatedn must not be a "regular" admin/user object in +multi-master replication). + +The function replog() in slapd/repl.c generates the actual change +records. Each change record is preceded by the list of replicas to which +this change record needs to be replicated, the time when this change +happened and the dn this change applies to. The pseudo code for replog() is +follows + +1. Check that a replog exists. +2. Lock the replog mutex. +3. Open and lock the replog file. +4. Normalize the dn for the entry and write out a "replica:" entry for each + replica with a matching suffix. +5. Write out the the timestamp and the dn for the entry. +6. Depending on the type of change, write out an appropriate changetype + record. +7. Close the replication log +8. Unlock the replog mutex + +slurpd has a file manager routine (function fm()) which watches for any +change in the replication log. Whenever fm() detects a change in the +replication log it locks the log, appends the records to slurpd's private +copy of the replication log and truncates the log. See the slurpd/DESIGN +file for a description of how slurpd works. + +slapd can be configured to write out a replication log even if no replicas +are configured. In this case the administrator has to truncate the +replication log manually (under a lock!).