Add mqtt.max_connections per-node connection limit

lukebakken · michaelklishin · commit 9c1683ab1e3c · 2026-05-11T16:49:54.000-07:00
Add the `mqtt.max_connections` configuration key, which sets a
node-wide limit on the number of concurrent MQTT connections.

The limit is checked in `rabbit_mqtt_processor:process_connect/5`
as the first step in the CONNECT packet handler, before
authentication. When exceeded, the broker returns a CONNACK with
reason code `quota_exceeded` (MQTT 5) or return code
`not_authorized` (MQTT 3.x/4).

The active connection count is obtained via
`ets:info(persistent_term:get(?PG_SCOPE), size)`. The MQTT plugin
creates a node-local PG scope in `rabbit_mqtt_sup`; each connection
joins it via `pg:join/3` in `register_client_id/4`, using
`{VHost, ClientId}` as the group key. Since the MQTT spec requires
unique client IDs per vhost, which RabbitMQ enforces, each group
has exactly one member. The PG scope ETS table therefore has one
row per active connection node-wide, covering all listeners and
transports (plain TCP, TLS, and Web MQTT). `ets:info/2` reads this
count in O(1) - important given that MQTT nodes can host a very
large number of connections.

The check runs before `register_client_id/4`, so the current
connection is not yet counted; the limit comparison is `&gt;= Limit`.

When `mqtt.max_connections` is absent, `application:get_env/3`
returns `infinity` and no check is performed.

A `node_connection_limit` test is added to the `limit` group in
`auth_SUITE`.
diff --git a/deps/rabbitmq_mqtt/priv/schema/rabbitmq_mqtt.schema b/deps/rabbitmq_mqtt/priv/schema/rabbitmq_mqtt.schema
@@ -160,6 +160,19 @@ end}.
     {datatype, integer}
 ]}.
 
+{mapping, "mqtt.max_connections", "rabbitmq_mqtt.max_connections",
+    [{datatype, [{atom, infinity}, integer]}, {validators, ["non_negative_integer"]}]}.
+
+{translation, "rabbitmq_mqtt.max_connections",
+fun(Conf) ->
+    case cuttlefish:conf_get("mqtt.max_connections", Conf, undefined) of
+        undefined -> cuttlefish:unset();
+        infinity  -> infinity;
+        Val when is_integer(Val) -> Val;
+        _         -> cuttlefish:invalid("should be a non-negative integer")
+    end
+end}.
+
 {mapping, "mqtt.ssl_cert_login", "rabbitmq_mqtt.ssl_cert_login", [
     {datatype, {enum, [true, false]}}]}.
 
diff --git a/deps/rabbitmq_mqtt/src/rabbit_mqtt_processor.erl b/deps/rabbitmq_mqtt/src/rabbit_mqtt_processor.erl
@@ -188,6 +188,7 @@ process_connect(
     end,
     Result0 =
     maybe
+        ok ?= check_node_connection_limit(),
         ok ?= check_extended_auth(ConnectProps),
         {ok, ClientId1} ?= extract_client_id_from_certificate(ClientId0, Socket),
         {ok, ClientId} ?= ensure_client_id(ClientId1, CleanStart, ProtoVer),
@@ -1081,6 +1082,33 @@ check_vhost_exists(VHost, Username, PeerIp) ->
             {error, ?RC_BAD_USER_NAME_OR_PASSWORD}
     end.
 
+check_node_connection_limit() ->
+    case application:get_env(rabbitmq_mqtt, max_connections, infinity) of
+        infinity ->
+            ok;
+        Limit when is_integer(Limit), Limit >= 0 ->
+            PgScope = persistent_term:get(?PG_SCOPE),
+            %% pg:init/1 creates a named ETS table using the scope atom as the table
+            %% name. Each row holds one group: {Group, AllPids, LocalPids}. Since
+            %% MQTT enforces unique client IDs per vhost, every connected client
+            %% occupies exactly one group, so the table size equals the number of
+            %% active connections node-wide across all listeners and transports.
+            %% We use ets:info/2 (O(1)) rather than pg:which_groups/1, which
+            %% performs a full table scan via ets:match/2 and is O(N) — too
+            %% expensive when the node hosts a large number of MQTT connections.
+            %% Note: OTP-27.3.4.11 source code used as a reference.
+            case ets:info(PgScope, size) of
+                ActiveConns when is_integer(ActiveConns), ActiveConns >= Limit ->
+                    ?LOG_ERROR("MQTT connection failed: node connection limit ~tp is reached",
+                               [Limit]),
+                    {error, ?RC_QUOTA_EXCEEDED};
+                _ ->
+                    ok
+            end;
+        _ ->
+            ok
+    end.
+
 check_vhost_connection_limit(VHost) ->
     case rabbit_vhost_limit:is_over_connection_limit(VHost) of
         false ->
diff --git a/deps/rabbitmq_mqtt/test/auth_SUITE.erl b/deps/rabbitmq_mqtt/test/auth_SUITE.erl
@@ -121,7 +121,8 @@ sub_groups() ->
      {limit, [shuffle],
       [vhost_connection_limit,
        vhost_queue_limit,
-       user_connection_limit
+       user_connection_limit,
+       node_connection_limit
       ]}
     ].
 
@@ -359,6 +360,10 @@ init_per_testcase(T, Config)
     SetupProcess = setup_rabbit_auth_backend_mqtt_mock(Config),
     rabbit_ct_helpers:set_config(Config, {mock_setup_process, SetupProcess});
 
+init_per_testcase(T = node_connection_limit, Config) ->
+    rabbit_ct_broker_helpers:rpc(Config, 0, application, set_env,
+                                 [rabbitmq_mqtt, max_connections, 0]),
+    testcase_started(Config, T);
 init_per_testcase(Testcase, Config) ->
     testcase_started(Config, Testcase).
 
@@ -499,6 +504,11 @@ end_per_testcase(T, Config)
     SetupProcess ! stop,
     close_all_connections(Config);
 
+end_per_testcase(node_connection_limit = T, Config) ->
+    rabbit_ct_broker_helpers:rpc(Config, 0, application, set_env,
+                                 [rabbitmq_mqtt, max_connections, infinity]),
+    close_all_connections(Config),
+    rabbit_ct_helpers:testcase_finished(Config, T);
 end_per_testcase(Testcase, Config) ->
     close_all_connections(Config),
     rabbit_ct_helpers:testcase_finished(Config, Testcase).
@@ -1321,6 +1331,12 @@ user_connection_limit(Config) ->
     ok = emqtt:disconnect(C1),
     ok = rabbit_ct_broker_helpers:clear_user_limits(Config, DefaultUser, max_connections).
 
+node_connection_limit(Config) ->
+    {ok, C} = connect_anonymous(Config, <<"client1">>),
+    ExpectedError = expected_connection_limit_error(Config),
+    unlink(C),
+    ?assertMatch({error, {ExpectedError, _}}, emqtt:connect(C)).
+
 expected_connection_limit_error(Config) ->
     case ?config(mqtt_version, Config) of
         v4 ->
diff --git a/deps/rabbitmq_mqtt/test/config_schema_SUITE_data/rabbitmq_mqtt.snippets b/deps/rabbitmq_mqtt/test/config_schema_SUITE_data/rabbitmq_mqtt.snippets
@@ -187,6 +187,11 @@
    [{rabbitmq_mqtt, [
       {message_interceptors, []}
      ]}],
-   []}
+   []},
+
+  {max_connections,
+   "mqtt.max_connections = 10",
+   [{rabbitmq_mqtt,[{max_connections, 10}]}],
+   [rabbitmq_mqtt]}
 
 ].
