# Shared subscriptions

A shared subscription is a mechanism for distributing messages to a set of subscribers to shared subscription topic, such that each message is received by only one subscriber. This contrasts with normal subscriptions where each subscriber will receive a copy of the published message.

A shared subscription is on the form `$share/sharename/topic` and subscribers to this topic will receive messages published to the topic `topic`. The messages will be distributed according to the defined distribution policy.

{% hint style="success" %}
When subscribing to a shared subscription using command line tools remember to quote the topic as some command line shells, like `bash`, will otherwise expand the `$share` part of the topic as an environment variable.
{% endhint %}

## Configuration

Currently three message distribution policies for shared subscriptions are supported: `prefer_local`, `random` and `local_only`. Under the `random` policy messages will be published to a random member of the shared subscription, if any exist. Under the `prefer_local` policy messages will be delivered to a random node-local member of the shared subscription, if none exist, the message will be delivered to a random member of the shared subscription on a remote cluster node. Under the `local_only` policy message will be delivered to a random node-local member of the shared subscription.

```
shared_subscription_policy = prefer_local
```

When a messages is being delivered to subscribers of a shared subscription, the message will be delivered to an online subscriber if possible, otherwise the message will be delivered to an offline subscriber. Notice that the shared subscription policy is applied before considering online or offline status of clients.

![Prefer local policy](/files/-LrIt-SbK1skEkg0Llae)

![Local only policy](/files/-LrIt68UcHxtcGF_ogzO)

![random policy](/files/-LrItCHH6D70hz4svZg-)

{% hint style="info" %}
Note that Shared Subscriptions still fully operate under the MQTT specification (be it MQTT 5.0 or backported to older protocol versions). Be aware of this, especially regarding QoS and clean\_session configurations.
{% endhint %}

## Examples

**Subscriptions** *Note: When subscribing to a shared topic, make sure to escape the* `$`

So, for dash or bash shells

```bash
mosquitto_sub -h mqtt.example.io -p 1883 -q 2 -t \$share/group/topicname
mosquitto_sub -h mqtt.example.io -p 1883 -q 2 -t \$share/group/topicname/#
```

**Publishing** *Note: When publishing to a shared topic, do not include the prefix* `$share/group/` *as part of the publish topic name*

```bash
mosquitto_pub -h mqtt.example.io -p 1883 -t topicname -m "This is a test message"
mosquitto_pub -h mqtt.example.io -p 1883 -t topicname/group1 -m "This is a test message"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vernemq.com/1.9.0/configuration/shared_subscriptions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.