# Retained

# Introduction

When the server receives a PUBLISH packet with a Retain flag of 1, it will treat the message as a retained message. In addition to being normally forwarded, the retained message will be stored on the server. There can only be one retained message under each topic. Therefore, if there is already a retained message of the same topic, the retained message is replaced.

When a client establishes a subscription, and there are retained messages with matching topics on the server, these retained messages will be sent to the client immediately. With retained messages, new subscribers can immediately get the latest status without waiting for unexpected time, which is very important in many scenarios.

EMQX Broker enables the function of retaining messages by default. You can modify mqtt.retain_available to false in etc/emqx.conf to disable the function of retaining messages. If the EMQX Broker still receives the retained message when the function is disabled, it will return the DISCONNECT packet with a reason code of 0x9A (retained message is not supported).

# Configuration

EMQX Broker's retained message function is implemented by the emqx_retainer plugin, which is enabled by default. By modifying the configuration of the emqx_retainer plugin, you can adjust the storage location of the retained messages in EMQX Broker, limit the number of received retained messages and the maximum length of Payload, and adjust the expiration time of retained messages. For more information about the EMQX Broker plug-in, see plugin.

The emqx_retainer plugin is enabled by default, and the configuration path of the plugin is etc/plugins/emqx_retainer.conf.

Configuration itemTypeOptional valueDefault valueDescription
retainer.storage_typeenumram, disc, disc_onlyramram: only stored in memory;
disc: stored in memory and hard disk;
disc_only: only stored in hard disk
retainer.max_retained_messagesinteger>= 00The maximum number of retained messages, and 0 means no limit. After the number of retained messages exceeds the maximum limit, you can replace the existing retained messages, but cannot store retained messages for new topics.
retainer.max_payload_sizebytesize1MBRetain the maximum Payload value of the message. After the Payload value exceeds the maximum value, the EMQX broker will treat the retained reserved message as a normal message.
retainer.expiry_intervaldurationThe expiration time of retaining message, and 0 means never expire. If the message expiration interval is set in the PUBLISH packet, the message expiration interval in the PUBLISH packet shall prevail.


EMQX Enterprise can store retained messages to various external databases