> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-core/guides/developing-applications/configuring-messaging/configuring-bus-connections.md).

# Configuring Bus Connections

Message bus configuration is split between **global** (shared structure) and **per-microservice** (connection details) concerns.

## Understanding Configuration Scope

**Global Configuration** defines the abstract bus structure shared across microservices:

* Bus names
* Channel catalog (channel names, QoS, key patterns)

**Per-Microservice Configuration** defines connection details specific to each microservice:

* **Connection descriptors** - Provider, address, credentials, and connection properties

{% hint style="info" %}
**Connection Descriptor Placement**: While connection descriptors are conceptually per-microservice configuration, they are physically specified in the global `<buses>` section. This allows most descriptor properties to be shared while using **substitution parameters** to provide microservice-specific values (such as credentials or client IDs) in each microservice's configuration.
{% endhint %}

## Global Bus Structure

The abstract bus structure is defined in the `<buses>...</buses>` section of the configuration DDL. This structure defines the bus name and the catalog of available channels.

### Bus Properties

The following properties define the global bus structure:

<table><thead><tr><th width="137.98712158203125">Property</th><th width="190.28448486328125">Required/Optional</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>Required</td><td>The (unique) name of the bus. This name is used by microservices to reference the bus.</td></tr><tr><td>displayName</td><td>Optional, default=null</td><td>The (non-unique) display name of the bus.</td></tr><tr><td><strong>enabled</strong></td><td>Optional, default=true</td><td>Used to enable/disable the bus.</td></tr><tr><td><strong>channels</strong></td><td>Optional</td><td>The set of channels contained in the bus (the channel catalog). See below for channel properties.</td></tr></tbody></table>

### Channel Properties

The following are the set of global bus channel properties.

<table><thead><tr><th width="136.3797607421875">Property</th><th width="267.55499267578125">Required/Optional</th><th>Description</th></tr></thead><tbody><tr><td><strong>id</strong></td><td>Optional, default=&#x3C;not present></td><td>The channel id. If present, it must be unique across all channels in the bus since it is used, in lieu of the channel name to uniquelt identify the channel in the bus system wide i.e., it is used, in lieu, of the name in the SMA metadata on the wire to identify the channel on which a message has travelled on the bus.</td></tr><tr><td><strong>qos</strong></td><td>Optional, default=Guaranteed</td><td>The channel quality of service. The value of this property must be either <strong>BestEffort</strong> or <strong>Guaranteed</strong></td></tr><tr><td><strong>key</strong></td><td>Optional, default=null</td><td>The channel key</td></tr></tbody></table>

## Connection Descriptor

The connection descriptor specifies how a microservice connects to the underlying messaging bus. **Connection descriptors are conceptually per-microservice configuration** - each microservice instance typically requires its own connection values (credentials, client IDs, provider-specific settings).

While physically specified in the global `<buses>` section, connection descriptors use **substitution parameters** to enable per-microservice values. The actual values are provided in the `<container>` section's `<env>` elements, allowing different microservice instances to connect with different credentials while sharing the same bus structure.

### Descriptor Format

A connection descriptor can be specified in two forms:

{% tabs %}
{% tab title="Non-Decomposed Format" %}
The descriptor can be specified as a single connection string using the format:

```
<provider>://<address>[:<port>][&prop1=value1][&prop2=value2]...
```

**Example:**

```xml
<bus name="sample-bus" descriptor="activemq://localhost:61616&set_key_on_receipt=true">
  <channels>
    <channel id="1" name="new-orders-channel">
      <qos>Guaranteed</qos>
      <key>NEWORDERS/${Region}/${Department}</key>
    </channel>
  </channels>
</bus>
```

{% endtab %}

{% tab title="Decomposed Format" %}
The descriptor can be decomposed into separate DDL elements:

```xml
<bus name="sample-bus">
  <provider>activemq</provider>
  <address>localhost</address>
  <port>61616</port>
  <properties>
    <set_key_on_receipt>true</set_key_on_receipt>
  </properties>
  <channels>
    <channel id="1" name="new-orders-channel">
      <qos>Guaranteed</qos>
      <key>NEWORDERS/${Region}/${Department}</key>
    </channel>
  </channels>
</bus>
```

{% endtab %}
{% endtabs %}

Both formats support substitution parameters for per-microservice values:

```xml
<bus name="orders-bus">
  <provider>solace</provider>
  <address>${solace.host}</address>
  <port>${solace.port}</port>
  <properties>
    <username>${solace.username}</username>
    <password>${solace.password}</password>
  </properties>
</bus>
```

### Provider-Agnostic Properties

The following connection properties are supported across all messaging providers.

#### Message Receipt

| Property                           | Default | Description                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `set_bus_and_channel_on_receipt`   | false   | Controls whether the bus and channel name are set on received messages. Setting the channel and bus name on inbound messages incurs performance overhead. Performance sensitive applications should avoid enabling this property.                                                                                                                                                                   |
| `set_key_on_receipt`               | false   | Controls whether the message key is set on received messages. Not all binding implementations transport the key on the wire; this property has no effect for bindings that don't transport the key. Setting the key on inbound messages incurs a performance overhead. Performance sensitive applications should avoid enabling this property.                                                      |
| `set_sno_on_receipt`               | true    | Controls whether the message sequence number is set on received messages. If set to false, inbound messages surfaced to the AEP engine and application will not have the sequence number set regardless of whether the sender was configured to set sequence numbers in outbound messages. Incurs a slight performance overhead when enabled.                                                       |
| `enable_inbound_transport_headers` | false   | Controls whether transport headers are set in inbound messages. Setting this to true causes bindings that support this functionality to set transport-specific headers in the metadata section of inbound messages. Not all binding implementations support this. Enabling this fosters tighter coupling between the application and specific message bindings, which is generally not recommended. |

#### Wire Metadata

| Property               | Default | Description                                                                                                                                                                                                              |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sma_metadata_version` | 2       | Controls the version of SMA message metadata encoded in outbound messages. The metadata version used must be supported by all downstream receivers that inspect the property.                                            |
| `raw_mode`             | false   | Controls whether the binding operates in raw mode (without SMA metadata). Messages sent through raw bindings do not set SMA metadata, and messages received through a raw binding are expected to not have SMA metadata. |

#### Topic Resolution

| Property                    | Default | Description                                                                                                                                                                                  |
| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `topic_starts_with_channel` | true    | Controls whether topic names start with the channel name for the bus. For bus bindings that support topic routing, this controls whether the resolved key is prefixed with the channel name. |

#### Channel Resolution

| Property                    | Default | Description                                                                                                                                                                                                        |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `auto_add_catchall_channel` | false   | Controls whether a catchall channel is automatically added to the bus descriptor when the binding is created. When enabled, a catchall channel is added provided one is not already present in the bus descriptor. |

#### Message Sending

| Property                  | Default | Description                                                                                                  |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `enable_concurrent_sends` | false   | Controls whether sends through the message bus binding can be performed concurrently using multiple threads. |

#### Configuration

| Property                     | Default | Description                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `additional_properties_file` | null    | Specifies the path to an external file used to load additional bus configuration properties. The external file format is a plain Java Properties file. Properties specified in the external file will be merged into the configuration property set for the bus. This file is loaded at runtime from the local file system on the host where the configured container will run. |

### Provider-Specific Properties

In addition to the provider-agnostic properties listed above, each messaging binding supports additional configuration properties specific to its underlying messaging technology.

For complete configuration reference and architectural information about each binding, see:

* [**Solace Binding**](/rumi-core/guides/developing-applications/configuring-messaging/configuring-bus-connections/solace-binding.md) - Configuration reference | [Concepts](/rumi-core/concepts/messaging-model/solace-binding.md)
* [**JMS Binding**](/rumi-core/guides/developing-applications/configuring-messaging/configuring-bus-connections/jms-binding.md) - Configuration reference | [Concepts](/rumi-core/concepts/messaging-model/jms-binding.md)
* [**Loopback Binding**](/rumi-core/guides/developing-applications/configuring-messaging/configuring-bus-connections/loopback-binding.md) - Configuration reference | [Concepts](/rumi-core/concepts/messaging-model/loopback-binding.md)
* [**Executor Binding**](/rumi-core/guides/developing-applications/configuring-messaging/configuring-bus-connections/executor-binding.md) - Configuration reference | [Concepts](/rumi-core/concepts/messaging-model/executor-binding.md)

## Providing Per-Microservice Connection Values

Since connection descriptors are conceptually per-microservice configuration, each microservice typically needs to provide its own connection values (such as credentials, client IDs, or other provider-specific parameters). This is accomplished using **substitution parameters** in the global bus descriptor, with values provided in the `<container>` section where the microservice runs.

**Example using substitution parameters**:

```xml
<model>
  <!-- Global bus structure with parameterized connection descriptor -->
  <buses>
    <bus name="orders-bus">
      <provider>solace</provider>
      <address>${solace.host}</address>
      <port>${solace.port}</port>
      <properties>
        <vpn>${solace.vpn}</vpn>
        <username>${solace.username}</username>
        <password>${solace.password}</password>
      </properties>
      <channels>
        <channel name="new-orders">
          <qos>Guaranteed</qos>
          <key>ORDERS/${Region}</key>
        </channel>
      </channels>
    </bus>
  </buses>

  <!-- Application definitions (business logic) -->
  <services>
    <service name="OrderProcessor" mainClass="com.example.OrderProcessor">
      <messaging>
        <bus name="orders-bus">
          <channels>
            <channel name="new-orders" join="true"/>
          </channels>
        </bus>
      </messaging>
    </service>

    <service name="InventoryService" mainClass="com.example.InventoryService">
      <messaging>
        <bus name="orders-bus">
          <channels>
            <channel name="new-orders" join="true"/>
          </channels>
        </bus>
      </messaging>
    </service>
  </service>

  <!-- containers (containers) provide microservice-specific connection values -->
  <containers>
    <container name="order-processor-1">
      <env>
        <solace.host>solace-prod.example.com</solace.host>
        <solace.port>55555</solace.port>
        <solace.vpn>prod-vpn</solace.vpn>
        <solace.username>order-processor-user</solace.username>
        <solace.password>${ORDER_PROCESSOR_PASSWORD}</solace.password>
      </env>
      <services>
        <service name="OrderProcessor" autoStart="true"/>
      </service>
    </container>

    <container name="inventory-service-1">
      <env>
        <solace.host>solace-prod.example.com</solace.host>
        <solace.port>55555</solace.port>
        <solace.vpn>prod-vpn</solace.vpn>
        <solace.username>inventory-service-user</solace.username>
        <solace.password>${INVENTORY_SERVICE_PASSWORD}</solace.password>
      </env>
      <services>
        <service name="InventoryService" autoStart="true"/>
      </service>
    </container>
  </containers>
</model>
```

In this example:

* The global `<buses>` section defines the bus descriptor with substitution parameters like `${solace.username}` and `${solace.password}`
* The `<services>` section defines the microservice business logic and which channels they join
* Each `<container>` (Rumi container) provides its own connection values via `<env>` elements
* When a container starts, it resolves the substitution parameters using its `<env>` values, allowing each microservice instance to connect with different credentials
* This allows the abstract bus structure (channels, QoS, keys) to be shared while connection credentials remain microservice-specific