clusterer: make use_controller a per-cluster parameter (breaking config change)

use_controller was a single global 0/1 switch that turned the controller
path on, with a separate 'cluster_id' modparam list naming which clusters
were controller-managed. That split was confusing: two parameters to express
one intent, and 'use_controller=0' could be read as if it meant per-cluster.

Collapse the two into one per-cluster parameter. Each

    modparam("clusterer", "use_controller", N)

now registers cluster N as controller-managed (creates the pre-fork stub,
flags it controller_managed so it never touches the DB, and arms the
native-hijack guard). Native clusters remain defined the usual way (DB rows
or static my_node_info/neighbor_node_info); a hybrid instance simply lists
its controller clusters with use_controller and its native ones separately.
The derived internal boolean the rest of the module keys off is unchanged,
so all downstream logic (db_mode override, mirror/child-init guards, packet
handling) is untouched.

This is a breaking config change (hard break, no silent compatibility):

  - use_controller now takes a cluster_id >= 1. A bare use_controller=0 is
    rejected with a clear error; to disable the controller, omit the modparam.
  - The 'cluster_id' modparam (which existed only as the controller stub list)
    is removed. It is kept registered solely to fail at startup with a hint
    pointing to the new form, instead of a generic "unknown parameter".

Docs (admin guide, tests appendix, README) updated so every example uses the
per-cluster form and every cluster is explicitly defined.

Author: Yury Kirsanov

modules/clusterer/clusterer_mod.c

@@ -51,22 +51,55 @@ int current_id = -1;
 int *_current_id_shm = NULL;
 int db_mode = 1;
 int clusterer_enable_rerouting = 1;
-int use_controller = 0;
+int use_controller = 0;   /* derived: 1 if any controller-managed cluster is configured */
 
-/* cluster_ids to pre-create when use_controller=1 */
+/* cluster_ids registered as controller-managed via the 'use_controller' modparam */
 static int cc_stub_ids[64];
 static int cc_stub_count = 0;
 
-static int cc_add_cluster_id(modparam_t type, void *val)
+/* 'use_controller' modparam: each entry names one controller-managed cluster_id.
+ * In the devel series this changed from a global 0/1 switch into a per-cluster
+ * list - modparam("clusterer","use_controller",N) marks cluster N as
+ * controller-managed.  The derived 'use_controller' int above stays as the
+ * "controller feature active at all" flag the rest of the module keys off. */
+static int cc_add_controller_cluster(modparam_t type, void *val)
 {
+	int id = (int)(long)val;
+	int i;
+
+	if (id <= 0) {
+		LM_ERR("clusterer: use_controller now takes a cluster_id >= 1 "
+			"(per-cluster); to disable the controller omit the modparam. "
+			"Old 'use_controller=1' global configs must set use_controller "
+			"to each controller cluster_id and drop the 'cluster_id' "
+			"modparam\n");
+		return -1;
+	}
 	if (cc_stub_count >= 64) {
-		LM_ERR("clusterer: too many cluster_id entries\n");
+		LM_ERR("clusterer: too many use_controller entries\n");
 		return -1;
 	}
-	cc_stub_ids[cc_stub_count++] = (int)(long)val;
+	for (i = 0; i < cc_stub_count; i++)
+		if (cc_stub_ids[i] == id) {
+			LM_ERR("clusterer: use_controller lists cluster_id %d twice\n", id);
+			return -1;
+		}
+	cc_stub_ids[cc_stub_count++] = id;
+	use_controller = 1;   /* at least one controller-managed cluster exists */
 	return 0;
 }
 
+/* 'cluster_id' modparam: removed.  It used to list controller-managed clusters;
+ * that role now belongs to per-cluster 'use_controller'.  Kept registered only to
+ * fail loudly with a migration hint instead of a generic "unknown parameter". */
+static int cc_add_cluster_id(modparam_t type, void *val)
+{
+	LM_ERR("clusterer: the 'cluster_id' modparam has been removed; register "
+		"each controller-managed cluster with "
+		"modparam(\"clusterer\", \"use_controller\", <cluster_id>) instead\n");
+	return -1;
+}
+
 str clusterer_db_url = {NULL, 0};
 
 extern db_con_t *db_hdl;
@@ -176,7 +209,7 @@ static const param_export_t params[] = {
 	{"flags_col",			STR_PARAM,	&flags_col.s		},
 	{"description_col",		STR_PARAM,	&description_col.s	},
 	{"db_mode",				INT_PARAM,	&db_mode			},
-	{"use_controller",			INT_PARAM,		&use_controller			},
+	{"use_controller",			INT_PARAM|USE_FUNC_PARAM, (void*)cc_add_controller_cluster},
 	{"cluster_id",				INT_PARAM|USE_FUNC_PARAM, (void*)cc_add_cluster_id},
 	{"neighbor_node_info",	STR_PARAM|USE_FUNC_PARAM,
 		(void*)&provision_neighbor},
@@ -527,7 +560,7 @@ static int mod_init(void)
 	}
 
 	/* Controller-managed clusters: pre-create a stub for each cluster_id the
-	 * controller registered (via the 'cluster_id' modparam), so cl_register_cap()
+	 * controller registered (via the 'use_controller' modparam), so cl_register_cap()
 	 * succeeds for tm/dialog before clusterer_controller injects the real
 	 * identity.  Each stub is flagged controller_managed: it never touches the DB
 	 * and behaves as db_mode=0, so it coexists with DB-native clusters.  A
@@ -541,7 +574,7 @@ static int mod_init(void)
 			for (_ex = *cluster_list; _ex; _ex = _ex->next)
 				if (_ex->cluster_id == cc_stub_ids[_ci]) {
 					LM_ERR("clusterer: cluster_id %d is registered as "
-						"controller-managed (cluster_id modparam) but is "
+						"controller-managed (use_controller modparam) but is "
 						"already defined via native config "
 						"(my_node_info/neighbor_node_info/DB) or listed "
 						"twice - a cluster_id must be unique and either "

modules/clusterer_controller/README

@@ -106,7 +106,8 @@ Chapter 1. Admin Guide
    each other automatically at startup and the cluster topology is
    maintained dynamically at runtime.
 
-   When use_controller=1 is set in the clusterer module, the
+   When a cluster is registered as controller-managed via
+   modparam("clusterer", "use_controller", N), the
    clusterer_controller module takes over all topology management:
    it allocates unique node IDs, discovers peer BIN socket
    addresses, and calls the clusterer internal API to add or
@@ -499,15 +500,17 @@ 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, 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.
+     * clusterer — required, and it must register at least one
+       cluster as controller-managed with modparam("clusterer",
+       "use_controller", N). That per-cluster parameter 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 no use_controller cluster registered, 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
@@ -516,28 +519,29 @@ 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.
+   The reverse is also checked: if a use_controller cluster is
+   registered 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
+   per-cluster parameter: each entry names one controller-managed
+   cluster id. In a hybrid instance (native and controller-managed
+   clusters side by side), the controller-managed clusters are
+   listed with use_controller while the native ones are defined
+   the usual way (DB rows or static
+   my_node_info/neighbor_node_info). 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
-   creates a cluster stub when use_controller=1 is set and a
-   module attempts to register a capability for an unknown
-   cluster.
+   creates a cluster stub when a use_controller cluster is
+   registered and a module attempts to register a capability for
+   an unknown cluster.
 
 1.5.2. External Libraries or Applications
 
@@ -832,9 +836,10 @@ modparam("clusterer_controller", "password", "MyStr0ngPassw0rd!")
 ...
 # clusters 1 and 2 registered as controller-managed on the clusterer sid
 e
-modparam("clusterer", "use_controller", 1)
-modparam("clusterer", "cluster_id", 1)
-modparam("clusterer", "cluster_id", 2)
+modparam("clusterer", "use_controller", 1)   # cluster 1 is controller-m
+anaged
+modparam("clusterer", "use_controller", 2)   # cluster 2 is controller-m
+anaged
 
 # Enable automatic failover for every cluster (this is also the default)
 modparam("clusterer_controller", "manage_shtags", 1)
@@ -849,9 +854,10 @@ modparam("clusterer_controller", "cluster", "id=2,multicast=239.0.90.2:3
 ...
 # clusters 1 and 2 registered as controller-managed on the clusterer sid
 e
-modparam("clusterer", "use_controller", 1)
-modparam("clusterer", "cluster_id", 1)
-modparam("clusterer", "cluster_id", 2)
+modparam("clusterer", "use_controller", 1)   # cluster 1 is controller-m
+anaged
+modparam("clusterer", "use_controller", 2)   # cluster 2 is controller-m
+anaged
 
 # manage_shtags=1 globally, but cluster 2 uses its own MI/event-route sc
 ripts
@@ -866,9 +872,10 @@ modparam("clusterer_controller", "cluster",
 ...
 # clusters 1 and 2 registered as controller-managed on the clusterer sid
 e
-modparam("clusterer", "use_controller", 1)
-modparam("clusterer", "cluster_id", 1)
-modparam("clusterer", "cluster_id", 2)
+modparam("clusterer", "use_controller", 1)   # cluster 1 is controller-m
+anaged
+modparam("clusterer", "use_controller", 2)   # cluster 2 is controller-m
+anaged
 
 # Disable automatic failover globally; enable it only for cluster 1
 modparam("clusterer_controller", "manage_shtags", 0)
@@ -890,10 +897,8 @@ socket=bin:10.22.23.191:3857
 loadmodule "proto_bin.so"
 
 loadmodule "clusterer.so"
-modparam("clusterer", "use_controller", 1)     # enable the controller p
-ath (global switch)
-modparam("clusterer", "cluster_id",     1)     # register cluster 1 as c
-ontroller-managed
+modparam("clusterer", "use_controller", 1)     # cluster 1 is controller
+-managed
 modparam("clusterer", "sharing_tag",   "vip1/1=active")
 modparam("clusterer", "ping_interval", 4)
 modparam("clusterer", "ping_timeout",  1500)
@@ -939,9 +944,10 @@ modparam("clusterer_controller", "password", "MyStr0ngPassw0rd!")
    Example 1.12. Set master_stickiness parameter
 ...
 # both clusters registered as controller-managed on the clusterer side
-modparam("clusterer", "use_controller", 1)
-modparam("clusterer", "cluster_id", 1)
-modparam("clusterer", "cluster_id", 2)
+modparam("clusterer", "use_controller", 1)   # cluster 1 is controller-m
+anaged
+modparam("clusterer", "use_controller", 2)   # cluster 2 is controller-m
+anaged
 
 # Global default (sticky) — omit entirely for the same effect
 modparam("clusterer_controller", "master_stickiness", 1)
@@ -1210,12 +1216,10 @@ socket=bin:10.0.2.10:5566
 loadmodule "proto_bin.so"
 
 loadmodule "clusterer.so"
-modparam("clusterer", "use_controller", 1)   # enable the controller pat
-h (global switch)
-modparam("clusterer", "cluster_id", 1)        # cluster 1 is controller-
-managed
-modparam("clusterer", "cluster_id", 2)        # cluster 2 is controller-
-managed
+modparam("clusterer", "use_controller", 1)   # cluster 1 is controller-m
+anaged
+modparam("clusterer", "use_controller", 2)   # cluster 2 is controller-m
+anaged
 
 loadmodule "clusterer_controller.so"
 # Cluster 1 — dialog replication group, LAN segment 10.0.1.0/24
@@ -1238,12 +1242,10 @@ socket=bin:10.22.23.191:3857
 loadmodule "proto_bin.so"
 
 loadmodule "clusterer.so"
-modparam("clusterer", "use_controller", 1)   # enable the controller pat
-h (global switch)
-modparam("clusterer", "cluster_id", 1)        # cluster 1 is controller-
-managed
-modparam("clusterer", "cluster_id", 2)        # cluster 2 is controller-
-managed
+modparam("clusterer", "use_controller", 1)   # cluster 1 is controller-m
+anaged
+modparam("clusterer", "use_controller", 2)   # cluster 2 is controller-m
+anaged
 
 loadmodule "clusterer_controller.so"
 modparam("clusterer_controller", "cluster",
@@ -1268,11 +1270,12 @@ modparam("dispatcher", "cluster_id", 2)
 
    Which kind a cluster is follows from how it is declared:
      * Controller-managed — every cluster_id registered with the
-       clusterer module via modparam("clusterer", "cluster_id", N)
-       (and matched by a cluster entry in this module). Its
-       topology and this node's node_id are driven at runtime by
-       the controller; it never touches the database and always
-       behaves as db_mode=0, regardless of the global db_mode.
+       clusterer module via modparam("clusterer",
+       "use_controller", N) (and matched by a cluster entry in
+       this module). Its topology and this node's node_id are
+       driven at runtime by the controller; it never touches the
+       database and always behaves as db_mode=0, regardless of the
+       global db_mode.
      * Native — every cluster loaded from the clusterer database
        (db_mode!=0) or provisioned statically. It behaves exactly
        as classic clusterer: fixed my_node_id, DB persistence
@@ -1315,10 +1318,8 @@ s")
 modparam("clusterer", "my_node_id", 5)      # this node's id in its nati
 ve/DB clusters (global)
 # controller side: cluster 1 is dynamic (no DB, no static rows)
-modparam("clusterer", "use_controller", 1)  # enable the controller path
- (global switch)
-modparam("clusterer", "cluster_id", 1)       # register cluster 1 as con
-troller-managed
+modparam("clusterer", "use_controller", 1)  # cluster 1 is controller-ma
+naged
 
 loadmodule "clusterer_controller.so"
 modparam("clusterer_controller", "cluster",
@@ -1350,10 +1351,8 @@ modparam("clusterer", "my_node_info",       "cluster_id=7, url=bin:10.0.
 modparam("clusterer", "neighbor_node_info", "cluster_id=7, node_id=6, ur
 l=bin:10.0.0.11:5566")
 # controller side: cluster 1 is dynamic
-modparam("clusterer", "use_controller", 1)           # enable the contro
-ller path (global switch)
-modparam("clusterer", "cluster_id", 1)                # register cluster
- 1 as controller-managed
+modparam("clusterer", "use_controller", 1)           # cluster 1 is cont
+roller-managed
 
 loadmodule "clusterer_controller.so"
 modparam("clusterer_controller", "cluster",
@@ -1386,10 +1385,8 @@ socket=bin:10.22.23.191:3857
 loadmodule "proto_bin.so"
 
 loadmodule "clusterer.so"
-modparam("clusterer", "use_controller", 1)     # enable the controller p
-ath (global switch)
-modparam("clusterer", "cluster_id",     1)     # register cluster 1 as c
-ontroller-managed
+modparam("clusterer", "use_controller", 1)     # cluster 1 is controller
+-managed
 modparam("clusterer", "sharing_tag",   "vip1/1=active")
 modparam("clusterer", "ping_interval", 4)
 modparam("clusterer", "ping_timeout",  1500)
@@ -1667,9 +1664,10 @@ A.7. Test 6 — Multiple clusters over one BIN socket
    but both advertise the same BIN socket (bin:IP:3857). Each
    cluster must form independently and its replication must stay
    isolated over the shared socket.
-modparam("clusterer", "use_controller", 1)
-modparam("clusterer", "cluster_id", 1)
-modparam("clusterer", "cluster_id", 2)
+modparam("clusterer", "use_controller", 1)   # cluster 1 is controller-m
+anaged
+modparam("clusterer", "use_controller", 2)   # cluster 2 is controller-m
+anaged
 modparam("clusterer_controller", "cluster",
     "id=1,multicast=239.0.90.1:3333,bin_socket=bin:IP:3857")
 modparam("clusterer_controller", "cluster",