4. Configuration

4.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.

4.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.

4.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 parameter -cfgFile.

Note

The tag [working directory] indicates the path to the current working directory from which you run the 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>

4.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.

4.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 4.1 describe the top-level tags allowed within the root <dds> tag.

Figure 4.1 Top-level Tags in the Configuration File

Table 4.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..*.

4.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 parameter.

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

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

Figure 4.2 Cloud Discovery Service Tag Structure

Table 4.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 4.5.2.	0..1
<transport>	Selection of unicast transport resources where the service receives and sends participant announcements. Section 4.5.3	0..1
<forwarder>	Configures the behavior of the participant announcement forwarding logic. Section 4.5.4	0..1
<database>	Configures the behavior of the service internal database that contains information about the discovery state. Section 4.5.5	0..1
<resource_limits>	Service resource management policies. Section 4.5.6	0..1

4.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

4.5.2. Domain List

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

Table 4.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 with which a subset of domains can be specified as a comma-separated list containing one 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.

4.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>

4.5.2.2. Example: Allow a subset of domains

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

4.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 4.3 and Table 4.4 shows the description of this element.

Figure 4.3 Transport Tag Structure

Table 4.4 Transport Tag

Tags within <transport>	Description	Multiplicity
<element>	Individual transport receive resource. See Table 4.5.	0..*

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

Table 4.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 pre-configured 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 4.6 Available Transports

Alias	Description	Prefix
udpv4 or builtin.udpv4	Built-in implementation of UDP v4. Class ID: NDDS_TRANSPORT_CLASSID_UDPV4 Reuse: Yes	dds.transport.UDPv4.builtin
udpv6 or builtin.udpv6	Built-in 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. Class ID: See parent.classid in Table 4.7 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

4.5.3.1. Pre-registered UDP transport

Cloud Discovery Service registers an instance for both of the Connext DDS UDPv4 and UDPv6 built-in 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.

4.5.3.2. Pre-registered TCP transport

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

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

Table 4.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

4.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>

4.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 pre-registered 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>

4.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 4.4 and Table 4.8 shows the description of this element.

Figure 4.4 Forwarder Tag Structure

Table 4.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>	0..1
<flow_controller>	Configures the announcement scheduling policy and the output traffic control. See Figure 4.5 and Table 4.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 4.5 and Table 4.9 shows the description of this element.

Figure 4.5 Flow Controller Tag Structure

Table 4.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>	Allows configuring the output capacity distribution depending on the the participant announcement class. See Table 4.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 produce inaccurate performance of the forwarder. It is recommended to configure all the parameters of the flow controller 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 announcement of such class.

Table 4.10 shows the description of this element.

Table 4.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 defaults 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.

4.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 for update and refresh classes (25/25).

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

4.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.

Table 4.11 shows the description of this element.

Table 4.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

4.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.

Table 4.12 shows the description of this element.

Table 4.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

4.6. Built-in configuration

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

<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 built-in configuration has the name rti.cds.builtin.config.default, which is reserved; no additional configurations can have this name.

4.7. Overriding XML settings

Cloud Discovery Service allows overriding 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 5.3 for a list of the available options that can override XML settings.