> 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-the-runtime/discovery/discovery-configuration.md).

# Discovery Configuration

Configure discovery providers, cache properties, and separate discovery domains for container and cluster discovery.

## Overview

Discovery caches are configured using descriptor strings that specify the provider, address, and additional properties. All discovery cache implementations support common properties for controlling entity lifecycle and advertisement behavior.

## Discovery Descriptor Format

A discovery cache descriptor follows this format:

```
<provider>://<address>[&prop1=value]...[&propN=valueN]
```

For example:

```
mcast://224.0.1.200:4090&initWaitTime=10&maxEntityAge=30
```

## Common Discovery Properties

The following properties are supported by all discovery cache implementations:

| Property       | Default | Description                                                                                                                                                                                                                                                                                                                                         |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initWaitTime` | 5       | <p>Time (in seconds) to wait after sending solicit packets for entities to join.<br><br>Upon construction, cache members solicit entity advertisements from remote members to populate the local cache. The initial wait time is the time that the cache constructor will sleep waiting for remote entities to be populated in the local cache.</p> |
| `maxEntityAge` | 30      | <p>Time (in seconds) that can elapse without receiving an ESA before an entity is deemed dead.<br><br>The maximum age associated with each entity created by the local cache member. This parameter works hand in hand with the <code>maxEsaLoss</code> parameter to determine how often to transmit ESAs.</p>                                      |
| `maxEsaLoss`   | 6       | <p>Number of ESAs, if lost, that would cause an entity to be expired (i.e., number of ESAs to advertise within the maxEntityAge interval).<br><br>An entity owner determines how often to broadcast ESAs using the maxEntityAge and maxESALoss parameters: ESAs are broadcast every <code>maxEntityAge / maxESALoss</code> seconds.</p>             |
| `memberName`   | UUID    | <p>Each discovery cache member is uniquely identified by a name. The member name is used to identify entity ownership.<br><br>By default, each member is uniquely identified by a UUID. However, you can override the use of UUIDs for identification through the use of the memberName property.</p>                                               |

## The Default Discovery Cache

Rumi broadcasts Applications, containers, and ODS Stores via discovery. Unless configured otherwise, these will be done using the default (global) discovery cache singleton in the JVM.

The default discovery descriptor uses IP multicast and defaults to `mcast://224.0.1.200:4090`.

This can be changed by configuring the environment property `nv.discovery.descriptor`:

**DDL Configuration:**

```xml
<env>
  <nv>
    <discovery>
      <descriptor>mcast://224.0.1.200:4096</descriptor>
    </discovery>
  </nv>
</env>
```

**System Property:**

```bash
-Dnv.discovery.descriptor=mcast://224.0.1.200:4096
```

{% hint style="info" %}
**Tip**: If you are on the same network as several of your peers and you are all working on the same application, it would be a good idea to choose your own port for discovery to avoid clashing.
{% endhint %}

## Configuring Separate container and Cluster Discovery

Using the default discovery provider for both container and cluster discovery is sufficient for most applications. However, there may be cases where it is advantageous to use separate providers.

**Example:** Using SMA for cluster discovery while using multicast for container discovery:

```xml
<env>
  <nv>
    <discovery>
      <descriptor>mcast://224.0.1.200:4096</descriptor>
    </discovery>
  </nv>
</env>

<services>
  <service name="MyApp">
    <storage>
      <clustering>
        <!-- Using discovery element -->
        <discovery>
          <provider>solace</provider>
          <address>192.168.1.100</address>
          <port>55555</port>
          <properties>
            <discoveryChannel>cluster-discovery</discoveryChannel>
          </properties>
        </discovery>

        <!-- OR using discoveryDescriptor -->
        <discoveryDescriptor>solace://192.168.1.101:55555&amp;discoveryChannel=cluster-discovery</discoveryDescriptor>
      </clustering>
    </storage>
  </service>
</service>

<containers>
  <container name="MyXVM">
    <!-- Using discovery element -->
    <discovery>
      <provider>solace</provider>
      <address>192.168.1.101</address>
      <port>55555</port>
      <properties>
        <discoveryChannel>container-discovery</discoveryChannel>
      </properties>
    </discovery>

    <!-- OR using discoveryDescriptor -->
    <discoveryDescriptor>solace://192.168.1.101:55555&amp;discoveryChannel=container-discovery</discoveryDescriptor>
  </container>
</containers>
```

## Provider-Specific Configuration

### Multicast Discovery

The multicast provider is the default discovery mechanism.

**Descriptor Format:**

```
mcast://<multicast-address>:<port>[&properties]
```

**Multicast-Specific Properties:**

| Property      | Default | Description                                                                                                                                                             |
| ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `localIfAddr` | N/A     | <p>When running on a host with multiple network interfaces that support multicast, this property specifies the interface that should be used for discovery.<br><br></p> |

{% hint style="info" %}
\
\*\*Tip\*\*: A common issue with multicast discovery occurs when 2 hosts bind to adapters that are on different discovery networks.<br>
{% endhint %}

|

**Example:**

```xml
<env>
  <nv>
    <discovery>
      <descriptor>mcast://224.0.1.200:4090&amp;localIfAddr=192.168.1.10</descriptor>
    </discovery>
  </nv>
</env>
```

{% hint style="warning" %}
**Use IPv4**: Multicast should be run over an IPv4 stack. When running on an OS or JVM that prefers IPv6, you should explicitly specify the usage of IPv4 by setting `-Djava.net.preferIPv4Stack=true`
{% endhint %}

{% hint style="warning" %}
**Mac OS X Yosemite or Later**: The Yosemite OS X version and beyond create a virtual interface (awdl0) for Airplay that states it has multicast enabled, but multicast does not work if that interface is discovered by the multicast provider. There is a tool called [WiFried](https://medium.com/@mariociabarra/wifriedx-in-depth-look-at-yosemite-wifi-and-awdl-airdrop-41a93eb22e48) that allows one to selectively disable this interface temporarily.
{% endhint %}

### SMA Discovery

The SMA discovery provider uses topic broadcasts for advertising packets. Any broker-based SMA messaging provider can be used for discovery.

**Descriptor Format:**

```
<provider>://<address>:<port>[&properties]
```

**SMA-Specific Properties:**

| Property           | Default | Description                                                                                                                                                                   |
| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `discoveryChannel` | *XEDP*  | The channel name to create and use for discovery. Because message bus topics start with the channel name by default, this value is used as the topic name on the message bus. |

Any bus binding-specific properties can be passed in with the discovery descriptor. The bus binding used for discovery will use the `memberName` as the value passed to the bus binding provider's create method.

{% hint style="warning" %}
**Resilience Consideration**: When considering using SMA-based discovery, you might want to consider using a different messaging container than the one used for application traffic, particularly if you will be using monitoring tools that rely on container discovery to discover the hosts that they manage. A failure in the messaging fabric would otherwise leave applications undiscoverable.
{% endhint %}

**Example SMA Discovery Descriptors:**

**Solace:**

When using the Solace provider, consider using the `single_session=true` property to reduce the number of threads created by the Solace binding. The Solace bindings created by the SMA discovery provider are marked as administrative and as such platform autotuning will not result in busy-spinning threads.

```xml
<env>
  <nv>
    <discovery>
      <descriptor>solace://solacehost:55555&amp;single_session=true</descriptor>
    </discovery>
  </nv>
</env>
```

**Loopback:**

The loopback provider uses the loopback bus and can be used for discovery within the same process. It can be useful in testing scenarios to simulate a message-based discovery provider, but it is often more efficient to use the local discovery provider described below.

```xml
<env>
  <nv>
    <discovery>
      <descriptor>loopback://container-discovery</descriptor>
    </discovery>
  </nv>
</env>
```

**JMS:**

Configuring a generic JMS discovery provider uses JNDI:

```xml
<container>
  <discovery>
    <provider>jms</provider>
    <address>tibcohost</address>
    <port>27326</port>
    <properties>
      <username>admin</username>
      <password>changeme</password>
      <jndi>true</jndi>
      <jndi_contextfactory>com.tibco.tibjms.naming.TibjmsInitialContextFactory</jndi_contextfactory>
      <jndi_principal>admin</jndi_principal>
      <jndi_credentials>changeme</jndi_credentials>
      <jndi_connectionfactory>CSTopicConnectionFactory</jndi_connectionfactory>
      <maxEntityAge>150</maxEntityAge>
      <maxEsaLoss>30</maxEsaLoss>
      <discoveryChannel>=_XEDP_/dev</discoveryChannel>
    </properties>
  </discovery>
</container>
```

**ActiveMQ:**

```xml
<env>
  <nv>
    <discovery>
      <descriptor>activemq://brokerhost:61616</descriptor>
    </discovery>
  </nv>
</env>
```

**Kafka:**

```xml
<env>
  <nv>
    <discovery>
      <descriptor>kafka://kafka-broker:9092&amp;discoveryChannel=talon-discovery</descriptor>
    </discovery>
  </nv>
</env>
```

### Local Discovery

The local discovery provider is a simple provider that can be used to find other entities in the same process. It is similar to the SMA loopback provider but has lower overhead.

**Descriptor Format:**

```
local://.
```

**Use Cases:**

* Unit tests launching all applications in the same JVM
* Development with collocated applications
* Testing scenarios requiring isolated discovery

**Example:**

```xml
<env>
  <nv>
    <discovery>
      <descriptor>local://.</descriptor>
    </discovery>
  </nv>
</env>
```

## Related Topics

* [Discovery Model](/rumi-core/concepts/discovery-model.md) - Understanding discovery concepts
* [Admin Over SMA](/rumi-core/guides/developing-applications/configuring-the-runtime/administration/admin-over-sma.md) - Administrative discovery configuration
* [rumi discovery](/rumi-cli/commands/tools/discovery.md) - Troubleshooting discovery

## Next Steps

1. Choose appropriate discovery provider for your environment
2. Configure default discovery cache for container discovery
3. Optionally configure separate cluster discovery for applications
4. Test discovery configuration using the rumi discovery
5. Monitor entity advertisements and age-out behavior