clusterer/clusterer_controller: enforce use_controller vs module-load consistency

Two startup sanity checks for a previously silent misconfiguration:

- clusterer_controller is only meaningful when the clusterer module has
  use_controller=1 (the global switch that pre-creates the controller-managed
  cluster stubs, sets each one's controller_managed flag so they never touch
  the DB, and arms the guard that stops the controller from hijacking a native
  cluster of the same id). If use_controller=0 there is no controller-managed
  cluster and those safety mechanisms are off, so mod_init now FAILS (refuse to
  start) rather than driving clusters clusterer never authorised. Hybrid setups
  keep use_controller=1 - only the per-cluster kind differs - so this never
  trips them.

- The mirror case, use_controller=1 but no clusterer_controller module bound
  the controller API, logs an ERROR at clusterer child_init (the pre-created
  controller-managed stubs would never obtain an identity). clusterer does NOT
  abort here: its native/hybrid clusters still work; only the controller-stub
  clusters are dead.

Plumbing: the clusterer_ctrl binds struct now carries clusterer's use_controller
value, and load_clusterer_ctrl_binds() sets clusterer_ctrl_bound so clusterer
can tell whether a controller registered. Verified on all permutations: pure
controller, hybrid, native-only, and both mismatches.

Author: Lt-Flash

modules/clusterer/clusterer_ctrl.c

@@ -372,12 +372,17 @@ int clusterer_ctrl_unset_shtag_managed(int cluster_id)
 	return 0;
 }
 
+/* 1 once a controller module has bound this API (see clusterer_ctrl.h). */
+int clusterer_ctrl_bound = 0;
+
 int load_clusterer_ctrl_binds(clusterer_ctrl_binds_t *binds)
 {
     if (!binds) {
 	LM_ERR("clusterer: load_clusterer_ctrl_binds: NULL binds\n");
 	return -1;
     }
+    clusterer_ctrl_bound   = 1;
+    binds->use_controller  = use_controller;
     binds->set_my_identity        = clusterer_ctrl_set_identity;
     binds->add_node               = clusterer_ctrl_add_node;
     binds->remove_node            = clusterer_ctrl_remove_node;

modules/clusterer/clusterer_ctrl.h

@@ -157,8 +157,18 @@ typedef struct clusterer_ctrl_binds {
 	 * @return 0 on success, -1 if cluster not found
 	 */
 	int (*unset_shtag_managed)(int cluster_id);
+
+	/* Introspection: the value of the clusterer 'use_controller' modparam at
+	 * bind time.  Lets clusterer_controller detect the mirror misconfiguration
+	 * (controller loaded but clusterer has use_controller=0, so no stubs were
+	 * pre-created). */
+	int use_controller;
 } clusterer_ctrl_binds_t;
 
+/* Set to 1 by load_clusterer_ctrl_binds() when a controller module binds the
+ * API, so clusterer can warn if use_controller=1 yet no controller registered. */
+extern int clusterer_ctrl_bound;
+
 /**
  * load_clusterer_ctrl_binds() — fill a clusterer_ctrl_binds_t struct.
  *

modules/clusterer/clusterer_mod.c

@@ -657,6 +657,18 @@ static int child_init(int rank)
 			return -1;
 		}
 	}
+
+	/* One-shot config sanity check (rank 1 fires once, and runs after every
+	 * module's mod_init, so a clusterer_controller would already have bound the
+	 * controller API): use_controller=1 is meaningless without that module -
+	 * the pre-created controller-managed cluster stubs would never obtain an
+	 * identity or form. */
+	if (rank == 1 && use_controller && !clusterer_ctrl_bound)
+		LM_ERR("clusterer: use_controller=1 but no clusterer_controller module "
+		       "registered the controller API - controller-managed cluster(s) "
+		       "will never obtain a node identity or form. Load the "
+		       "clusterer_controller module, or unset use_controller.\n");
+
 	return 0;
 }
 

modules/clusterer_controller/README

@@ -496,9 +496,15 @@ on-key")
      * proto_bin — required so that BIN listeners are registered
        and available for discovery when clusterer_controller
        initialises and scans the proto_bin listener list.
-     * clusterer — required with use_controller=1 set, so that the
-       clusterer internal API (load_clusterer_ctrl_binds) is
-       exported and available at initialisation time.
+     * clusterer — required, and it must have use_controller=1
+       set. That global switch is what pre-creates the
+       controller-managed cluster stubs, marks them so they never
+       touch the database, and arms the guard that stops the
+       controller from driving a native cluster of the same id. If
+       clusterer_controller is loaded while clusterer has
+       use_controller=0, it refuses to start with a clear error —
+       there is no controller-managed cluster for it to drive and
+       those safety mechanisms would be off.
 
    Both dependencies are declared in the module's dep_export_t.
    OpenSIPS will refuse to start if either dependency is not
@@ -507,6 +513,22 @@ on-key")
    resolves the dependency at runtime and will initialize the
    required modules first regardless of loadmodule order.
 
+   The reverse is also checked: if use_controller=1 is set but the
+   clusterer_controller module is not loaded, clusterer logs an
+   error at startup, since the controller-managed cluster stubs
+   would never obtain a node identity or form. clusterer itself
+   keeps running, so any native or DB-backed clusters are
+   unaffected.
+
+   Hybrid deployments are unaffected. use_controller is a single
+   global switch; in a hybrid instance (native and
+   controller-managed clusters side by side) it is always 1 and
+   only the per-cluster kind differs (native via DB/static
+   provisioning versus controller-managed via the cluster_id
+   list). Both consistency checks above therefore only fire on a
+   genuine module/config mismatch — never on a hybrid or
+   pure-controller setup.
+
    All other modules that use the clusterer interface (tm, dialog,
    dispatcher, usrloc etc.) may be loaded in any order relative to
    clusterer_controller. The clusterer module automatically

modules/clusterer_controller/clusterer_controller.c

@@ -5804,6 +5804,25 @@ static int mod_init(void)
 	    LM_INFO("clusterer_controller: clusterer API loaded - "
 	            "topology will be driven dynamically\n");
 
+	    /* The controller is only meaningful when the clusterer module is told
+	     * to expect it (use_controller=1, a global switch): that is what
+	     * pre-creates the controller-managed cluster stubs, sets each one's
+	     * controller_managed flag (so they never touch the DB), and arms the
+	     * guard that stops the controller from hijacking a native cluster of the
+	     * same id.  With use_controller=0 there is no controller-managed cluster
+	     * at all and those safety mechanisms are off, so refuse to start rather
+	     * than run the control plane against clusters clusterer never authorised
+	     * us to drive.  (Hybrid setups keep use_controller=1 - only the per-
+	     * cluster kind differs - so this never trips them.) */
+	    if (!clctl.use_controller) {
+		LM_ERR("clusterer_controller: loaded but the clusterer module has "
+		       "use_controller=0 - there is no controller-managed cluster and "
+		       "the controller's safety guards are disabled. Set "
+		       "modparam(\"clusterer\", \"use_controller\", 1), or remove the "
+		       "clusterer_controller module.\n");
+		return -1;
+	    }
+
 	    /* When we manage sharing tags, start every tag as BACKUP and
 	     * lock out MI/script changes - the controller master decides
 	     * who becomes active.  (manage_shtags sentinels were already

modules/clusterer_controller/doc/clusterer_controller_admin.xml

@@ -502,11 +502,17 @@
 		</listitem>
 		<listitem>
 		<para>
-		    <emphasis>clusterer</emphasis> — required with
-		    <varname>use_controller=1</varname> set, so that
-		    the clusterer internal API
-		    (<function>load_clusterer_ctrl_binds</function>) is
-		    exported and available at initialisation time.
+		    <emphasis>clusterer</emphasis> — required, and it
+		    <emphasis>must</emphasis> have
+		    <varname>use_controller=1</varname> set. That global switch
+		    is what pre-creates the controller-managed cluster stubs,
+		    marks them so they never touch the database, and arms the
+		    guard that stops the controller from driving a native cluster
+		    of the same id. If <emphasis>clusterer_controller</emphasis>
+		    is loaded while clusterer has
+		    <varname>use_controller=0</varname>, it refuses to start with
+		    a clear error — there is no controller-managed cluster for it
+		    to drive and those safety mechanisms would be off.
 		</para>
 		</listitem>
 	    </itemizedlist>
@@ -521,6 +527,26 @@
 	    required modules first regardless of
 	    <function>loadmodule</function> order.
 	</para>
+	<para>
+	    The reverse is also checked: if
+	    <varname>use_controller=1</varname> is set but the
+	    <emphasis>clusterer_controller</emphasis> module is not loaded,
+	    clusterer logs an error at startup, since the controller-managed
+	    cluster stubs would never obtain a node identity or form. clusterer
+	    itself keeps running, so any native or DB-backed clusters are
+	    unaffected.
+	</para>
+	<para>
+	    <emphasis role="bold">Hybrid deployments are unaffected.</emphasis>
+	    <varname>use_controller</varname> is a single global switch; in a
+	    hybrid instance (native and controller-managed clusters side by side)
+	    it is always <varname>1</varname> and only the
+	    <emphasis>per-cluster</emphasis> kind differs (native via DB/static
+	    provisioning versus controller-managed via the
+	    <varname>cluster_id</varname> list). Both consistency checks above
+	    therefore only fire on a genuine module/config mismatch — never on a
+	    hybrid or pure-controller setup.
+	</para>
 	<para>
 	    All other modules that use the clusterer interface
 	    (<emphasis>tm</emphasis>, <emphasis>dialog</emphasis>,