Skip to main content
Version: Mosquitto 2.5


Publish / Subscribe Introduction

retain_available [ true | false ]

If set to false, then retained messages are not supported. Clients that send a message with the retain bit will be disconnected if this option is set to false. Defaults to true.

This option applies globally.

Reloaded on reload signal.

The PUBLISH/SUBSCRIBE model consists of the client-server model.

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 publisher and subscriber.


The broker simply delivers the message to all subscribers. It's the duty of the broker. There is no obstacle within the broker.


Either one publisher publishes messages to multiple Subscribers.


Or multiple publisher publish messages to just one subscriber.


Or any combination of multiple publishers/subscribers.

Also, consumers can publish as well. This is called "Bidirectional publishing".

Any publisher can only be identified when information about the publisher is included in the topic or payload.


  • packetId

Identifies a message.

The packetId is set by the client library and broker.

  • topicName

The topic is set using a simple string.

Topics are treated hierarchically. To delimiter, a slash "/" symbolizes a separation. Allowing the client organizational structure, much like a common filesystem.

There is no need for creating a topic. You can subscribe to any topic, even though there might not be messages published.

On the other hand, you must know about the topic names to be able to subscribe to them.

The topic is essentially a UTF-8 string.

Filtering the topic of a sent message can be done by the broker by simply comparing the encoded UTF-8 bytes or decoded Unicode characters.

Be aware that an extra slash or slashes set by mistake are detected by the broker as a delimiter.

  • 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.

  • retainFlag

In many cases, a device can not wait until the next time the publisher provides information sending a message.

A sensor of a car door tells whether the door is open or closed. As the door is used very infrequently, including a retained flag makes sense.

Without a retained flag set (retainFlag=false), you must wait for the next time the door is opened or closed to find out about the status.

With retained messages (retainFlag=true), you immediately find out, because the retained message gives you the last status.

A retained message safes the last known value of the topic. It's only possible to save up to one retained message, equal to one retained value. The retainFlag identifies a message to be a retained message. To identify the message the packetId is used.


Digression: Wildcards + retained messages

May the subscribing client include wildcards in the topic pattern they subscribe to, the client receives a retained message even if the topic of the retained message is not an exact match.


The actual content of a message is the content of a payload. Whether it's a .mp3-file or .mp4-file, a picture, or a video. Up to 256MB. The payload does not encrypt the content. The broker simply delivers what the publisher inserted into the payload.

Matter of fact the receiving clients don't even know about the data format they receive. Still, there's little chance that a client subscribes to a host and topic it doesn't know about in the first place. Following the client can forecast the receiving data format.

The subscriber can not reject a message. But as it can do with it as pleased, that could be nothing as well. Meaning a subscriber could receive a message, but simply don't do anything with it.

  • dupFlag

A dupFlag indicates the duplicate of a message.

A message with dupFlag was resent. Following a recipient didn't acknowledge the original message.