5. Configuration

5.1. Configuring Cloud Discovery Service

This document describes how to configure Cloud Discovery Service. For installation instructions or to walk through some simple examples, please see the appropriate section.

When you start Cloud Discovery Service, you can specify a configuration file in XML format. In that file, you can set properties that control the behavior of the service. This chapter describes how to write a configuration file.

5.2. Terms to Know

Before learning how to configure Cloud Discovery Service, you should become familiar with a few key terms and concepts:

  • A Cloud Discovery Service Configuration—represented by the <cloud_discovery_service> XML tag—refers to an execution of Cloud Discovery Service.

5.3. How to Load the XML Configuration

Cloud Discovery Service loads its XML configuration from multiple locations. This section presents the various sources of configuration files, listed in load order.

  • [working directory]/USER_CLOUD_DISCOVERY_SERVICE.xml This file is loaded automatically if it exists.
  • [NDDSHOME]/resource/xml/RTI_CLOUD_DISCOVERY_SERVICE.xml This file is loaded automatically if it exists.
  • File specified using the command-line option -cfgFile.

Note

The tag [working directory] indicates the path to the current working directory from which you run Cloud Discovery Service.

The tag [NDDSHOME] indicates the path to your Connext DDS installation.

You may use a combination of the above sources and load multiple configuration files.

Here is an example configuration file. You will learn the meaning of each line as you read the rest of this section.

<?xml version="1.0" encoding="UTF-8"?>
<dds>
  <cloud_discovery_service name="MyCds">
      <transport>
          <element>
              <alias>udpv4</alias>
              <receive_port>7400</receive_port>
          </element>
      </transport>
      <domain_list>
          <allow_domain_id>0</allow_domain_id>
      </domain_list>
      <forwarder>
          <flow_controller>
              <output_capacity unit="KILOBYTES_PER_SECOND">
                  100
              </output_capacity>
          </flow_controller>
      </forwarder>
      <database>
          <cleanup_period>
              <sec>30</sec>
          </cleanup_period>
      </database>
  </cloud_discovery_service>
</dds>

5.4. XML Syntax and Validation

The XML representation of DDS-related resources must follow these syntax rules:

  • It shall be a well-formed XML document according to the criteria defined in clause 2.1 of [XML].
  • It shall use UTF-8 character encoding for XML elements and values.
  • It shall use <dds> as the root tag of every document.

To validate the loaded configuration, Cloud Discovery Service relies on an XSD file that describes the format of the XML content. We recommend including a reference to this document in the XML file that contains the service’s configuration; this provides helpful features in code editors such as Visual Studio®, Eclipse®, and NetBeans®, including validation and auto-completion while you are editing the XML file.

The XSD definitions of the XML elements are in [NDDSHOME]/resources/schema/rti_cloud_discovery_service.xsd

To include a reference to the XSD document in your XML file, use the attribute xsi:noNamespaceSchemaLocation in the <dds> tag. For example:

<?xml version="1.0" encoding="UTF-8"?>
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="[NDDSHOME]/resource/schema/rti_cloud_discovery_service.xsd">
    <!-- ... -->
</dds>

Note

The tag [NDDSHOME] indicates the path to your Connext DDS installation.

5.5. XML Tags for Configuring RTI Cloud Discovery Service

This section describes the XML tags you can use in a Cloud Discovery Service configuration file. The following diagram and Table 5.1 describe the top-level tags allowed within the root <dds> tag.

Top-level Tags in the Configuration File

Figure 5.1 Top-level Tags in the Configuration File

Table 5.1 Top-level Tags in the Configuration File
Tags within <dds> Description Multiplicity
<cloud_discovery_service>

Specifies a Cloud Discovery Service configuration.

Attributes
  • name: uniquely identifies a service configuration. Required.
Example
<cloud_discovery_service name="ExampleService">
    <!-- your service settings ... -->
</cloud_discovery_service>
1..*.

5.5.1. Cloud Discovery Service

A configuration file must have at least one <cloud_discovery_service> tag. This tag is used to configure an execution of Cloud Discovery Service. A configuration file may contain multiple <cloud_discovery_service> tags.

When you start Cloud Discovery Service, you can specify which <cloud_discovery_service> tag to use to configure the service using the -cfgName command-line option.

Because a configuration file may contain multiple <cloud_discovery_service> tags, one file can be used to configure multiple Cloud Discovery Service executions.

Figure 5.2 and Table 5.2 describe the tags allowed within a <cloud_discovery_service> tag.

Cloud Discovery Service Tag

Figure 5.2 Cloud Discovery Service Tag Structure

Table 5.2 Cloud Discovery Service Tag
Tags within <cloud_discovery_service> Description Multiplicity
<domain_list> Set of domains for which the service forwards participant announcements.
Section 5.5.2.		 0..1
<transport> Selection of unicast transport resources where the service receives and sends participant announcements.
Section 5.5.3		 0..1
<forwarder> Configures the behavior of the participant announcement forwarding logic.
Section 5.5.4		 0..1
<database> Configures the behavior of the service’s internal database, which contains information about the discovery state.
Section 5.5.5		 0..1
<resource_limits> Service resource management policies.
Section 5.5.6		 0..1

5.5.1.1. Example: Specify a Configuration in XML

<dds>
    <cloud_discovery_service name="EmptyConfiguration"/>
    <cloud_discovery_service name="ShapesDemoConfiguration">
    <!--...-->
    </cloud_discovery_service>
</dds>

Starting Cloud Discovery Service with the following command will use the <cloud_discovery_service> tag with the name EmptyConfiguration.

$NDDSHOME/bin/rticlouddiscoveryservice \
        -cfgFile file.xml -cfgName EmptyConfiguration

5.5.2. Domain List

A <domain_list> allows you to control for which domains the discovery traffic is propagated. Table 5.3 describes the tags allowed.

Figure 5.3 and Table 5.3 describe the tags allowed within a <domain_list> tag.

Domain List Tag

Figure 5.3 Domain List Tag Structure

Table 5.3 Domain List Tag
Tags within <domain_list> Description Multiplicity
<allow_domain_id> Set of domain IDs where the service forwards participant announcements.
Default: DOMAIN_LIST_ALL		 0..1
<deny_domain_id> Subset of the allowed domain IDs for which the service ignores announcements.
Default: [empty string]		 0..1

The <allow_domain_id> and <deny_domain_id> filters both allow the same syntax, in which a subset of domains can be specified as a comma-separated list containing one or more of the following elements:

  • Individual domains: 5, 6, 7
  • Domain Range: [1 - 10]
  • Special values:
    • DOMAIN_LIST_ALL: specifies all the available domains.
    • (empty string): specifies none of the domains.

5.5.2.1. Example: Deny a Few Specific Domains

<domain_list>
   <allow_domain_id>DOMAIN_LIST_ALL</allow_domain_id>
   <deny_domain_id>5,7,10</deny_domain_id>
</domain_list>

5.5.2.2. Example: Allow a Subset of Domains

<domain_list>
   <allow_domain_id>[10 - 30], 40, [50 - 100]</allow_domain_id>
</domain_list>

5.5.3. Transport

The <transport> element allows you to select and configure the resources used to receive and send discovery traffic. A receive resource is uniquely specified by a transport class-receive port pair. For each different transport instance specified, Cloud Discovery Service creates a send resource.

Figure 5.4 and Table 5.4 shows the description of this element.

Transport Tag

Figure 5.4 Transport Tag Structure

Table 5.4 Transport Tag
Tags within <transport> Description Multiplicity
<element> Individual transport receive resource.
See Table 5.5.		 0..*

Each <element> within <transport> is a transport unicast receive resource, specified by a transport alias and a receive port. Table 5.5 describes the tags allowed.

Table 5.5 Transport Element Tag
Tags within <element> of a <transport> Description Multiplicity
<alias>

Identifies a concrete transport class instantiation.
Default: udpv4

If the transport supports it, you can reuse the same transport instance by specifying the same alias.

Note

If you attempt to reuse a transport instance of a class that does not support reuse, Cloud Discovery Serivce will log a warning and continue loading.

 0..1
<receive_port>

Port that the service listens on to receive participant announcements.
Default: 7400

Attributes:

  • kind: Specifies the port representation. Optional.

    • PORT: An integer that represents a port number within the valid range allowed by the transport.

    • DOMAIN_ID_DERIVED: A domain ID that represents the discovery receive port computed from the well-known RTPS port mapping:

      • participant Id: 0
      • well-known ports: DDS_INTEROPERABLE_RTPS_WELL_KNOWN_PORTS
 0..1
<property>

A sequence of name-value string pairs that allows configuring the underlying transport instance.

Example:
<property>
    <value>
        <element>
            <name>dds.transport.UDPv4.builtin.allow_interfaces_list</name>
            <value>eth0</value>
        </element>
    </value>
</property>

Note

When reusing a transport instance, if you specify the same property twice, Cloud Discovery Service will log a warning.

 0..1

Cloud Discovery Service comes with the following preconfigured transport instances, which you can use and configure directly.

Note

You can override any of the preset transport properties. In such a case, Cloud Discovery Service will log a warning.

Table 5.6 Available Transports
Alias Description Prefix
udpv4 or builtin.udpv4

Builtin implementation of UDP v4.

  • Class ID: NDDS_TRANSPORT_CLASSID_UDPV4
  • Reuse: Yes
 dds.transport.UDPv4.builtin
udpv6 or builtin.udpv6

Builtin implementation of UDP v6.

  • Class ID: NDDS_TRANSPORT_CLASSID_UDPV6
  • Reuse: Yes
 dds.transport.UDPv6.builtin
tcpv4_lan, tcpv4_wan, tlsv4_lan or tlsv4_wan

Implementation of TCP v4 for LAN and WAN networks.

Note

Your library path requires libraries from RTI TCP Support (nddstransporttcp) and additionally, if enabling TLS, RTI TLS Support (nddstls) and OpenSSL.

  • Reuse: No
 dds.transport.cds.tcp1

5.5.3.1. Preregistered UDP Transport

Cloud Discovery Service registers an instance for both of the Connext DDS UDPv4 and UDPv6 builtin transports. There are no preset properties for any of these instances.

See Connext DDS UDPv4 configuration and Connext DDS UDPv6 configuration for a list of available properties.

5.5.3.2. Preregistered TCP Transport

Cloud Discovery Service registers an instance of the RTI TCP transport. Table 5.7 shows a list of preset properties.

See RTI TCP Transport configuration for a list of available properties.

Table 5.7 TCP Transport preset properties
Property name (prefix with dds.transport.cds.tcp1) Property value
library nddstransporttcp
create_function NDDS_Transport_TCPv4_create
server_bind_port The value of the corresponding <receive_port>
parent.classid
  • NDDS_TRANSPORT_CLASSID_TCPV4_LAN
    • For alias tcpv4_lan
  • NDDS_TRANSPORT_CLASSID_TCPV4_WAN
    • For alias tcpv4_wan
  • NDDS_TRANSPORT_CLASSID_TLSV4_LAN
    • For alias tlsv4_lan
  • NDDS_TRANSPORT_CLASSID_TLSV4_WAN
    • For alias tlsv4_wan

5.5.3.3. Example: Reusing UDP Transport Instance for Multiple Receive Resources

<transport>
    <element>
        <alias>udpv4</alias>
        <receive_port>7400</receive_port>
    </element>
    <element>
        <alias>udpv4</alias>
        <receive_port>7500</receive_port>
    </element>
</transport>

5.5.3.4. Example: A Receive Resource for Each UDP and TCP Transport

This example shows how to specify different receive resources from different transport instances. Additionally, it shows how to extend the behavior of the preregistered TCP transport through the specification of additional transport properties using the transport prefix dds.transport.cds.tcp1.

<transport>
    <element>
        <alias>builtin.UDPv4</alias>
        <receive_port>7400</receive_port>
    </element>
    <element>
        <alias>tcpv4_wan</alias>
        <receive_port>8400</receive_port>
        <property>
            <value>
                <element>
                    <name>dds.transport.cds.tcp1.tcp1.public_address</name>
                    <value>35.6.9.10</value>
                </element>
            </value>
        </property>
    </element>
</transport>

5.5.4. Forwarder

The <forwarder> element allows you to configure the attributes and behavior of the active component involved in the participant announcement forwarding process.

Figure 5.5 and Table 5.8 describe this element.

Forwarder Tag

Figure 5.5 Forwarder Tag Structure

Table 5.8 Forwarder Tag
Tags within <forwarder> Description Multiplicity
<thread_pool>

Configures the pool of threads dedicated to the forwarding process.
This element allows you to specify the number of threads as well as the properties of those threads.

Example
<thread_pool>
    <size>3</size>
    <mask>MASK_DEFAULT</mask>
    <priority>THREAD_PRIORITY_DEFAULT</priority>
    <stack_size>THREAD_STACK_SIZE_DEFAULT</stack_size>
</thread_pool>
Default values:
  • size: 1
  • mask: MASK_DEFAULT
  • priority: THREAD_PRIORITY_DEFAULT
  • stack_size: THREAD_STACK_SIZE_DEFAULT
 0..1
<flow_controller> Configures the announcement scheduling policy and the output traffic control. See Figure 5.6 and Table 5.9. 0..1

The <flow_controller> element allows you to configure the output traffic of Cloud Discovery Service. With the flow controller, you can limit the output capacity, assign more of the output capacity to certain participant announcements, and also throttle the output traffic.

Figure 5.6 and Table 5.9 describe this element.

Flow Controller Tag

Figure 5.6 Flow Controller Tag Structure

Table 5.9 Flow Controller Tag
Tags within <flow_controller> Description Multiplicity
<output_capacity> Specifies a limit for the output capacity in jobs per second.
Default: LENGTH_UNLIMITED
0..1
<max_burst_jobs> Maximum amount of announcement jobs that can be dispatched at once.
Default: <output_capacity> * 1 second
0..1
<output_capacity_allocation>

Configures the output capacity distribution depending on the participant announcement class. See Table 5.10.

Example
<output_capacity_allocation>
    <new>50</new>
    <update>30</update>
    <refresh>20</refresh>
</output_capacity_allocation>
0..1
<flush_period>

Configures the maximum period at which the forwarder will attempt to send pending announcements.
Default: DURATION_INFINITE.

Example
<flush_period>
    <sec>1</sec>
    <nanosec>0</nanosec>
</flush_period>
0..1

Note

Configuring only one flow controller parameter in isolation may result in inaccurate performance of the forwarder. It is recommended to configure all the flow controller parameters, to guarantee the expected behavior.

The <output_capacity_allocation> allows you to distribute the output capacity to each participant announcement class. Each class element is an integer that represents the percentage of the total output capacity used to forward announcements of such class.

Table 5.10 describes this element.

Table 5.10 Output Capacity Allocation Tag
Tags within <output_capacity_allocation> Description Multiplicity
<new> Percentage of the maximum output capacity dedicated to the new participant announcement class.
Default: 40		 0..1
<update> Percentage of the maximum output capacity dedicated to the update participant announcement class.
Default: 30		 0..1
<refresh> Percentage of the maximum output capacity dedicated to the refresh participant announcement class.
Default: 30		 0..1

Note that the sum of the percentages from the three classes can never be greater than 100. Otherwise Cloud Discovery Service will log an error message and fail to start. Unless default values are used, if the allocation for one or more classes are not specified, Cloud Discovery Service will equally split the remaining of the output capacity among them.

5.5.4.1. Example: Flow Controller

This example shows how to set up a flow controller with a maximum output capacity of 5000 jobs/s, of which half is reserved only for new participant announcements, and the other half is equally distributed among the update and refresh classes (25/25).

<flow_controller>
    <output_capacity>5000</output_capacity>
    <output_capacity_allocation>
        <new>50</new>
    </output_capacity_allocation>
</flow_controller>

5.5.5. Database

The <database> element allows you to configure the behavior of the internal database that contains the information that represents the discovery state of the system.

Figure 5.7 and Table 5.11 describe this element.

Database Tag

Figure 5.7 Database Tag Structure

Table 5.11 Database Tag
Relevant tags within <database> Description Multiplicity
<thread> Database thread settings.
See thread in DatabaseQosPolicy.		 0..1
<cleanup_period>

The period at which the service database thread wakes up to clean up expired information.
See cleanup_period in DatabaseQosPolicy.

Example
<cleanup_period>
    <sec>1</sec>
    <nanosec>0</nanosec>
</cleanup_period>
0..1
<initial_records> The initial number of total records.
See initial_records in DatabaseQosPolicy.		 0..1

5.5.6. Resource Limits

The <resource_limits> element allows you to specify upper limits of memory consumption. In general, Cloud Discovery Service incorporates mechanisms to clean up unused memory and maintain the execution within bounds when possible. Nevertheless, you may need to tune the memory usage if you have special memory requirements.

Figure 5.8 and Table 5.12 describe this element.

Resource Limits Tag

Figure 5.8 Resource Limits Tag Structure

Table 5.12 Resource Limits Tag
Tags within <resource_limits> Description Multiplicity
<remote_participant_allocation> Allocation settings applied to remote DomainParticipants.
See remote_participant_allocation in DomainParticipantResourceLimitsQosPolicy.		 0..1
<remote_participant_hash_buckets> Number of hash buckets for remote DomainParticipants.
See remote_participant_hash_buckets in DomainParticipantResourceLimitsQosPolicy.		 0..1
<participant_property_list_max_length> Maximum number of properties associated with the DomainParticipant.
See participant_property_list_max_length in DomainParticipantResourceLimitsQosPolicy.		 0..1
<participant_property_string_max_length> Maximum string length of the properties associated with the DomainParticipant.
See participant_property_string_max_length in DomainParticipantResourceLimitsQosPolicy.		 0..1
<participant_user_data_max_length> Maximum length of user data to send and receive in a participant announcement.
See participant_user_data_max_length in DomainParticipantResourceLimitsQosPolicy.		 0..1
<transport_info_list_max_length> Maximum number of installed transports to send and receive information about a participant announcement.
See transport_info_list_max_length in DomainParticipantResourceLimitsQosPolicy.		 0..1

5.6. Builtin Configuration

Cloud Discovery Service comes pre-loaded with a builtin configuration, which is selected on startup if no configuration name is specified. This builtin configuration is equivalent to the following:

<cloud_discovery_service name="rti.cds.builtin.config.default">
    <transport>
        <element>
            <alias>builtin.UDPv4</alias>
            <receive_port>7400</receive_port>
        </element>
    </transport>
    <domain_list>
        <allow_domain_id>DOMAIN_LIST_ALL</allow_domain_id>
    </domain_list>
    <forwarder>
        <thread_pool>
            <size>2</size>
        </thread_pool>
    </forwarder>
    <database>
        <cleanup_period>
            <sec>50</sec>
        </cleanup_period>
    </database>
</cloud_discovery_service>

The builtin configuration has the name rti.cds.builtin.config.default, which is reserved; no additional configurations can have this name.

5.7. Overriding XML Settings

Cloud Discovery Service allows you to override certain XML settings through the use of the command-line options. When these options are explicitly specified, their values will override the values of the equivalent XML elements.

See Section 4.3 for a list of the available options that can override XML settings.