How do I configure RTI Data Distribution Service not to use multicast?

Note: This solution applies to RTI Data Distribution Service 4.x.

If you disable multicast traffic, you will not be able to send or receive multicast data.

To disable multicast:

  1. Disable multicast in the UDPv4 transport.
  2. Configure the initial peers list not to use multicast.
  3. Remove any multicast receive addresses

These steps are explained below as we describe three methods for disabling multicast:

  • The first method creates the DomainParticipant disabled, which is a little more cumbersome than the other two methods, but it applies to all 4.x versions.
  • The second method uses the Property QoS policy and applies to version 4.2e and higher.

Method One for Disabling Multicast (applies to all 4.x versions)

  1. Before creating the DomainParticipant
    1. Make sure the DomainParticipant will be created in a disabled state. For example, in C++:
      retcode = DDSTheParticipantFactory->get_qos(factory_qos);
      factory_qos.entity_factory.autoenable_created_entities = DDS_BOOLEAN_FALSE;
      retcode = DDSTheParticipantFactory->set_qos(factory_qos);
    2. Obtain the participant_qos and configure the initial peers not to announce on a multicast address. To do this, either:
      • Set the NDDS_DISCOVERY_PEERS file/environment variable to the unicast IP address of the remote participants. (On the publisher's side, set it to the subscriber's IP address and vice versa)
      • or set the peers list to the unicast IP address of the remote participants through the DiscoveryQosPolicy’s initial_peers field.
    3. Configure the DomainParticipant not to listen for discovery information on any multicast addresses. To do this, either:
      • Set the NDDS_DISCOVERY_PEERS file/environment variable not to include a multicast address. Otherwise, the multicast receive_addresses are set to the first multicast address found in the NDDS_DISCOVERY_PEERS environmental variable
      • or set the multicast_receive_addressesto empty. In order to do this, set the sequence length to 0. For example, in C++:
        participant_qos.discovery.multicast_receive_addresses.length(0);
  2. Create the DomainParticipant
  3. Disable multicast on the UDP transport. For example, in C++:
    struct NDDS_Transport_UDPv4_Property_t UDPv4Properties = 
        NDDS_TRANSPORT_UDPV4_PROPERTY_DEFAULT;
    
    if (NDDSTransportSupport::get_builtin_transport_property(
        participant, DDS_TRANSPORTBUILTIN_UDPv4,
        (struct NDDS_Transport_Property_t&)UDPv4Properties)
        != DDS_RETCODE_OK) {
        printf("***Error: get builtin transport property\n");
    }
    
    UDPv4Properties.multicast_enabled = 0;
    
    if (NDDSTransportSupport::set_builtin_transport_property(
        participant, DDS_TRANSPORTBUILTIN_UDPv4,
        struct NDDS_Transport_Property_t&)UDPv4Properties)
        != DDS_RETCODE_OK) {
        printf("***Error: set builtin transport property\n");
    }
  4. Enable the DomainParticipant:
    retcode = participant->enable();
    

Method Two for Disabling Multicast (applies to version 4.2 and higher)

This method involves using the Property QosPolicy to modify the UDP transport properties. (The Property QosPolicy is available in RTI Data Distribution Service 4.2x and higher.) This method is easier that Method One, because you do not need to create the DomainParticipant disabled first. You will need to configure the initial peers list so it does not include a multicast address and make sure the multicast receive address list is empty. This code snippet shows how to do it:

retcode = DDSTheParticipantFactory->get_default_participant_qos(
participant_qos);
if (retcode != DDS_RETCODE_OK) {
    puts("Error, impossible get default participant qos");
    return NULL;
}
/* Use Property QoS to disable multicast */
retcode = DDSPropertyQosPolicyHelper::add_property(
    participant_qos.property,
    "dds.transport.UDPv4.builtin.multicast_enabled",
    "0",
    DDS_BOOLEAN_FALSE);
 
if (retcode != DDS_RETCODE_OK) {
    printf("Error, impossible add property");
    return NULL;
}
 
/* Modify initial peers and multicast receive addresses */
DDS_DomainParticipantQos participant_qos;
DDSTheParticipantFactory->get_default_participant_qos(participant_qos);

/* free original memory */
participant_qos.discovery.initial_peers.maximum(0);

/* set new initial peer for sending discovery information */
participant_qos.discovery.initial_peers.maximum(3);
participant_qos.discovery.initial_peers.length(3);
participant_qos.discovery.initial_peers[0] = DDS_String_dup("129.168.0.1");
participant_qos.discovery.initial_peers[1] = DDS_String_dup("4@builtin.udpv4://127.0.0.1");
participant_qos.discovery.initial_peers[2] = DDS_String_dup("builtin.shmem://");
participant_qos.discovery.multicast_receive_addresses.length(0);
 
participant = DDSTheParticipantFactory->create_participant(
    domainId, participant_qos, 
    NULL /* listener */, DDS_STATUS_MASK_NONE);

if (participant == NULL) {
    printf("create_participant error\n");
    publisher_shutdown(participant);
    return -1;
}

Method Three for Disabling Multicast (applies to version 4.3 and higher)

This method uses an XML QoS profile to configure the DomainParticipant and transport properties.

<dds>
  <qos_library name="NoMulticastLibrary">
    <qos_profile name="DefaultProfile">
      <participant_qos>
        <discovery>
          <initial_peers>
            <element>builtin.udpv4://127.0.0.1</element>
          </initial_peers>
          <multicast_receive_addresses/> 
        </discovery>
        <property> 
          <value>
            <element>
              <name>dds.transport.UDPv4.builtin.multicast_enabled</name>
              <value>0</value>
            </element>
          </value>
        </property>
      </participant_qos>
    </qos_profile>
  </qos_library>
</dds>

If you are using RTI Data Distribution Service 4.3e, you must call DDSTheParticipantFactory->load_profiles() before creating the DomainParticipant with a profile.

When using RTI Data Distribution Service 4.4 and higher, the XML file can be automatically loaded. If NDDS_QOS_PROFILES.xml is in the $NDDSHOME/resource/xml directory, it will be automatically loaded. Similarly, if USER_QOS_PROFILES.xml is in the working directory, it will be automatically loaded. See the User’s Manual for more details on XML file loading.

When using version RTI Data Distribution Service 4.4 and higher, place the attached USER_QOS_PROFILES.xml file in the working directory. It specifies NoMulticastLibrary as the default QoS profile and will be loaded when your DDS application starts.

Attachments: