Bridging Guide

This page contains a step-by-step guide for connecting (bridging) two OpenDXL Brokers to one another.

Create Docker Containers for Two OpenDXL Brokers

Follow the Install OpenDXL Broker steps to create a Docker container for the first broker, broker1.
Follow the installation steps again to create a Docker container for a second broker, broker2.

Generate a New Broker Keystore

As part of the bridging setup, the default keystore which the second broker generates for itself at startup will be replaced with a new keystore which the first broker generates. This allows for each of the certificates that the brokers use to have been created from the same certificate authority.

Browse to the Generate Configuration page in the OpenDXL Broker Management Console on the first broker.

A page similar to the following should be displayed:
Change the value in the Configuration Type field to Broker Keystore.
Specify a value for the Common Name field to use in the certificate for the second broker.

The only required field in the form is Common Name which is a human readable name that can be used to identify the certificate.
Press the Generate button.

A zip file named opendxlbrokerkeystore.zip should be downloaded to a local file.
In the keystore directory under the second broker's Docker Volume (/dxlbroker-volume), delete all of the existing files.
Extract all of the files from the opendxlbrokerkeystore.zip file into the second broker's keystore directory.

Establish the Bridging Configuration

The steps below involve modifying the configuration and policy files on the two brokers to establish a bridge to one another.

In a text editor, open the dxlbroker.conf.defaults file in the config directory under the first broker's /dxlbroker-volume directory.

Set the value for the brokerId to a unique value and save the file.

For example:
```
brokerId=broker1
```
NOTE: The value that you select will be used when specifying broker bridging configuration in a later step.
In a text editor, open the dxlbroker.conf.defaults file in the config directory under the second broker's /dxlbroker-volume directory.

Set the value for the brokerId setting to a unique value and save the file.

For example:
```
brokerId=broker2
```
In a text editor, open the brokerstate.policy file in the policy directory under the first broker's /dxlbroker-volume directory.

Set the contents similar to the following:
```
{
  "hubs": [],
  "brokers": [
    {
      "id": "broker1",
      "hostname": "10.0.0.1",
      "port": "8883"
    },
    {
      "id": "broker2",
      "hostname": "10.0.0.2",
      "port": "58883",
      "parentId": "broker1"
    }
  ]
}
```
An entry should be present in the brokers array for each of the two brokers.

The id value for each broker should match the brokerId value from the broker's dxlbroker.conf.defaults file.

The values for hostname and port should be what the brokers use to connect to one another. These should correspond to the IP address and port which were configured for the Docker container. See the Configure Container Ports documentation for more information.

The parentId entry for the second broker should be set to the brokerId value for the first broker, which, in this case, is broker1.

For more information on the content of the brokerstate.policy file, see the brokerstate.policy documentation.
Copy the brokerstate.policy file which was modified in the previous step to the policy directory under the second broker's /dxlbroker-volume directory.
Restart each of the broker containers.

At this point, the two brokers should be bridged to one another.

Validate Broker Bridging

The steps below involve sending and receiving a DXL event between the two brokers. If this process is successful, the brokers have been bridged to one another.

Browse to the Fabric Monitor page in the OpenDXL Broker Management Console on the first broker.
Click on the + Add button on the Subscriptions tab.
In the text box which appears under the + Add button, enter /testevent as the event topic for subscription.
Without closing the Fabric Monitor page for the first broker, browse to the Fabric Monitor page in the OpenDXL Broker Management Console on the second broker.
Under the Send Message tab, enter /testevent for the Topic and hello for the Payload and press the Send Message button to send the event.
Return to the Fabric Monitor page for the first broker.

If the two brokers have been successfully bridged together, the /testevent message should have been received by the first broker and information for the message should appear on the Fabric Monitor page: