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

![Random Message Routing for Shared Subscribers](https://2154816337-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LOvr-CQz8jJxldqmC1L%2F-LgbmZkARd5Vww4QYTVr%2F-LgbmhdYt6UbZ0Lk0TfZ%2Frandom.svg?alt=media\&token=863e4c09-6d8b-49aa-bb41-1d46a7306b2e)

![Local Only Message Routing for Shared Subscribers](https://2154816337-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LOvr-CQz8jJxldqmC1L%2F-LgbmZkARd5Vww4QYTVr%2F-LgbmvLfhnu8etSiyOll%2Flocal_only.svg?alt=media\&token=767b66e4-6ad9-4c0d-a66a-1b1f31270595)

![Prefer\_local Message Routing for Shared Subscribers](https://2154816337-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LOvr-CQz8jJxldqmC1L%2F-LgbmZkARd5Vww4QYTVr%2F-Lgbn4JRRixncbe0XZJj%2Fprefer_local.svg?alt=media\&token=8f9ffbf8-09f4-4d73-88c8-45ff9fe8fca1)

{% 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"
```