Skip to main content
Version: Mosquitto 2.8

MQTT Glossary

Below a list of often used terms, when working with MQTT architectures.


The Broker is the server that communicates with all clients to manage the message or packet transfer using the MQTT Protocol. The broker receives all messages published from connected clients and coordinates the message transfer to subscribing clients based on topics. The broker also ensures security issues. Messages are to some extent cached on the broker to be resent, if a connection is temporarily lost or a message did not reach the client (depending on QoS)

Clean Session

If the cleanSession is set true ( = true), the client does not want to store messages. Also, if set true, previous persistent sessions are dismissed.

Clean Start

When connecting to a broker, the client defines how a broker resumes a previous session. If the clean start flag is set to 1, the broker starts a new session. If it is set to 0the server resumes communication with the client based on the state of the current session (the session is identified by the clientId).


A client can be any device that can run a MQTT library and is able to connect to a broker. Clients communicate with the broker via topics. A client can publish a message and/or subscribe to messages. These message are categorized by topics.

Client ID

The clientId identifies any MQTT client that is connecting to an MQTT broker. The clientId can come from the client, but it does not always have to. If permitted, a clientId can be blank. Whenever the client does not set a clientId, the broker sets one on behalf of the client.


A cluster provides the ability to run a cluster of broker nodes with a single leader and multiple followers, so that broker availability can be ensured even if a single node becomes unavailable through fault or for an upgrade. This document describes the recommended cluster architecture and how to configure the cluster for first use, and in the future.

The Mosquitto cluster comprises at least three nodes. A single node is available for use by MQTT clients at once, the other nodes operate as fail-over nodes. The cluster expects a minimum of two nodes to be available at once, to provide a leader and a fallback node. If the state of the cluster fails so that only a single node is available, clients will be unable to connect until the cluster is in a stable state again.

Dynamic Security

The Dynamic Security plugin for Eclipse Mosquitto provides role based authentication and access control features that can updated while the broker is running, using a special topic based API.

It is supported since Eclipse Mosquitto 2.0, and should be available in all installations, but will not be activated by default.

Keep Alive

The MQTT keepAlive parameter identifies the maximum interval in seconds when a client maintains the MQTT connection but without communication (sending an MQTT packet). After the specified keepAlive parameter period is over, a client sends a PING request (PINGREQ), and a broker has to respond with a PING Response (PINGRESP). If no response follows the PING request, the client can assume the connection has disconnected. Also, the broker is waiting for the PING request. The broker must expect a PINGREQ and wait for another half of the set in the keepAlive parameter time, but then disconnect the connection for good.

Last Will

The lastWill message is sent by the broker on behalf of the client when a disconnect occurs without a DISCONNECT packet before the actual break-off.

Message / Packet

There is no definition of when a delivery is called a packet or message. Cedalo is using the term "packet" for any of the commands, and "message" for publishing or subscribing messages. All packets must pass the broker.

The actual content of a message is the content of a payload. MQTT is not limited by its payload format. It delivers what the publisher is sending. This could be a value, string, JSON file, or even content of a jpg or an mp3 file. Up to 256MB. The payload does not encrypt the content. The broker simply delivers what the publisher inserts into the payload.


MQTT (originally “MQ Telemetry Transport”) is a lightweight publish/subscribe messaging protocol. It is designed for connecting remote devices with a small footprint and minimal network bandwidth.

There are two major specification versions. Click on a specification to get more information:


Payload is the actual content of a message. MQTT is not limited by its payload format. It delivers what the publisher is sending.

Persistent Session

The Persistent session is active when the cleanSession flag is set to false. An active MQTT persistent session is relevant whenever the client disconnects ungracefully. All information that the client did not receive from the broker since the last active connection will be preserved on the broker and delivered to the client once the connection is restored. The broker resumes the client in the existing session if the clientId is the same as the disconnected client. A client will not have to resubscribe to all topics again.


Either one publisher publishes messages to multiple Subscribers. Or multiple publishers publish messages to just one subscriber. Or any combination of multiple publishers/subscribers. Any publisher can only be identified when information about the publisher is included in the topic or payload.

Publish / Subscribe

The PUBLISH/SUBSCRIBE model connects clients that want to exchange information/data/messages. Any client communicates with an endpoint via the broker. Before a client wants to publish messages it first has to set up a connection with the broker. Also, a subscribing client has to do the same. Therefore, the broker can decouple the publisher and subscriber.

Quality of Service (QoS)

The QoS (Quality of Service) defines a certain level of service that enables the publisher to make sure that the certainty and quantity of a subscriber receiving a sent message equal the importance to receive the message at all, plus whether to receive the message only once. Also, a subscriber can set a QoS, defining the importance to receive every message, and whether to accept one message multiple times or not. There are three levels available.

QoS 0

The broker/client is delivering the message only once, without confirmation. There is no guarantee that the message sent has been sent to the subscriber. The recipient on the other end does not acknowledge the receipt. Neither is the acknowledgment stored. The QoS - level 0 is often referred to be the "fire and forget"-level.

QoS 1

QoS - Level 1 guarantees the delivery of a message to the receiver at least once.

QoS 2

QoS - level 2 guarantees each message is received exactly once.


When a persistent session is active, the broker must queue the missed messages. Whenever a persistent session is created by the client, and the broker already queued messages of an earlier persistent session, the broker delivers the queued messages using the same old session.

Retained Message

A retained message safes the last known value of the topic. It's only possible to save uone retained message, equal to one retained value. The retainFlag identifies a message to be a retained message. This message is sent, if a client subscribes to a topic.


If a client connects to the broker a session is started. If a client connects to the broker and another client session already exists with the clientId that the new client has chosen, the old session will be kicked out and taken over.

Session Expiry Interval

The session expiry interval defines the period length after a client disconnects and the session of the client ends. When the session ends allo data related to the session is removed (subscriptions, messages ...)


A subscription consists of a packetId. And the subscriptions the subscriber wants to subscribe to. Each subscription consists of a topic and a QoS level. When subscriptions overlap, the broker delivers the message that has the highest QoS level for the specific topic.


A subscriber is a client that subscribed messages related to a topic.


Using Transport Layer Security (TLS) provides a secured communication channel a client and a server can use to connect. TLS is a cryptographic protocol, that uses a handshake mechanism to create a secure connection between client and server.


Messages in MQTT are published to topics. A topic is a string that that acts as an identifier for messages to be published to or subscribed from. There is no need to configure a topic, publishing on it automatically creates a topic, you can subscribe on.

Topics are treated as a hierarchy, using a slash (/) as a separator. This allows an arrangement of common themes to be created, much in the same way as a file system. This way you can group or organize your data to be published.

Valid examples for grouped topics could be:

  • Company/Location/MachineA/Speed
  • Company/Location/MachineB/Speed
  • Company/Location/MachineC/Speed
  • Company/Location/MachineC/Temp

Topics can contain spaces and are case-sensitive. Topics must use UTF8 coding. Zero length topic levels are valid, which can lead to some slightly non-obvious behaviour. For example, a topic of " a//topic" would correctly match against a subscription of "a/+/topic". Likewise, zero length topic levels can exist at both the beginning and the end of a topic string, so "/a/topic" would match against a subscription of "+/a/topic", "#" or "/#", and a topic "a/topic/" would match against a subscription of "a/topic/+" or "a/topic/#".

Clients can receive messages by creating subscriptions. A subscription may be to an explicit topic, in which case only messages to that topic will be received, or it may include wildcards. Two wildcards are available, + or #.

  • '+' can be used as a wildcard for a single level of hierarchy. For the above topics using Company/Location/+/Speed would subscribe to all machines messages related to Speed.
  • '#' can be used as a wildcard for all remaining levels of a hierarchy. For the above topics using Company/Location/MachineC/# would subscribe to all messages for MachineC.