Connect a HiveMQ Broker or Edge to the Platform

Deploying or running an MQTT broker on the HiveMQ Platform does not expose the platform to data flowing between the broker and its clients. You must connect your HiveMQ broker deployment to the platform to expose that data to all layers of the platform. Only after connecting can the platform contextualize, analyze, and act on that data. Connecting all your brokers to the platform also allows you to manage their licensing and entitlements centrally.

To connect your HiveMQ broker with the platform, you use the platform to generate a connection string value. The platform registers this value. Next, you apply the generated value to your deployment, and then restart the broker. The platform recognizes this value and connects. The Network view in Connect shows you the current broker state.

You can use the HiveMQ Platform to connect either a HiveMQ broker you deployed with the platform or one running before you adopted it. As you complete the following steps, make sure to follow the specific instructions to connect your preferred deployment option, such as a Local Install or a Docker Deployment.

Before You Begin

Before you connect a broker or an edge to the platform, you must have:

A running HiveMQ broker or edge, version HiveMQ 4.53 or later.
Filesystem access to the deployment, so that you can create configuration files and restart the broker.

Step 1: Generate a Connection String

On Connect, click Get Broker or Edge.
On How do you want to get started?, select Connect what you already run.
Select HiveMQ Broker or HiveMQ Edge, then click Continue.
Enter a name and an optional description. The name is the display name shown in the broker and edge list.
Click Generate connection string. A generated string value displays.
In Connection string, copy the generated string value. In the next step, you add this value to your deployment.

When you generate the connection string, the instance appears in the Network view on the Connect page with a Data Intelligence state Ready to connect. This state shows that the instance is eligible for Data Intelligence, but the connection process is not yet complete. For more details about each state, see Connect - The Network View.

Step 2: Add a Connection String to Your Deployment

A broker connects to the platform through a configuration file that is not part of the default HiveMQ distribution. You create this configuration file within your HiveMQ deployment. The configuration file location and the way you persist the file depend on how the broker runs.

Local Install

Create pulse/conf/config.xml directly under your HiveMQ home directory.
1. In your HiveMQ home directory, create a folder named pulse.
2. Inside the pulse folder, create a sub-folder named conf.
3. Inside pulse/conf, create a file named config.xml. Use the following structure and paste the connection string you copied into the <connection-string> element:
  <HIVEMQ_HOME>/pulse/conf/config.xml
  <pulse> <enabled>true</enabled> <bootstrap>true</bootstrap> <agent> <connection-string>YOUR_PLATFORM_CONNECTION_STRING</connection-string> </agent> </pulse>
  Do not add spaces inside the <connection-string>…</connection-string> element value.

Save the file.

The resulting layout inside your HiveMQ home directory is:

<HIVEMQ_HOME>/
└── pulse/
    └── conf/
        └── config.xml

Restart the broker.
```
./bin/run.sh
```

Docker

In the official HiveMQ Docker image, the HiveMQ home directory is /opt/hivemq. To connect a Docker deployment to the platform, you create a pulse/conf/config.xml configuration file under the HiveMQ home directory inside the deployment container. To add the configuration file to the container, complete the following steps:

Confirm the HiveMQ home directory exists inside the container:
```
docker exec <container_name> ls /opt/hivemq
```
A successful listing confirms the path:
```
audit  backup  bin  conf  data  extensions  license  log  README.txt  third-party-licenses  tools
```
If the path does not exist, ls returns No such file or directory.

Choose how to persist your configuration.

You can add the configuration file in two ways:

Method	When to Use
Edit files inside the running container	Use for quick tests or validation in a temporary or development container. Docker discards your changes when you remove or recreate the container.
Bind-mount from the host (Recommended)	Use in any environment where you redeploy or rebuild the container, including production and CI/CD workflows.

Method

When to Use

Edit files inside the running container

Use for quick tests or validation in a temporary or development container. Docker discards your changes when you remove or recreate the container.

Bind-mount from the host (Recommended)

Use in any environment where you redeploy or rebuild the container, including production and CI/CD workflows.

To edit files inside the running container:
1. Run the following commands. Replace <container_name> with your container name. Replace YOUR_PLATFORM_CONNECTION_STRING with the connection string that you generated from the HiveMQ Platform:
  docker exec <container_name> mkdir -p /opt/hivemq/pulse/conf docker exec -i <container_name> sh -c 'cat > /opt/hivemq/pulse/conf/config.xml' <<'EOF' <pulse> <enabled>true</enabled> <bootstrap>true</bootstrap> <agent> <connection-string>YOUR_PLATFORM_CONNECTION_STRING</connection-string> </agent> </pulse> EOF
  Do not add spaces inside the <connection-string>…</connection-string> element value.
  
  Do not run ./bin/run.sh inside the container. The script starts a second broker instance that conflicts with the running broker on the same ports.
2. Restart the container to restart the broker:
  docker restart <container_name>

To Bind-mount from the host (Recommended):

Docker cannot attach a volume mount to a container after the container starts. To use this method on a running container, replace the running container with a new container that has the mount in place from startup.

Create the folder structure on the host. Replace <HOST_PULSE_DIR> with a directory path on your host (for example, ~/hivemq-pulse). Replace YOUR_PLATFORM_CONNECTION_STRING with the connection string that you generated from the HiveMQ Platform:
```
mkdir -p <HOST_PULSE_DIR>/conf
cat > <HOST_PULSE_DIR>/conf/config.xml <<'EOF'
<pulse>
    <enabled>true</enabled>
    <bootstrap>true</bootstrap>
    <agent>
        <connection-string>YOUR_PLATFORM_CONNECTION_STRING</connection-string>
    </agent>
</pulse>
EOF
```
Do not add spaces inside the <connection-string> element.

Stop, inspect, and then remove the running container. Docker requires this step to attach the new mount:

The new container must repeat every option from your original Docker run command: environment variables, data and license volumes, cluster settings, and port mappings. If the original container stored broker data without a volume, that data is lost when you remove the container. Inspect your original container and ensure that the new container includes these options before you remove your original one.

docker stop <container_name>
docker inspect <container_name>
docker rm <container_name>

Start a new container with your original options plus the Pulse mount. The -v flag mounts <HOST_PULSE_DIR> (the directory from step 1) into the pulse subdirectory of the HiveMQ home directory:
```
docker run -d --name <container_name> \
  -p 8080:8080 -p 1883:1883 \
  -v <HOST_PULSE_DIR>:/opt/hivemq/pulse \
  hivemq/hivemq4:latest
```
You can now edit config.xml directly on the host. The broker applies your changes after you restart the container (for example, docker restart <container_name>).

To learn more about HiveMQ clustering with Docker, see Run HiveMQ on Docker.

Kubernetes

Provide the Pulse configuration to the HiveMQ Platform Operator. The operator manages the configuration as a Kubernetes Secret. For the pulse configuration options (inline data, an existing Secret by name, or overridePulseConfig from a file), see HiveMQ Pulse Configuration Options.

Step 3: Confirm Your Connection

When the broker restarts, it connects to the platform with the configured connection string. Upon successful connection, the instance status in Connect changes from Ready to connect to Connected. If the instance does not connect, check the path to the configuration file, check the connection string, and confirm that the broker restarted.

Next Steps

To see more context about the data that now streams through your connected broker, see Discovery.
To license your HiveMQ broker, see Get a License.

For More Information

To learn more about using the Network view to manage connections, see Connect - The Network View.