emqx4.3/changes/v5.8.1.en.md

5.8.1

Release Date: 2024-10-14

Make sure to check the breaking changes and known issues before upgrading to EMQX 5.8.1.

Important Changes

• #13956 Updated the gen_rpc library to version 3.4.1, which includes a node crash issue. Previously, if a node is force shutdown down while RPC channels are being established, it may cause a cluster peer node to crash.

Enhancements

Core MQTT Functionalities

• #13525 Added new configuration item shared_subscription_initial_sticky_pick to specify the strategy for making the initial pick when shared_subscription_strategy is set to sticky.

• #13942 The HTTP client now automatically reconnects if no activity is detected for 10 seconds after the latest request has expired. Previously, it would wait indefinitely for a server response, causing timeouts if the server dropped requests.

This change impacts below components.

• HTTP authentication
• HTTP authorization
• Webhook (HTTP connector)

Authentication and Authorization

• #13863 EMQX now supports ${cert_common_name} placeholder in topic name templates for raw ACL rules.

• #13792 The banned-clients API GET /banned supports querying the rules using filters in the query string.

The available filters are:

• clientid
• username
• peerhost
• like_clientid
• like_username
• like_peerhost
• like_peerhost_net

When adding a new banned client entry, the default expiration time for entries without the until parameter specified has been changed from 1 year to infinite.

Rule Engine

• #13773 Disabled rule actions now do not trigger out_of_service warnings.

Previously, if an action is disabled, there would be a warning log with msg: out_of_service, and the actions.failed counter was incremented for the rule.

After this enhancement, disabled action will result in a debug level log with msg: discarded, and the newly introduced counter actions.discarded will be incremented.

MQTT over QUIC

• #13814 Connection Scope Keepalive for MQTT over QUIC Multi-Stream:

This update introduces a new feature to maintain MQTT connections over QUIC multi-streams, even when the control stream is idle but other data streams are active.

Previously, clients had to send MQTT.PINGREQ on idle control streams to keep the connection alive. Now, a shared state is maintained for each connection, monitoring activity across all streams. This shared state helps determine if the connection is still active, reducing the risk of keepalive timeouts caused by Head-of-Line (HOL) blocking and improving overall connection stability.

Bug Fixes

Core MQTT Functions

• #13702 Clean up the corresponding exclusive subscriptions when a node goes down.

• #13708 Fixed an issue which may cause shared subscription 'sticky' strategy to degrade to 'random'.

• #13733 Made cacertfile optional when configuring https listener from emqx ctl conf load command.

• #13742 Fixed when subscribing with + as the first level, or # as a wildcard, retained messages with topics starting with $ are incorrectly received.

• #13754 Fixed an issue when websocket connection would break consistently on its own.

• #13756 Introduced more randomness to broker assigned client IDs.

• #13790 The default heartbeat interval for the MQTT connector has been reduced from 300 seconds to 160 seconds.

This change helps maintain the underlying TCP connection by preventing timeouts due to the idle limits imposed by load balancers or firewalls, which typically range from 3 to 5 minutes depending on the cloud provider.

• #13832 Fixed that the Publish endpoint would have a 500 error when persistent session were enabled.

• #13842 Fixed a UTF-8 string validation exception.

Upgrade and Migration

• #13731 Resolved an issue that prevented clusters running on EMQX 5.4.0 from upgrading to EMQX 5.8.0. This fix introduces a migration procedure to update specific internal database tables created in version 5.4.0 to align with the new schema.

Breaking Changes

• #13792 The default expiration time for a banned item that is created without an until value is now infinity (previsouly capped at 1 year limit).

• #13742 Fixed an issue when a client would receive retained messages for a topic starting with $ when it subscribed to topic # or +.

This fix satisfies the requirement of MQTT-4.7.2-1.