Skip to content

MQTT Configuration

MQTT is a standard messaging protocol for the Internet of Things (IoT). It is designed as an extremely lightweight publish/subscribe messaging transport that is ideal for connecting remote devices with a small code footprint and minimal network bandwidth.

EMQX is 100% MQTT 5.0 and 3.x compliant, this section will introduce the basic configuration items for MQTT-related features, covering topics like basic MQTT settings, subscription settings, session settings, force shutdown settings, and forced garbage collection settings.

Basic MQTT Configurations

This section will introduce the configuration settings that determine how the MQTT protocol will behave in terms of packet size, client ID length, topic levels, quality of service (QoS), topic alias, and retention.

TIP

You can also find the corresponding configuration items in EMQX Dashboard (Management -> MQTT Settings -> General). Once you configured these items with the Dashboard, your settings will override the same configuration items in emqx.conf.

Example Code:

bash
mqtt {
  max_packet_size = 1MB
  max_clientid_len = 65535
  max_topic_levels = 128
  max_qos_allowed = 2
  max_topic_alias = 65535
  retain_available = true
}

Where,

Configuration ItemsDashboard UIDescriptionDefault valueOptinal Values
max_packet_sizeMax Packet SizeMQTT packets are used to send messages between MQTT clients and EMQX.

This sets the maximum MQTT packet size allowed.
1MB
max_clientid_lenMax Client ID LengthThis sets the maximum length of an MQTT client ID.

It can help to prevent clients from using excessively long client IDs that could cause issues.
6553523 - 65535
max_topic_levelsMax Topic LevelsMQTT topics are used to organize and categorize messages.

This sets the maximum number of levels allowed in an MQTT topic.
1281 - 35
max_qos_allowedMax QoSQoS levels determine the level of reliability and delivery assurance for messages.

This sets maximum quality of service (QoS) level that is allowed for MQTT messages.
max_topic_aliasMax Topic AliasTopic aliases are a way to reduce the size of MQTT packets by using a shorter alias instead of the full topic name.

This sets the maximum number of topic aliases that can be used in an MQTT session.
655351 - 65535
retain_availableRetain AvailableRetained messages are used to store the last message published to a topic, so that new subscribers to the topic can receive the most recent message.

This sets whether to enable retained messages feature in MQTT.
truetrue, false

Subscription Settings

In EMQX, subscription refers to the process of a client subscribing to a topic on EMQX. When a client subscribes to a topic, it is indicating that it wants to receive messages published to that topic.

This section introduces how to configure shared subscription, wildcard subscription, and exclusive subscription.

TIP

You can also find the corresponding configuration items in EMQX Dashboard (Configuration -> MQTT -> General). Once you configured these items with the Dashboard, your settings will override the same configuration items in emqx.conf.

Example code:

bash
mqtt {
	wildcard_subscription = true
  exclusive_subscription = false
  shared_subscription = true
  shared_subscription_strategy  =  round_robin
}

Where,

Configuration ItemsDashboard UIDescriptionDefault valueOptinal Values
wildcard_subscriptionWildcard Subscription AvailableWildcard subscriptions allow MQTT clients to subscribe to multiple topics using a single subscription, using wildcards such as + and #.

This sets whether to enable wildcard subscription.
truetrue, false
exclusive_subscriptionExclusive SubscriptionExclusive subscriptions allow only one MQTT client to subscribe to a topic at a time.

This sets whether to enable exclusive subscriptions.
truetrue, false
shared_subscriptionShared Subscription AvailableShared subscriptions allow multiple MQTT clients to share a subscription to a topic.

This sets whether to enable shared subscriptions in MQTT.
truetrue, false
shared_subscription_strategyThis setting defines the strategy for distributing messages among MQTT clients that share a subscription.

Needed only shared_subscription is set to true.
round_robin- random (Dispatch the message to a random selected subscriber)

- round_robin (Select the subscribers in a round-robin manner)

- sticky (Always use the last selected subscriber to dispatch, until the subscriber disconnects.)

- hash (Select the subscribers by the hash of clientIds)

Delayed Publish Settings

The Delayed Publish feature allows clients to delay the publishing of a message to a topic for a specified amount of time. This feature is useful for scenarios where messages need to be published at specific times or when a certain condition is met.

This section introduces how to enable delayed publishing and how to set the maximum of delayed messages allowed:

Example code:

bash
delay {
  delayed_publish_enabled = true
  max_delayed_messages = 0
}

Where,

  • delayed_publish_enabled sets whether to enable the Delayed Publish feature in EMQX; default value: true, optional values: true, false.
  • max_delayed_messages sets the maximum number of delayed messages allowed; default value: 0.

Keep Alive Settings

The Keep Alive is a Two Byte Integer, a time interval measured in seconds. It is a mechanism to ensure that an MQTT client and EMQX connection remain active even if no data is transmitted. When an MQTT client establishes a connection with EMQX, setting a non-zero value in the Keep Alive variable header field of the CONNECT packet can enable the Keep Alive mechanism between both parties. For details about how Keep Alive works, see What is the MQTT Keep Alive parameter for?.

According to the MQTT 5.0 protocol, for clients with Keep Alive enabled, if the server does not receive an MQTT Control Packet from the client within 1.5 times the Keep Alive duration, it must close the network connection with the client. Therefore, EMQX introduces a configuration option keepalive_multiplier to periodically check clients' Keep Alive timeout status. The default value for keepalive_multiplier is 1.5:

bash
keepalive_multiplier = 1.5

The timeout calculation formula is as follows:

Keep Alive×keepalive_multiplier

Session Settings

In MQTT, a session refers to the connection between a client and a broker. As in EMQX, When a client connects to EMQX, it establishes a session that allows it to subscribe to topics and receive messages, as well as publish messages to EMQX.

This section introduces how to configure sessions.

Example code:

bash
session {
    max_subscriptions = infinity
    upgrade_qos = false
    max_inflight = 32
    retry_interval = 30s
    max_awaiting_rel = 100
    await_rel_timeout = 300s
    session_expiry_interval = 2h
    max_mqueue_len = 1000
    mqueue_priorities = disabled
    mqueue_default_priority = lowest
    mqueue_store_qos0 = true
    
    force_shutdown {
      max_message_queue_len = 1000
      max_heap_size = 32MB
    }

    force_gc {
      count  =  16000
      bytes  =  16MB
    }
  }

Where,

Configuration ItemDashboard UIDescriptionDefault ValueOptional Values
max_subscriptionsMax SubscriptionsThis sets the maximum number of subscriptions that the client is allowed to haveinfinity1 - infinity
upgrade_qosUpgrade QoSThis sets whether the client is allowed to upgrade the QoS (Quality of Service) level of a message after it has been published.false (disabled)true, false
max_inflightMax InflightThis sets the maximum number of QoS 1 and QoS 2 messages that can be in flight (i.e., sent but not yet acknowledged) at any given time321 - 65535
retry_intervalRetry IntervalThis sets the interval at which the client should retry sending a QoS 1 or QoS 2 message.30s
unit: s
--
max_awaiting_relMax Awaiting PUBRELThis sets the pending QoS 2 messages in each session until either PUBREL is received or timed out. After reaching this limit, new QoS 2 PUBLISH requests will be rejected with error code 147(0x93).
In MQTT, PUBREL is a control packet used in the message flow for QoS 2, which provides guaranteed message delivery.
1001 - infinity
await_rel_timeoutMax Awaiting PUBREL TIMEOUTThis sets the amount of time to wait for a release of a QoS 2 message before receiving PUBREL. After reaching this limit, EMQX will release the packet ID and also generate a warning level log.
Note: EMQX will forwarding of the received QoS 2 message whether it has received the PUBREL or not.
300s
unit: s
--
session_expiry_intervalSession Expiry IntervalThis sets the amount of time that a session can be idle before it is automatically closed. Note: For non-MQTT 5.0 clients only.2h
max_mqueue_lenMax Message Queue LengthThis sets the maximum allowed queue length when persistent clients are disconnected or inflight window is full.10000 - infinity
mqueue_prioritiesTopic PrioritiesThis sets the topic priorities, the configuration here will override that defined in mqueue_default_priority.disabled
The session uses the priority set by mqueue_default_priority.
disabled
or
1 - 255
mqueue_default_priorityDefault Topic PrioritiesThis sets the default topic priority.lowesthighestlowest
mqueue_store_qos0Store QoS 0 MessageThis sets whether to store QoS 0 message in the message queue when the connection is down but the session remains.truetrue, false
force_shutdown--This sets whether to enable the force shutdown feature if the queue length (max_message_queue_le) or heap size (max_heap_size) reaches the specified value.truetrue, false
force_shutdown.max_message_queue_le--This sets the maximum queue length to trigger a forced shutdown.10001 - infinity
force_shutdown.max_heap_size--This sets the maximum heap size to trigger a forced shutdown.32MB--
force_gc--This sets whether to enable forced garbage collection if the specified message number (count) or byte received (bytes) is reached:truetrue, false
force_gc.count--This sets the received message number that will trigger the forced garbage collection.160000 - infinity
force_gc.bytes--This sets the received byte number that will trigger the forced garbage collection.16MB
Unit: MB
--

TIP

To Configure MQTT via Dashboard, click Configuration -> MQTT on the left navigation menu of the Dashboard. Once you configured these items with the Dashboard, your settings will override the same configuration items in emqx.conf.

TIP

EMQX offers more configuration items to serve customized needs better. For details, see the EMQX Open Source Configuration Manual and EMQX Enterprise Configuration Manual for Enterprise.