Incompatible Changes in EMQX 6.3

6.3.0

• #17185 The MQTT parser now runs in strict mode by default. To restore the previous lenient behavior, set mqtt.strict_mode = false (globally or per-zone).

  In strict mode, the broker validates incoming MQTT packets against the protocol specification and disconnects clients that send malformed packets. The validations enforced only in strict mode are:

  • Fixed-header flags. Reserved DUP/QoS/RETAIN bits must be zero for non-PUBLISH packets, and PUBREL/SUBSCRIBE/UNSUBSCRIBE must use QoS=1 (bad_frame_header).
  • CONNECT reserved bit must be zero (reserved_connect_flag).
  • CONNECT Will flag consistency: Will Flag=0 requires Will QoS=0 and Will Retain=0; Will Flag=1 requires Will QoS in {0,1,2} (invalid_will_qos, invalid_will_retain).
  • CONNECT Password/Username flags (MQTT 3.1.1 only). If Username Flag=0, Password Flag must also be 0, per [MQTT-3.1.2-22] (invalid_password_flag). MQTT 5.0 lifts this constraint and is unaffected.
  • UTF-8 strings (proto name, client ID, topic, username, password, will topic, MQTT 5 string properties) must be valid UTF-8 and must not contain control characters U+0000–U+001F or U+007F–U+009F (utf8_string_invalid).
  • Packet identifiers must be non-zero where required (PUBLISH QoS>0, PUBACK/REC/REL/COMP, SUBSCRIBE/SUBACK, UNSUBSCRIBE/UNSUBACK) (bad_packet_id).

  When a client violates one of these checks, the broker logs an info-level entry with msg=frame_parse_error and a structured reason (for example, cause=invalid_password_flag, proto_ver, or received_prefix) for troubleshooting. For MQTT 5.0 connections, the broker also responds with CONNACK/DISCONNECT carrying reason code 0x81 Malformed Packet before closing; for MQTT 3.1/3.1.1, the connection is silently closed (no CONNACK reason code is defined for malformed packets in those versions).

• #17215 Removed the bundled Swagger UI assets from the EMQX release package, reducing tarball size by approximately 11 MB.

  /api-docs/swagger.json continues to serve the full OpenAPI 3 JSON spec, so external Swagger UI deployments that load it by URL keep working. The legacy /api-docs URL responds with an HTTP 308 redirect to /api-spec.html, the in-tree spec explorer introduced in 6.3.0. Other /api-docs/* subpaths (the embedded Swagger UI assets) are no longer served and return 404.

• #17267 The node.max_ports config now defaults to auto, which scales the Erlang VM port limit (+Q) with the number of logical CPU cores: 65536 ports per core for up to 8 cores, and 1048576 (the historical fixed default) above that. Explicit integer values are still accepted.

  This is a behavior change for nodes upgraded from earlier versions where max_ports defaulted to a fixed 1048576: hosts with 8 or fewer CPU cores will now boot with a smaller port table. Setups that rely on accepting more than cores * 65536 connections must set node.max_ports explicitly (and restart the node) before upgrading.

  The hidden node.process_limit setting is reinstated as an override: when set to a value larger than the derived limit (2 * max_ports), it is respected; smaller values are ignored so the process table never under-sizes the port table.

  A new node.schedulers setting (default auto) controls the Erlang scheduler count (+S). With auto, the count is capped at the number of logical processors actually available to the VM (sched_getaffinity on Linux), so containers limited via --cpuset-cpus or Kubernetes CPU requests no longer spawn scheduler OS threads they cannot run in parallel. Set it to a positive integer to override the auto-detected value.

• #17437 Prometheus scrape endpoints (/api/v5/prometheus/*) now require authentication by default. Set prometheus.enable_basic_auth = false explicitly to restore the previous unauthenticated behavior. Deployments that scrape these endpoints without credentials will need to either configure credentials on the scraper or set the config field. The recommended setup is a dedicated API key with the monitoring scope, used with Bearer auth in the scraper.

• #17582 Prometheus VM and Mnesia collector metric names now use the prometheus.erl 6.x promtool-compliant names.

  Affected metric renames:

  • erlang_mnesia_failed_transactions -> erlang_mnesia_failed_transactions_total
  • erlang_mnesia_committed_transactions -> erlang_mnesia_committed_transactions_total
  • erlang_mnesia_logged_transactions -> erlang_mnesia_logged_transactions_total
  • erlang_mnesia_restarted_transactions -> erlang_mnesia_restarted_transactions_total
  • erlang_vm_memory_atom_bytes_total -> erlang_vm_memory_atom_bytes
  • erlang_vm_memory_bytes_total -> erlang_vm_memory_bytes
  • erlang_vm_memory_processes_bytes_total -> erlang_vm_memory_processes_bytes
  • erlang_vm_memory_system_bytes_total -> erlang_vm_memory_system_bytes
  • erlang_vm_statistics_context_switches -> erlang_vm_statistics_context_switches_total
  • erlang_vm_statistics_garbage_collection_number_of_gcs -> erlang_vm_statistics_garbage_collection_number_of_gcs_total
  • erlang_vm_statistics_garbage_collection_words_reclaimed -> erlang_vm_statistics_garbage_collection_words_reclaimed_total
  • erlang_vm_statistics_garbage_collection_bytes_reclaimed -> erlang_vm_statistics_garbage_collection_bytes_reclaimed_total
  • erlang_vm_statistics_runtime_milliseconds -> erlang_vm_statistics_runtime_seconds_total
  • erlang_vm_statistics_wallclock_time_milliseconds -> erlang_vm_statistics_wallclock_time_seconds_total
  • erlang_vm_port_count -> erlang_vm_ports
  • erlang_vm_process_count -> erlang_vm_processes
  • erlang_vm_atom_count -> erlang_vm_atoms

• #17596 Added authorization options that forbid interpolation of /, +, and # symbols into topic filter templates in authorization rules. The new options are:

  authorization.topic_template_allow {
    plus = false,
    hash = false,
    slash = false
  }

  With false, the corresponding symbol cannot be used in a value interpolated into a topic template. For example, if plus = false, then username bad+user is forbidden in a rule such as {allow, all, publish, ["userspace/${username}"]}. The outcome depends on the active security profile: with the legacy profile the rule will not match, and with the hardened profile the action will be denied.

• #17677 Dropped support for the JSON output format in the Prometheus REST API.

  The endpoints under /api/v5/prometheus (stats, auth, data_integration, schema_validation, message_transformation) now only produce the Prometheus text format. Requests sending Accept: application/json are rejected with 400 Bad Request ("only prometheus format is supported"); previously they returned a JSON representation of the metrics.

• #17626 #18123 Added a new configuration multi_tenancy.deny_namespaces holding namespace names that cannot be used as a namespace identifier, either as an admin namespace (dashboard roles, API keys, multi-tenancy management API) or as a per-client client_attrs.tns; a client whose client_attrs.tns resolves to a denied name is rejected.

  This is a breaking change: the default value ["global", "undefined", "null", "none"] denies names that were previously accepted. These names collide with internal sentinels and would produce ambiguous log lines and dashboard output. Existing namespaces with these names are not migrated; rename them before upgrading, or set multi_tenancy.deny_namespaces to an empty list to lift the restriction.

  Additionally, when multi_tenancy.post_auth_tns_expression is configured and evaluates to an empty value or fails to evaluate, a client whose pre-authentication client_attrs.tns is a denied namespace name is now also rejected, consistent with the handling when the expression evaluates to a non-empty value.

• #18228 The default authorization rules file (acl.conf) no longer grants clients connecting from 127.0.0.1 blanket publish/subscribe access to all topics (including $SYS/# and #).

  Clients connecting from localhost are now authorized by the same rules as any other client, and ultimately by the authorization.no_match setting. In particular, subscriptions to $SYS/# and the wildcard filters # and +/# are now denied for localhost clients by the default rules, regardless of the security profile.

  Deployments that relied on the built-in localhost allowance must add an explicit rule to acl.conf. The previous rule is retained in the file as a comment for easy re-enabling:

  %% {allow, {ipaddr, "127.0.0.1"}, all, ["$SYS/#", "#"]}.

  Note: this applies to new installations and deployments that have not customized acl.conf; existing customized acl.conf files are not modified by upgrades.

• #18244 The ExProto gateway has been removed.

• #18271 #18329 MQTT and gateway WebSocket listeners no longer read the client address and port from forwarded headers by default: the default value of proxy_address_header and proxy_port_header changed from x-forwarded-for / x-forwarded-port to empty, meaning the socket source address and port are always used. Deployments behind load balancers or reverse proxies that rely on forwarded headers must now configure the header names explicitly (for example, set proxy_address_header to x-forwarded-for). Setting an empty header name disables the forwarded-header lookup.

  This change also fixes the forwarded-header lookup for gateway WebSocket listeners. Previously, a configured header name was never matched against the request headers, so the socket source address and port were used even when the forwarded headers were present.

• #18377 Managed namespace names are now validated when created. A name may contain only ASCII letters, digits, and the characters ., -, and _, with a length of 1 to 255 bytes; the names . and .. are not accepted. Namespaces that already exist are not affected.

• #18390 The mqtt.clientid_override expression no longer falls back to the client-supplied Client ID when it fails.

  When mqtt.clientid_override is configured and the expression raises an error (for example, it references an attribute the client did not provide) or renders an empty string, EMQX now refuses the connection with CONNACK reason code 0x85 (Client Identifier not valid; return code 2 for MQTT 3.1 and 3.1.1 clients). Previously such clients stayed connected under their original Client ID, so the override silently did not apply to them.

  Before upgrading, verify that every connecting client can render the configured expression to a non-empty string. Clients that could not render the expression connected with their original Client ID before the upgrade; after the upgrade they are refused until the expression or the client data is fixed.

• #18419 Removed the Google Cloud IoT Core migration compatibility feature, including the GCP Device authenticator and device management APIs.

• #18515 Updated the Azure Blob Storage Action's blob template field to use the same schema validation as the Aggregated S3 Action's key field. The validation rejects unsupported template bindings.

• #18528 Added validation that requires the exporter endpoint of an OpenTelemetry integration to be a URL with an explicit scheme and port. Supported schemes are http and https.

• #18627 Dashboard SAML SSO now verifies IdP signatures by default in all security profiles.

  Previously the default followed the security profile: the hardened profile verified signatures, but the legacy profile (the default until v7.0) did not, so it accepted an unsigned, forged SAMLResponse and issued a Dashboard session.

  If you intentionally run an unsigned IdP, set sso.saml.idp_signs_envelopes = false and sso.saml.idp_signs_assertions = false explicitly. If the IdP does sign but its metadata carries no certificate, the SAML backend now fails to start with missing_idp_certificate.