dsdb: Add comments explaining the limitations of our current backlink behaviour

BUG: https://bugzilla.samba.org/show_bug.cgi?id=13418

Signed-off-by: Andrew Bartlett <abartlet@samba.org>
Reviewed-by: Tim Beale <timbeale@catalyst.net.nz>

Autobuild-User(master): Andrew Bartlett <abartlet@samba.org>
Autobuild-Date(master): Tue Oct 30 10:32:51 CET 2018 on sn-devel-144

(cherry picked from commit 852e1db12b0afa04a738c03bb2609c084fe96a7f)

Autobuild-User(v4-8-test): Karolin Seeger <kseeger@samba.org>
Autobuild-Date(v4-8-test): Mon Nov  5 14:28:49 CET 2018 on sn-devel-144

2 files changed, 35 insertions, 7 deletions

diff --git a/source4/dsdb/samdb/ldb_modules/linked_attributes.c b/source4/dsdb/samdb/ldb_modules/linked_attributes.c
index c6beb25e58b..c3f1a1484ba 100644
--- a/source4/dsdb/samdb/ldb_modules/linked_attributes.c
+++ b/source4/dsdb/samdb/ldb_modules/linked_attributes.c
@@ -25,7 +25,23 @@
  *
  *  Component: ldb linked_attributes module
  *
- *  Description: Module to ensure linked attribute pairs remain in sync
+ *  Description: Module to ensure linked attribute pairs (i.e. forward-links
+ *  and backlinks) remain in sync.
+ *
+ *  Backlinks are 'plain' links (without extra metadata). When the link target
+ *  object is modified (e.g. renamed), we use the backlinks to keep the link
+ *  source object updated. Note there are some cases where we can't do this:
+ *    - one-way links, which don't have a corresponding backlink
+ *    - two-way deactivated links, i.e. when a user is removed from a group,
+ *      the forward 'member' link still exists (but is inactive), however, the
+ *      'memberOf' backlink is deleted.
+ *  In these cases, we can end up with a dangling forward link which is
+ *  incorrect (i.e. the target has been renamed or deleted). We have dbcheck
+ *  rules to detect and fix this, and cope otherwise by filtering at runtime
+ *  (i.e. in the extended_dn module).
+ *
+ *  See also repl_meta_data.c, which handles updating links for deleted
+ *  objects, as well as link changes received from another DC.
  *
  *  Author: Andrew Bartlett
  */
diff --git a/source4/dsdb/samdb/ldb_modules/repl_meta_data.c b/source4/dsdb/samdb/ldb_modules/repl_meta_data.c
index 5bdc57366da..c2eafd0a521 100644
--- a/source4/dsdb/samdb/ldb_modules/repl_meta_data.c
+++ b/source4/dsdb/samdb/ldb_modules/repl_meta_data.c
@@ -4367,6 +4367,10 @@ static int replmd_delete_internals(struct ldb_module *module, struct ldb_request
 	     - preserved if in above list, or is rDN
 	  - remove all linked attribs from this object
 	  - remove all links from other objects to this object
+	    (note we use the backlinks to do this, so we won't find one-way
+	     links that still point to this object, or deactivated two-way
+	     links, i.e. 'member' after the user has been removed from the
+	     group)
 	  - add lastKnownParent
 	  - update replPropertyMetaData?
 
@@ -4488,12 +4492,12 @@ static int replmd_delete_internals(struct ldb_module *module, struct ldb_request
 
 			if (sa->linkID & 1) {
 				/*
-				  we have a backlink in this object
-				  that needs to be removed. We're not
-				  allowed to remove it directly
-				  however, so we instead setup a
-				  modify to delete the corresponding
-				  forward link
+				 * we have a backlink in this object
+				 * that needs to be removed. We're not
+				 * allowed to remove it directly
+				 * however, so we instead setup a
+				 * modify to delete the corresponding
+				 * forward link
 				 */
 				ret = replmd_delete_remove_link(module, schema,
 								replmd_private,
@@ -7626,6 +7630,14 @@ static int replmd_delete_link_value(struct ldb_module *module,
 	/* if the existing link is active, remove its backlink */
 	if (is_active) {
 
+		/*
+		 * NOTE WELL: After this we will never (at runtime) be
+		 * able to find this forward link (for instant
+		 * removal) if/when the link target is deleted.
+		 *
+		 * We have dbcheck rules to cover this and cope otherwise
+		 * by filtering at runtime (i.e. in the extended_dn module).
+		 */
 		ret = replmd_add_backlink(module, replmd_private, schema,
 					  src_obj_dn, target_guid, false,
 					  attr, NULL);