Mosquitto MQTT Bridge-Usage and Configuration

The Mosquiito broker (server) can be configured to work as an MQTT bridge.

A bridge lets you connect two MQTT brokers together.

They are generally used for sharing messages between systems.

A common usage is connect edge MQTT brokers to a central or remote MQTT network.

Generally the local edge bridge will only bridge a subset of the local MQTT traffic.


In addition you only need to configure 1 of the brokers to act as the bridge, the other will act as a normal broker.

How it Works

When you configure the mosquitto broker as a bridge it becomes an MQTT client and subscribes and publishes to topics on the other broker and itself depending on the entries in the mosquitto.conf file.


Configuring the Broker

You will need to configure

  • The Address and port of the remote broker or brokers. – Address keyword
  • A client name. – Connection keyword
  • What topics the broker will publish, and which topics it will subscribe to. -topic keyword
  • Remapping if needed.

Note: You can configure multiple remote broker addresses and the broker will switch to another broker if the current broker connection fails.

Topic Bridging

What topics are being bridged and if they are being remapped is controlled by the topic entry.

The general format is

topic topic pattern direction QOS local prefix/remote prefix.

Direction can be out,in or both.


topic house/sensor1 both 0 “” “”

direction both (could also be in and out)

The entries:
topic house/sensor1 in 0 “” “”
topic house/sensor1 out 0 “” “”

Are equivalent to the single entry:

topic house/sensor1 both 0 “” “”

The screen shot below shows how to bridge all topics with no remapping.


With the above configuration then:

  • When a Client connected to broker 1 publishes on any topic that message will be sent to broker 2 . Example incoming message on topic house/sensor1 are published to broker 2 on topic house/sensor1.
  • When a client connected to broker 2 publishes a message then messages published on any topic are sent from broker2 to broker 1.

Note: The messages are sent from broker 2 to broker 1 because broker1 subscribed to that topic on broker 2

Topic remapping is accomplished using topic prefixes.

The topic prefixes follow the QOS entry.

The screen shot below shows a remapping configuration for broker 1:mosquitto-bridge-config-remapping

With the above configuration then:

  • When a Client publishes on any topic that message will be sent to broker 2 with the topic prefix b2/. Example incoming message on topic house/sensor1 is published to broker 2 on topic b2/house/sensor1.
  • When a client publishes a message to broker2 then messages published on b2/# are sent from broker2 to broker 1 but without the b2/ prefix. A message published to broker 2 on house/sensor1 is not sent to broker 2

Broker 2 Configuration

Broker2 is functioning as a normal broker (not a bridge) and doesn’t normally need any extra configuration.

Topic Bridging and Remapping

This is accomplished using the local and remote prefixes.

When the bridge on broker1 subscribes to a topic on broker2 it uses the form

remote_prefix + topic name e.g. b2/house/sensor1

When the bridge on broker1 subscribes to a topic on broker1 it uses the form:

local_prefix + topic name e.g. b1/house/sensor1

The following diagram illustrates the general process.



Bridging and Topic Remapping Examples

The following examples refer to the schematic above with two brokers broker1 and broker2 . Broker1 is configured as the bridge.

Normal clients will also be connected to both brokers.


topic house/sensor1 both 0 “” “” or

topic house/sensor1 both 0

Also Equivalent to

topic house/sensor1 out 0
topic house/sensor1 in 0


Incoming messages from a client connected to broker1 to a topic house/sensor1 are being bridged and will be sent to broker2 on topic house/sensor1.

Incoming messages from a client connected to broker2 on the topic house/sensor1. will be sent to broker1 on topic house/sensor1.

Entry uses remote prefix:

topic house/sensor1 both 0 “” b2/

Equivalent to

topic house/sensor1 out 0
topic house/sensor1 in 0 “” b2/


Incoming messages from a client connected to broker 1 on the topic house/sensor1 are being bridged and will be remapped and sent to broker2 on topic b2/house/sensor1.

Incoming messages from a client connected to broker2 on topic b2/house/sensor1. will be sent to broker1 on topic b2/house/sensor1..

Broker1 removes the b2 prefix and will send them to clients subscribed to house/sensor1 on broker 1.

Entry uses local and remote prefixes:

topic house/sensor1 both 0 b1/ b2/

this is the same as:

topic house/sensor1 out 0 b1/ “”
topic house/sensor1 in 0 “” b2/


Incoming messages from a client connected to broker1 on topic b1/house/sensor1 are being bridged and will be remapped and sent to broker2 on the topic b2/house/sensor1.

Incoming messages from a client connected to broker2 on the topic b2/house/sensor1. will be sent to broker1 on topic b2/house/sensor1.

Broker 1 removes the remote prefix (b2/) and then adds the local prefix (b1/) and will send them to clients subscribed to b1/house/sensor1 on broker 1

Working Example

Using the configuration shown above on broker 1 I am going to publish a message to broker 1.

Broker 1 has the bridge configured to connect to broker2 (IP address

The topic bridging entry is:

topic # both 0 “” b2/

Broker 1 accepts messages and publishes them to broker 2 with a prefix of b2/.

Broker 1 subscribes to messages from from broker 2 on topic b2/#

Using a simple python client we will :

  • Publish a message to broker1 on topic house/sensor1. Using a client name of P1
  • Subscribe to broker2 on topic b2/house/sensor1 -Using client name of P2


When you start the broker on broker 1.

  • It connects to broker 2 and subscribes to the topics b2/#.
  • Connects to itself and subscribes to topic #

This can be seen from the console log messages:


When I run the script this is what I see.


Broker 1 receives message on topic house/sensor1 and publishes them to broker2 on b2/house/sensor1.

Broker2 receives messages on b2/house/sensor1 from broker1.

Backwards Testing

I can also publish to broker 2 on topic b2/house/sensor1 and it should be sent to broker 1 and made available as house/sensor1.

So now I will alter my script to send to broker 2 on topic b2/house/sensor1 and subscribe to house/sensor1 on broker 1.

Here is a screen shot of the results.


Notice the message is received by the client subscribed to broker 1 n the topic house/sensor1

Topic Remapping and Topic Republishing

Topic remapping takes an incoming topic and renames it.

E.g A broker would receive messages to topic sensor1 and remap them to new_sensor1.

Currently this form of remapping is not available, but prefix remapping is as shown above.


Topic republishing is done using an MQTT client and not a broker.

It can be used for more sophisticated remapping schemes but generates more traffic. See this python code example.

Bridging to Multiple Brokers- Round Robin

It is possible to bridge to another broker in the event of a broker failure.

To do so you need to set multiple address:port entries in the address field i.e


will use broker if the connection to the first broker ( fails.

The round robin setting controls what happens when the original connection is restored. Here is the description taken from the online manual:


Authentication and Encryption

If the remote broker requires a username and password then you need to enter this using the remote username and remote password options.


You can also encrypt the connection between the brokers. This is likely to be a common configuration and Is covered in more detail in the Configure Mosquitto Bridge With SSL Encryption- Examples tutorial.


Publishing and subscribing to the same topic on the broker could result in a loop.

However if you try this you find that a broker detects that another broker sent the message, and doesn’t send the message back to it even though the broker has subscribed to that topic.

This confused me at first as looking through the specs I couldn’t find any reference for broker detection.

I did find this comment from Roger Light on a forum that explains it.


This seems to be triggered by the try private statement in the configuration file. This is what the config file states:

# If try_private is set to true, the bridge will attempt to indicate to the
# remote broker that it is a bridge not an ordinary client. If successful, this
# means that loop detection will be more effective and that retained messages
# will be propagated correctly. Not all brokers support this feature so it may
# be necessary to set try_private to false if your bridge does not connect
# properly.
#try_private true

Bridging to Thingspeak Note

I had a request for help regarding bridge configuration on mosquitto when creating a bridge to thingspeak.

If you need to do this you need the following two entries:

notifications flase
cleansession true

See this forum comment

Problems Encountered

When configuring bridges you may encounter some issues. Here are some of the errors I’ve encountered.

Error message on broker –socket error on client <unknown>disconnecting

Cause – Configuration file error. In my case it was the PSK setting.

Problem – Remapping not working as it should.

Cause -I forgot the QOS entry


If you prefer videos I’ve created a video on Configuring a bridged connection on Mosquitto

Related Articles and Resources:

Mosquitto Configuration Tutorials



  1. I tried to make a bridge with with mosquitto version 1.4.14 on Windows and the results worked. but when I tried it with version 1.5.4 the result failed, the error statement was “unknown error”, this happened when the local broker tried to connect to the remote broker (
    This works when I make a bridge with a remote broker on the same PC

    1. Hi
      I have had others complain of bridge problems with mosquitto 1.5.4. I haven’t had chance to test it but it is probably nothing you are doing wromg.

  2. How to establish a TCP Bridge connection.
    Trying to TCP Bridge Mosquitto with EMQ.
    Included the bridge connection in my mosquitto.conf
    connection emq
    topic AB/# both 2

    The IP address mentioned above is an IP of a different system. And also setup the port at 2883.
    But the very rarely does the connection happen. It fails 95% of the times.
    Where am i making a mistake?

    1. Difficult to say. The mosquitto conf file that you included looks ok but missing a line like
      connection bridge-emq
      If that doesn’t work make sure that you can connect to emq using a normal client as it might have other restriction e.g authentication configured.
      Let me know how you get on.

  3. Hi steve, can we increase client connection limit from default 1024 to 10,000 in mosquitto?
    I don’t find a proper solution from internet…so, it would be great for me if you can help in this problem..
    Thank you!

    1. From what I understand you can use -1 and have unlimited connections but the docs say that you might hit problems when you go over 1024.
      # The maximum number of client connections to allow. This is
      # a per listener setting.
      # Default is -1, which means unlimited connections.
      # Note that other process limits mean that unlimited connections
      # are not really possible. Typically the default maximum number of
      # connections possible is around 1024.
      #max_connections -1

  4. I am using Mosquitto MQTT Bridge between local gateway & remote MQTT broker server. It is working fine but when internet connection down then all topic published locally will not publish to broker when reconnect to internet even though QOS level is set to 2 and clean session flag is false so how can I ensure high quality of level between local MQTT bridge & remote MQTT broker without making retain topics. Is there any configuration from which local MQTT bridge ensure all topic sends to remote MQTT broker as or when internet connection resume?

    1. It is not just the QOS on the bridge. Yoy need to be publishing to the bridge with a qos of 1 or 2 and subscribing on the remote broker with a qos of 1 or 2 and it should work.
      You should also note that mosquitto has a limit of 100 messages (default) setting that it will hold in a queue.

  5. HI Steve
    I added following entry in broker2 mosquitto.conf file

    connection Bridge1
    topic # both 0 “” b0/

    That’s broker-2 as bridge, Broker1 as normal broker

    Started normal broker first(broker1) and then bridge broker (broker2) later.

    Used mosquitto_pub and mosquitto_sub to verify.

    Case 1: Publishing from Broker2
    # broker2:~# mosquitto_pub -t chassis/PSU0 -m “PSU0 is ON”
    # broker1:~# mosquitto_sub -t b0/chassis/PSU0
    PSU0 is ON

    Case 2: Publishing from Broker1
    #broker1:~# mosquitto_pub -t chassis/PSU0 -m “PSU0 is ON”
    #broker2:~# mosquitto_sub -t chassis/PSU0
    PSU0 is ON

    Broker2 publishes them to broker1 with a prefix of b0/
    Broker2 subscribes to all messages from broker1 with no prefix, is that correct ? I thought there would be /b0 this case as well.

    Please clarify

    1. No broker2 should subscribe to broker 1 using the prefix.
      When you publish a message to broker1 then any message not beginning with the prefix b0/ isn’t sent to broker2.

      When you send a message to broker2 it should send it to broker1 with the prefix.
      In this case the prefix is both ways in and out.

  6. Hi
    Thank you first
    I have question about bridge
    Assume my broker can accept 10k users
    If i use bridge,my brokers can 20k users?

  7. Hi Steve,

    Great article. Quick question. Is there a practical limit to the number of brokers that can be bridged? In my project, I will have 100s of remote mqtt brokers. I’d like to pass status information from the remote brokers to my main cloud broker. The above configurations work great, but I’m unsure if there is a limit to the number of bridge connections (assuming the could version has the power to handle all of the incoming messages) a single instance can support.


    1. Shouln’t be a problem as the cloud broker sees client connections it is the edge broker that is configured to be a bridge. The edge broker only needs to support 1 bridge to the cloud broker or 2 if you want a standby cloud broker.
      Does that make sense?

  8. Hi Steve,
    When I bridge two mosquitto brokers in same laptop, it works. But not able to bridge two brokers in same network but both are running in different laptops. What could be the issue? Below is my configuration,
    connection bridge-01
    topic # out 0
    topic # in 0

    please suggest


      1. Thanks Steve for prompt response.solved.

        I am trying to setup mosquitto cluster. Is it possible to achieve High availability(HA) and Load balancing(LB)?
        As per my understanding, If I want to have cluster setup at cloud for HA and LB where mqtt gateways can publish data. It is not possible with mosquitto to achieve . Better I should choose another mqtt broker which gives HA/LB support and suitable for cloud.
        Is my understanding correct? please suggest


        1. I haven’t looked at clustering mosquitto but I’ve seen several comments around the web saying you can’t do it.
          You might want to look at HiveMQ

  9. i was getting “socket error on client (client id), disconnecting”
    could you please help me why this error occurred and how to resolve this

    1. Where are you getting the error? Does it occur on the broker that the bridge is trying to connect to? Do you have any security configured on the broker?

  10. Is bridging suitable for HA architecture where I want to have say three brokers that all share clients’ data?My concern is that it seems that even with Round Robin there is only one bridge so if that bridge broker goes down then HA breaks – am I missing something?

    1. HA?
      You’re correct the bridge is the weak link. The only alternative is to get the clients to publish to two brokers but that isn’t really practical.
      Bridging doesn’t give you any kind f resilience it is only meant to connect brokers together so that they can share topics.

  11. I am currently running a mosquito broker. I need to bridge this with mqtt broker running on So as per your idea I need to do configuration on my mosquito.config file.Is it wright. I need to pass all messages publish all topics to remote broker and vice versa. Please provide comment on this

    1. Yes
      Edit the config file and start by bridging all topics. Once it is working ok then you can change it to only bridge selected topics.

  12. In the simple configuration you have

    topic # out 0 “” b1/
    topic # in 0 “” b1/

    But later you say

    When the bridge on broker b1 subscribes to a topic on b2 it uses the form
    remote_prefix + topic name e.g. b2/house/sensor1

    Where does the b2 come from? I see no mentioning of b2 in the simple config.
    Do you mean
    topic # in 0 “” b2/

    1. b2 is the remote prefix.The prefix is only used if you want topic remapping.You can use any prefix you want b2 is just an example.
      I’ll reread the tutorial over the next few days and check to make sure the examples are OK as I remember when I was doing it it got confusing.

  13. Hi Steve,
    I am newbie in MQTT. I am using a Mosquitto broker in my laptop for home automation applications. It has worked well for local network but not for remote one. Could you guide me to configure the Mosquitto broker in order to access from outside network?
    Many thanks in advance.
    Vince Tran

  14. Hello Steve,

    Very nice explanation on how to get this done. Could you please explain how to do this if say broker 2 has a username and password set up or TLS? Is it possible to configure in Broker 1, which is being used as the bridge a user name and password so it can access broker 2’s topic and publish to it?

    Thanks and expecting your reply soon.

      1. Hello Steve,

        Thanks for the quick response. I will be checking for the update, as I am in the middle of trying to develop my system now.

        Kind regards

      2. Hello Steve,

        I am just putting together this configuration, but I don’t seem to understand where this configuration is to be. Is it a different script, or this is to be inputted into the mosquitto.conf file found in /etc/mosquitto/.


        1. When Linux start mosquitto it will use the mosquitto.conf file in the /etc/nosquitto folder. So if you want to start mosquitto automatically then you need to place your changes in the mosquitto.comf file. If you start mosquitto manually from the command prompt which is normal when testing the you can use any conf file as you tell mosquitto which file to use using the -c switch. I use a file called m1.conf as it is short and easy to type. So I start mosquitto
          mosquitto -c m1.conf

          1. Hello Steve,

            Many thanks for your quick responses, as I am beginning to get a hang of it now. The “connection “, what name exactly am I supposed to use, as can I just give it any name of my choice? below is my config, but the bridge seems not to be able to do anything as its finding it difficult to connect to my other broker:

            #connection bridge-01
            connection bridge-01

            topic home/sensor both 0 “” “”


            Please is there something I am missing?


          2. Hello Steve,

            Many thanks for your quick responses, as I am beginning to get a hang of it now. The “connection bridge-01 “, what name exactly am I supposed to use, as can I just give it any name of my choice? below is my config, but the bridge seems not to be able to do anything as its finding it difficult to connect to my other broker:

            #connection bridge-01
            connection bridge-01

            topic home/sensor both 0 “” “”

            remote_username myusername
            remote_password mypassword

            Please is there something I am missing?

            Sorry had to send it again, as some text went missing in the last one I sent, and seems I can’t edit.


  15. Hi,

    can you help on below issue , as my another bridge server denied publishing the data.

    1492491690: | — mosquitto_auth_acl_check(…, local.KIBANA-BRIDGE-USER, AnonymouS, smart/, MOSQ_ACL_WRITE)
    1492491690: | — mysql: topic_matches(smart, smart) == 0
    1492491690: | — aclcheck(AnonymouS, smart/, 2) AUTHORIZED=0 by (null)
    1492491690: | — Cached [86CCE31BFEB0B45E07246624715795ACE9151C96] for (local.KIBANA-BRIDGE-USER,AnonymouS,2)
    1492491690: Denied PUBLISH from local.KIBANA-BRIDGE-USER (d0, q0, r0, m0, ‘smart/’, … (17 bytes))

    1. Hi
      I would look at the topic name as I’m not sure about the comma. Then I would see i the bridge as an access control list configured as that is when I’ve seen the publish denied message.
      What broker are you using for the bridge?

Leave a Reply

Your email address will not be published. Required fields are marked *