Skip to main content
Version: Mosquitto 2.1

Subscribing

Currently the section "Subscribing" contains "mosquitto_sub" and "Subscription Support". Both are command line tools. Both can publish/subscribe.

Subscription Support

Introduction Publish / Subscribe

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

he delivered subject is ether called "message" or "packet" by all participants working with MQTT.

Both - messages and packets - are the same.

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.

Direct contact between subscriber and publisher is never able. Only the broker enables transmitting messages.

The setup allows no other than the broker to connect the publisher and subscriber. There is no way around this setup but still using MQTT, no gap.

Once the PUBLISHER and SUBSCRIBER are authenticated by the broker. Backed on information the broker sent, the broker ensures the connected devices can send messages to other devices. And the other way round, to receive messages from other devices.

So the broker is the central hub every message sent must pass. The brokers job is to receive, filter, and forward the message. The so-called load balancer moves the message from process stage to the next.

The brokers' responsibility is to receive all messages that are sent by the publishing clients.

In the next step, the broker must filter the incoming message. Part of it is to check the configured rules the publishing client has set. Following the broker authorativates who have subscribed to the topic of the message, and finally forwarding the message to the subscribing clients.

Whenever a subscribing client requests storage of not-sent messages, the broker does as pleased within the possibility the MQTT protocol sets.

Therefore the publishing client has only one duty. To make sure that the message is sent to the broker. Everything else is dealt with by the broker.

Also, the subscribing client only has one duty. To subscribe to the topic it wants to receive messages from.

In fact, because of the decoupling of the publishing client and subscribing client, they have no chance to find out more about the other one.

The subscriber only knows about the existence of the publisher as the client subscribes to the published topics.

Every exchange of messages is done by the broker.

  • allow_duplicate_messages [ true | false ]

This option is deprecated and will be removed in a future version. The behaviour will default to true.

If a client is subscribed to multiple subscriptions that overlap, e.g. foo/# and foo/+/baz , then MQTT expects that when the broker receives a message on a topic that matches both subscriptions, such as foo/bar/baz, then the client should only receive the message once.

Mosquitto keeps track of which clients a message has been sent to in order to meet this requirement. This option allows this behaviour to be disabled, which may be useful if you have a large number of clients subscribed to the same set of topics and want to minimise memory usage.

It can be safely set to true if you know in advance that your clients will never have overlapping subscriptions, otherwise your clients must be able to correctly deal with duplicate messages even when then have QoS=2.

Defaults to true.

This option applies globally.

Reloaded on reload signal.

  • autosave_on_changes [ true | false ]

If true, mosquitto will count the number of subscription changes, retained messages received and queued messages and if the total exceeds autosave_interval then the in-memory database will be saved to disk. If false, mosquitto will save the in-memory database to disk by treating autosave_interval as a time in seconds.

This option applies globally.

Reloaded on reload signal.

  • check_retain_source [ true | false ]

This option affects the scenario when a client subscribes to a topic that has retained messages. It is possible that the client that published the retained message to the topic had access at the time they published, but that access has been subsequently removed. If check_retain_source is set to true, the default, the source of a retained message will be checked for access rights before it is republished. When set to false, no check will be made and the retained message will always be published.

This option applies globally, regardless of the per_listener_settings option.

  • max_packet_size value

For MQTT v5 clients, it is possible to have the server send a "maximum packet size" value that will instruct the client it will not accept MQTT packets with size greater than value bytes. This applies to the full MQTT packet, not just the payload. Setting this option to a positive value will set the maximum packet size to that number of bytes. If a client sends a packet which is larger than this value, it will be disconnected. This applies to all clients regardless of the protocol version they are using, but v3.1.1 and earlier clients will of course not have received the maximum packet size information. Defaults to no limit.

This option applies to all clients, not just those using MQTT v5, but it is not possible to notify clients using MQTT v3.1.1 or MQTT v3.1 of the limit.

Setting below 20 bytes is forbidden because it is likely to interfere with normal client operation even with small payloads.

This option applies globally.

Reloaded on reload signal.

  • max_queued_bytes count

The number of outgoing QoS 1 and 2 messages above those currently in-flight will be queued (per client) by the broker. Once this limit has been reached, subsequent messages will be silently dropped. This is an important option if you are sending messages at a high rate and/or have clients who are slow to respond or may be offline for extended periods of time. Defaults to 0. (No maximum).

See also the max_queued_messages option. If both max_queued_messages and max_queued_bytes are specified, packets will be queued until the first limit is reached.

This option applies globally.

Reloaded on reload signal.

  • max_queued_messages count

The maximum number of QoS 1 or 2 messages to hold in the queue (per client) above those messages that are currently in flight. Defaults to 1000. Set to 0 for no maximum (not recommended). See also the queue_qos0_messages and max_queued_bytes options.

This option applies globally.

Reloaded on reload signal.

  • memory_limit limit

This option sets the maximum number of heap memory bytes that the broker will allocate, and hence sets a hard limit on memory use by the broker. Memory requests that exceed this value will be denied. The effect will vary depending on what has been denied. If an incoming message is being processed, then the message will be dropped and the publishing client will be disconnected. If an outgoing message is being sent, then the individual message will be dropped and the receiving client will be disconnected. Defaults to no limit.

This option is only available if memory tracking support is compiled in.

Reloaded on reload signal. Setting to a lower value and reloading will not result in memory being freed.

  • message_size_limit limit

This option sets the maximum publish payload size that the broker will allow. Received messages that exceed this size will not be accepted by the broker. This means that the message will not be forwarded on to subscribing clients, but the QoS flow will be completed for QoS 1 or QoS 2 messages. MQTT v5 clients using QoS 1 or QoS 2 will receive a PUBACK or PUBREC with the "implementation specific error" reason code.

The default value is 0, which means that all valid MQTT messages are accepted. MQTT imposes a maximum payload size of 268435455 bytes.

This option applies globally.

Reloaded on reload signal.

  • password_file file path

Set the path to a password file. If defined, the contents of the file are used to control client access to the broker. The file can be created using the mosquitto_passwd utility.

Read more about Password: Here. And here. And here.

If mosquitto is compiled without TLS support (it is recommended that TLS support is included), then the password file should be a text file with each line in the format "username:password", where the colon and password are optional but recommended. If allow_anonymous is set to false, only users defined in this file will be able to connect. Setting allow_anonymous to true when password_file is defined is valid and could be used with acl_file to have e.g. read only guest/anonymous accounts and defined users that can publish.

If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Reloaded on reload signal. The currently loaded username and password data will be freed and reloaded. Clients that are already connected will not be affected.

See also this

  • autosave_on_changes [ true | false ]

If true, mosquitto will count the number of subscription changes, retained messages received and queued messages and if the total exceeds autosave_interval then the in-memory database will be saved to disk. If false, mosquitto will save the in-memory database to disk by treating autosave_interval as a time in seconds.

This option applies globally.

Reloaded on reload signal.

  • per_listener_settings [ true | false ]

If true, then authentication and access control settings will be controlled on a per-listener basis. The following options are affected:

password_file, acl_file, psk_file, allow_anonymous, allow_zero_length_clientid, auto_id_prefix.

  • plugin, plugin_opt_*

Note that if set to true, then a durable client (i.e. with clean session set to false) that has disconnected will use the ACL settings defined for the listener that it was most recently connected to.

The default behaviour is for this to be set to false, which maintains the settings behaviour from previous versions of mosquitto.

Reloaded on reload signal.

  • check_retain_source

This option affects the scenario when a client subscribes to a topic that has retained messages. It is possible that the client that published the retained message to the topic had access at the time they published, but that access has been subsequently removed. If check_retain_source is set to true, the default, the source of a retained message will be checked for access rights before it is republished. When set to false, no check will be made and the retained message will always be published.

This option applies globally, regardless of the per_listener_settings option.

  • persistence [ true | false ]

If true, connection, subscription and message data will be written to the disk in mosquitto.db at the location dictated by persistence_location. When mosquitto is restarted, it will reload the information stored in mosquitto.db. The data will be written to disk when mosquitto closes and also at periodic intervals as defined by autosave_interval. Writing of the persistence database may also be forced by sending mosquitto the SIGUSR1 signal. If false, the data will be stored in memory only. Defaults to false.

The persistence file may change its format in a new version. The broker can currently read all old formats, but will only save in the latest format. It should always be safe to upgrade, but cautious users may wish to take a copy of the persistence file before installing a new version so that they can roll back to an earlier version if necessary.

This option applies globally.

Reloaded on reload signal.

To receive messages on topics of interest, the client sends a SUBSCRIBE packet to the broker.

caution

Attention

To subscribe to a topic, the subscriber must also set a QoS level of the topic subscription. (#).

  • packetId:

Unique packet identifier.

  • subscriptions:

The limitation on subscriptions a subscriber can subscribe to within one SUBSCRIBE packet is huge.

A SUBSCRIBE packet does not have to have only one subscription. Multiple can be added.

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.

The brokers must make sure the subscribing client receives the messages that are permitted to be received by him in terms of security. But also concerning the QoS level that was set by the publishing client.

Subscribing to several topics simultaneously is an option that's possible. A so-called "wildcard" enables this feature.

Read more about Quality of Service: Quality of Service

  • persistence_file file name

The filename to use for the persistent database. Defaults to mosquitto.db.

This option applies globally.

Reloaded on reload signal.

  • persistence_location path

The path where the persistence database should be stored. If not given, then the current directory is used.

This option applies globally.

Reloaded on reload signal.

  • 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 broker must acknowledge each SUBSCRIBE packet. Therefore the broker sends a SUBACK packet (subscribe acknowledge) to the client.

The broker sends one return code for each topic/QoS-pair that it receives in the SUBSCRIBE packet.

The return codes can be:

  • 0 - Success-Maximum QoS0

  • 1 - Success-Maximum QoS1

  • 2 - Success-Maximum QoS2

  • 128 - Failure

The Success-Maximum QoS0-2 shows the level of Quality of Service (QoS) that is set and can be supported.

  • persistent_client_expiration duration

This option allows persistent clients (those with clean session set to false) to be removed if they do not reconnect within a certain time frame. This is a non-standard option. As far as the MQTT spec is concerned, persistent clients persist forever.

Badly designed clients may set clean session to false whilst using a randomly generated client id. This leads to persistent clients that will never reconnect. This option allows these clients to be removed.

The expiration period should be an integer followed by one of h d w m y for hour, day, week, month and year respectively. For example:

  • persistent_client_expiration 2m

  • persistent_client_expiration 14d

  • persistent_client_expiration 1y

As this is a non-standard option, the default if not set is to never expire persistent clients.

This option applies globally.

Reloaded on reload signal.

The broker filters the incoming messages. In the next step, the filtered message gets forwarded to the subscriber. That’s how the subscriber only receives messages of interest.

As there is no direct link between publisher and client, the publisher can never make sure that somebody is actually "listening" to the messages sent.

The worst case would be that there is no subscriber to the topic, following the broker discards the topic.

In MQTT v5, if a client publishes with QoS 1 or 2 and there is no subscriber, then the broker can tell the publisher this in the PUBACK/PUBREC reply.

  • upgrade_outgoing_qos [ true | false ]

The MQTT specification requires that the QoS of a message delivered to a subscriber is never upgraded to match the QoS of the subscription. Enabling this option changes this behaviour. If upgrade_outgoing_qos is set true, messages sent to a subscriber will always match the QoS of its subscription. This is a non-standard option not provided for by the spec. Defaults to false.

This option applies globally.

Reloaded on reload signal.

  • user username

When run as root, change to this user and its primary group on startup. If set to "mosquitto" or left unset, and if the "mosquitto" user does not exist, then mosquitto will change to the "nobody" user instead. If this is set to another value and mosquitto is unable to change to this user and group, it will exit with an error. The user specified must have read/write access to the persistence database if it is to be written. If run as a non-root user, this setting has no effect. Defaults to mosquitto.

This setting has no effect on Windows and so you should run mosquitto as the user you wish it to run as.

Not reloaded on reload signal.

caution

Attention

MQTT v.3.1.1:

Whenever you disconnect unintendedly and haven't set a cleanSession flag (cleanSession=false) all topic subscriptions are lost. You must resubscribe to every single one again.

In case you have set CleanFlag=false and reconnected with the same clientId, the broker remembers the topics you have subscribed to.

MQTT v.5.0:

The session duration is set by the session expiry interval. (#).

Password Management

Manage password files for Mosquitto.

See Mosquitto Password

// Internal link

 // External link

{

type: 'link',

label: 'Facebook', // The link label

href: 'https://docs.cedalo.com/mosquitto/security',
// The external

URL

},

Add a user to a new password file:

mosquitto_passwd -c /etc/mosquitto/passwd ral

Delete a user from a password file

mosquitto_passwd -D /etc/mosquitto/passwd ral

  • autosave_on_changes [ true | false ]

If true, mosquitto will count the number of subscription changes, retained messages received and queued messages and if the total exceeds autosave_interval then the in-memory database will be saved to disk. If false, mosquitto will save the in-memory database to disk by treating autosave_interval as a time in seconds.

This option applies globally.

Reloaded on reload signal.

  • check_retain_source

This option affects the scenario when a client subscribes to a topic that has retained messages. It is possible that the client that published the retained message to the topic had access at the time they published, but that access has been subsequently removed. If check_retain_source is set to true, the default, the source of a retained message will be checked for access rights before it is republished. When set to false, no check will be made and the retained message will always be published.

This option applies globally, regardless of the per_listener_settings option.

Unsubscribe

A client can always UNSUBSCRIBE from a topic.

  • packetId:

Uniquely identifies a message.

  • List of topics:

The UNSUBSCRIBE packet contains also the topics you want to unsubscribe from.

After the packet is sent, the broker unsubscribes the client from the topics.