6.1.3

Enhancements

Clustering

• #17530 Cluster linking now requires a non-community license. Under the default community license, configured links stay inactive (no message forwarding or route replication) and the REST API rejects attempts to enable a link with a clear hint to load a non-community license. Disabling and deleting links remain available so that legacy configuration can be tidied up. After upgrading the license, links can be enabled from the dashboard or REST API without restarting the node.

• #17549 Added the EMQX Backup Sync plugin to periodically synchronize selected configuration from a primary cluster to a secondary cluster by using the Data Backup APIs. The plugin supports configurable TLS options for HTTPS calls to the primary cluster.

• #17620 Added an operator-facing diagnostics module emqx_router_tool for inspecting and reconciling routing tables. Intended to be run via emqx ctl eval, it provides three helpers: cluster_schema_view/0 reports the route storage schema each cluster node is running; scan_missing_routes/0,1 streams the local subscription table and reports topics whose route entry is missing for this node (two-pass, throttled, tolerates concurrent (un)subscribes); reconcile_missing_routes/0,1 re-adds the missing routes via the existing emqx_router:add_route/2 API. Schema-agnostic and safe to run on a live cluster.

Multi-tenancy

• #17711 Made namespace selection consistent across the built-in database authentication user HTTP APIs, and allowed cleanup of records left over from a deleted namespace.

Previously only user creation accepted a namespace field in the request body; updating and deleting a user accepted the target namespace only through the ns query parameter. The update and delete endpoints now also accept a namespace field in the request body. When both are provided, the ns query parameter takes precedence. Listing users continues to use the ns query parameter.

• #17665 Added per-namespace counters for dropped messages and dropped deliveries in the multi-tenancy app. These are exposed at /api/v5/prometheus/namespaced_stats with a namespace label, alongside the existing per-namespace metric families. Operators can now diagnose drop rates per tenant from Prometheus without resorting to log inspection.

Known limitation: QoS2 PUBREL await-timeout drops do not yet have per-namespace attribution because that drop path bumps the global counter without firing the message.dropped hook.

Data Integration

• #17481 Add a retain_as_published option to MQTT bridge ingress (source) subscriptions. When the bridge connects to the remote broker using MQTT 5.0 and retain_as_published = true, the original retain flag on forwarded messages is preserved instead of being cleared, allowing the bridge to faithfully republish retained messages from upstream. The default is false to keep existing behavior. The option has no effect when proto_ver is v3 or v4.

Also, the connector now emits a warning log when bridge_mode = true is configured together with proto_ver = v5, since the legacy bridge-mode flag has no effect under MQTT 5.0 — set retain_as_published on individual subscriptions instead.

• #17508 Set the PostgreSQL application_name startup parameter to emqx for PostgreSQL and TimescaleDB connector connections.

This makes EMQX database sessions easier to identify in PostgreSQL logs and views such as pg_stat_activity.

• #17576 Added TLS cipher suite configuration support for the GreptimeDB connector via the existing ssl.ciphers field. When a cipher list is specified, TLS negotiation is restricted to those suites. Unsupported ciphers are rejected at connector startup.

• #17594 Added support for configuring Google Cloud Pub/Sub and BigQuery connector service_account_json values with file:// secret files, so service account credentials can be injected from external files.

• #17717 Added the option of allowing TLS Peer Verification for Confluent Producer Connectors.

• #17718 Added the option of allowing TLS Peer Verification for GCP PubSub Producer/Consumer and BigQuery Connectors.

Observability

• #17712 Added emqx_session_tool, an operator-facing diagnostic module callable from the remote console. Use emqx_session_tool:top_by(mqueue_len) (or any other session metric such as mqueue_dropped or inflight_cnt) to find the top-K sessions by gauge or counter value in clusters with many connections, without paging through the client list manually. The scan streams the channel registry, keeps only a bounded top-K result, and reads cached per-session metrics without messaging connection processes. emqx_session_tool:cluster_top_by/1 aggregates the result across all cluster nodes.

• #17558 Added two new metrics and corresponding rates to the GET /monitor_current HTTP API: rules_matched and actions_executed. They track the number of rules matched and the action execution rate (success + failure), respectively.

Also fixed actions.executed undercounting action invocations in non-batch mode (batch_size = 1): the counter is now incremented once per action callback invocation, independently of the buffer-worker telemetry flush window.

Bug Fixes

Core MQTT Functionalities

• #17529 Fixed an issue where QoS 0 messages delivered through Message Queue subscriptions could remain unacknowledged internally, causing the queue subscriber to stop receiving more messages after reaching its local inflight limit.

• #17540 Fixed a bug where setting password = "file://..." on an SSL listener caused config validation to fail with bad_password_or_invalid_keyfile when the keyfile was encrypted. The file:// reference is now resolved during validation, not only at runtime.

• #17569 Reduced MQTT v5 user-property parsing cost from quadratic to linear.

• #17731 Fixed a transient "address already in use" error that could occur when updating the options of a WS or WSS listener (for example when rotating TLS certificates). Updating such a listener rebinds its port, and the operating system may not have released the old socket yet; EMQX now retries the rebind briefly instead of failing the update.

• #17798 Fixed an issue where retained messages could be delivered with the original publish QoS instead of the wildcard subscription QoS limit.

• #17801 The ssl_opts.ciphers validator now accepts cipher names in either OpenSSL or IANA/RFC naming convention. Previously, only OpenSSL-format names were recognised, so a valid TLS 1.2 cipher supplied in its IANA name (e.g. TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384) was rejected as bad_ciphers even though Erlang's ssl module would have accepted it. TLS 1.3 ciphers were unaffected because their IANA and OpenSSL names are identical.

Queue and Stream

• #17515 Fixed an issue where Message Queue subscriptions using QoS 0 could stop receiving messages after the queue subscriber's local inflight window became full.

• #17733 Fixed an issue where Message Queue consumers could fail to restore an empty stream buffer after durable storage subscription recovery.

Rule Engine

• #17725 Fixed a bug introduced in 6.0.3, 6.1.2 and 6.2.1 where a global rule could stop matching messages on its FROM topic when publishing clients carried a tenant namespace (client_attrs.tns).

With rule_engine.limit_selects_in_namespace enabled (the default), global rules now retain system-wide visibility and match messages from any namespace. Rules created inside a namespace remain isolated to their own namespace. Operators who prefer to disable namespace restriction entirely can still set rule_engine.limit_selects_in_namespace = false.

Data Integration

• #17568 Upgraded the Kafka client library brod to 4.5.5.

Consumer group: respect the broker-assigned member ID when the join response carries the member_id_required error code (returned by older Kafka brokers, e.g. 2.2.0, that do not support static member instance IDs). Previously the member ID was discarded on error, preventing the retry from succeeding.

• #17579 Fixed Redis Sentinel connectors to use isolated Sentinel managers per resource and clean them up when resources stop, avoiding shared Sentinel state across connectors.

• #17584 Limited the amount of data returned during Connector health checks of Snowflake Aggregated Connectors. This only has observable effects if the list of existing schemas was really large, in which case the health check will take far less time to execute.

• #17588 Limited the amount of data returned during Connector and Action health checks of Kinesis integrations. This only has observable effects if the list of existing schemas was really large, in which case the health check will take far less time to execute.

• #17595 Limited the amount of data returned during Connector health checks of S3 and S3Tables integrations. This only has observable effects if the list of existing buckets was really large, in which case the health check will take far less time to execute.

• #17598 Fixed a connection failure to MongoDB 8.0+ when authentication is required. The driver previously queried buildInfo before authentication to pick the auth mechanism; MongoDB 8.0 restricted that command to authenticated callers. The driver now skips the probe and uses SCRAM-SHA-1 directly, which all supported MongoDB versions accept.

• #17605 Fixed Oracle action prepare/status checks to parse action SQL without executing it, and reject unsupported top-level DDL/DCL/TCL statements. Also improved support for text payloads over 4000 bytes when the payload placeholder is the last bind parameter.

• #17625 Fixed an issue with GCP PubSub Consumer Source where, if a source was initially created with a service account lacking necessary permissions to create subscriptions for the configured topic, the Source would fail to become connected even after granting the permissions to the service account.

• #17633 Fixed an issue introduced in 6.1.2 and 6.2.1 where MQTT bridges and Cluster Link connections over TLS could stall after a short period of traffic. Affected nodes log a recurring error message like unexpected_event ... ssl_passive ... from the emqtt client. EMQX now bundles emqtt 1.15.3, which restores normal traffic flow after the bug was first reported in https://github.com/emqx/emqx/issues/17617.

• #17649 Improved the responsivity of starting/stopping GCP PubSub Consumer Connectors. Previously, if hte connections were slow/busy, there could be timeouts which left the Connectors running, in an inconsistent state with the config.

• #17681 Fixed PostgreSQL connector batch writes when prepared statements are disabled.

Previously, concurrent batches on the same connection could interleave raw SQL parsing and fail with PostgreSQL protocol errors. Table-existence checks are also serialized through the connector worker to avoid interleaving with batch execution.

• #17701 Fixed a confusing badarith error from PostgreSQL actions when a batched SQL template returned rows, for example SELECT ....

PostgreSQL action batching does not support row-returning SQL. EMQX now returns a clear unsupported SQL error instead of crashing the batch result handler.

Clustering

• #17586 Periodically purge stale entries from the global session registry. Previously, when a session's owner process died without a clean unregister (for example, after a brief network split that prevented the unregister from replicating, or when one core's consensus check timed out during the down-event cleanup), the registry row could remain forever if the same clientid never reconnected. A new throttled background sweep on each core node now removes such rows. The sweep is bounded to at most 500 registry rows per second per node and runs no more often than once every 10 minutes, so it does not measurably affect broker throughput even on registries holding millions of sessions.

• #17773 Fixed configuration update commands (REST API and CLI) crashing with a function_clause crash report when the underlying cluster RPC layer aborted with an unexpected reason, for example {no_exists, cluster_rpc_mfa} when the cluster RPC tables were not yet available during node startup or recovery. Such failures are now returned to the caller as a structured error instead.

• #17764 Fixed stale plugin entries after a node rejoins a cluster where the plugin was uninstalled while the node was offline. EMQX now removes local plugin packages that are no longer present in the cluster plugin configuration during plugin startup.

Access Control

• #17575 Fixed a race condition in the emqx_username_quota plugin that could cause the per-username session counter to become inconsistent with the actual number of tracked client records. The counter could be decremented past zero and then be deleted while a concurrent session registration incremented it, losing the increment permanently.

• #17644 Fixed an issue where the plain password hash algorithm accepted passwords that differed only by letter case during authentication.

• #17646 Fixed an HTTP/1.1 protocol-conformance issue in the JWKS retrieval client used by JWT authentication. Earlier versions sent an empty TE: header value due to a long-standing default in Erlang/OTP's inets HTTP client (fixed upstream in inets 9.4.2 / OTP 28.1). Some identity providers (notably PingFederate) reject such requests. EMQX now sends an explicit, valid TE: trailers header on JWKS fetches.

• #17653 Fixed a security issue where the Prometheus configuration API returned stored Authorization header values in push gateway headers. The API now redacts these values in responses.

• #17654 Fixed an issue where creating an authenticator via POST /authentication returned the new authenticator config without redacting provider secrets (such as JWT HMAC secrets, HTTP Authorization headers, and request body passwords). The creation response now applies the same redaction as the list and get endpoints.

• #17657 Fixed a security issue where raw authorization and cookie headers were forwarded to plugin API callbacks. These credential-bearing headers are now redacted before reaching plugin code.

• #17711 Creating or updating a built-in database user that targets a namespace which is not a known managed namespace is now rejected with "Managed namespace not found". Previously a user supplied with a namespace in the request body could be created even when that namespace did not exist.

In addition, a global administrator can now delete a built-in database user that belongs to a namespace which has already been deleted, instead of receiving a "Managed namespace not found" error.

• #17736 Restricted the JWT authenticator to verify tokens using only JWS algorithms consistent with the configured key type. HMAC-based authenticators now accept only HS256, HS384, and HS512. Public-key and JWKS authenticators accept RS, PS, ES*, and EdDSA algorithms. Tokens whose alg header does not match the configured key type — including alg=none — are rejected.

• #17739 Improved redaction of sensitive data in logs, traces, and audit records.

• #17787 Stopped HTTP connector error logs from including request headers when an ehttpc worker is killed mid-request.

When the HTTP connector's ehttpc worker was killed while a request was in flight (for example, by deleting the source while the request had not yet returned), the resulting EXIT reason carried the original gen_server:call arguments, which include the request headers. These headers were then written verbatim to the error log. The call arguments are now dropped from the reason before it is logged.

• #17790 Stopped writing the TOTP shared secret to the dashboard_login_failed server log. The secret was previously included in this log entry during first-time MFA setup.

• #17791 Improved log redaction so that JWT HMAC key bytes no longer appear in cluster_rpc_apply_result and cluster_rpc_apply_ok debug log lines emitted during configuration updates.

The redactor now recognises the internal JWK record shape and replaces it with a placeholder before logging, and also treats the jwk field as sensitive.

Multi-tenancy

• #17715 Fixed a multi-tenancy gating gap. When multi_tenancy.post_auth_tns_expression is configured and the expression evaluates to an empty string or raises an error, the namespace gate (allow_only_managed_namespaces enforcement, session quota, etc.) was previously skipped, allowing the client through.

The empty and error outcomes are now treated as "no namespace assigned" and pass through the same gate as a client that supplied no namespace before authentication: the client is rejected when allow_only_managed_namespaces = true, and accepted without a namespace when it is false. Any namespace value carried in client_attrs.tns from before authentication is also cleared in this case, so it is not retained when the expression declined to assign one.

• #17757 Fixed /prometheus/namespaced_stats so that namespaced admins/API keys can only see data from their own namespace. Global admins/API keys can still see data from all namespaces.

Gateway

• #17556 Fixed an issue where the OCPP gateway did not pass the listener enable_authn option to the shared authentication flow because the option was stored under a misspelled client-info key.

• #17581 Fixed the JT/T 808 gateway to use the phone number accepted during authentication as the connection identity, rejecting mismatched registration-code authentication attempts and subsequent uplink frames with a different phone number.

• #17604 Fixed GBT32960 gateway routing: vehicle responses to downstream commands (Parameter Query, Parameter Setting, Terminal Control) are now correctly published to upstream/response instead of upstream/transparent.

• #17765 Fixed missing authorization checks in several gateway broker paths.

MQTT-SN will message publishing, JT808 upstream publishing and automatic downlink subscription, GBT32960 upstream publishing and automatic downlink subscription, and OCPP upstream publishing and automatic downlink subscription now check authorization before publishing or subscribing.

Observability

• #17497 Fixed the actions.executed metric undercounting actions.messages for actions configured in non-batch mode (batch_size = 1).

The previous implementation incremented actions.executed once per buffer-worker telemetry flush, which could aggregate many individual completions into one event, so actions.executed fell behind actions.messages even when no batching was configured.

The two metrics are now incremented at independent call sites: actions.executed once per action callback invocation (one per batch in batch mode, one per message in single mode), actions.messages per message handled.

• #17513 Fixed Prometheus matched authorization allow/deny metrics so they reflect real matched authorization decisions.

• #17536 Documented the file:// option in dashboard tooltips for the SSL listener password and other secret-typed configuration fields (MQTT bridge password, cluster link password, Dashboard OIDC client secret, S3 secret access key, AI completion API key, Pulsar/RocketMQ credentials, etc.). The generic secret type description already mentioned this convention, but field-specific descriptions shadowed it in the dashboard, causing users to assume the field accepted only literal values.

• #17708 Fixed a logger JSON formatter crash that could replace some debug-level trace events with a FORMATTER CRASH line.