6. Configuration

6.1. Configuring Cloud Discovery Service

This section provides a reference for the XML elements that conform a Routing Service configuration. For details on how to provide XML configurations to Routing Service. refer to Configuring RTI Services. This chapter describes how to write an XML configuration.

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

Top-level Tags in the Configuration File

Figure 6.1 Top-level Tags in the Configuration File

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

6.2.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 6.2 and Table 6.2 describe the tags allowed within a <cloud_discovery_service> tag.

Cloud Discovery Service Tag

Figure 6.2 Cloud Discovery Service Tag Structure

Table 6.2 Cloud Discovery Service Tag

Tags within <cloud_discovery_service>

Description

Multiplicity

<administration>

Enables remote administration.

When administration is enabled, monitoring is also enabled by default. If no domain ID is specified for monitoring, Cloud Discovery Service will use the same domain as administration by default. See Administration.

0..1

<monitoring>

Enables monitoring for Cloud Discovery Service, including the periodic publication of statistics. See Section 6.2.3.

0..1

<domain_list>

Set of domains for which the service forwards participant announcements.
See Domain List.

0..1

<transport>

Selection of unicast transport resources where the service receives and sends participant announcements.
See Transport.

0..1

<security>

Configures the security features provided by the RTI Security Plugins.
See Security.

0..1

<forwarder>

Configures the behavior of the participant announcement forwarding logic.
See Forwarder.

0..1

<database>

Configures the behavior of the service’s internal database, which contains information about the discovery state.
See Database.

0..1

<resource_limits>

Service resource management policies.
See Resource Limits.

0..1

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

6.2.2. Administration

The <administration> tag allows you to enable and configure remote administration of Cloud Discovery Service, including stopping, starting, and deleting a Cloud Discovery Service instance.

See Remote Administration for details on using remote administration.

Table 6.3 Administration Tags in Cloud Discovery Service’s Configuration File

Tags within <administration>

Description

Multiplicity

<domain_id>

Domain ID used for remote administration. Also used for monitoring by default.

0..1

<domain_participant_qos>

QoS used by the administration DomainParticipant. If the tag is not defined, Connext DDS defaults will be used.

0..1

<publisher_qos>

QoS used by the administration Publisher. If the tag is not defined, Connext DDS defaults will be used.

0..1

<subscriber_qos>

QoS used by the administration Subscriber. If the tag is not defined, Connext DDS defaults will be used.

0..1

<datawriter_qos>

QoS used by administration DataWriter(s). If the tag is not defined, Connext DDS defaults will be used, with the following changes:

  • history.kind = DDS_KEEP_ALL_HISTORY_QOS

  • resource_limits.max_samples = 32

0..1

<datareader_qos>

Quality of Service (QoS) used by administration DataReader(s). If the tag is not defined, the Connext DDS defaults will be used, with the following changes:

  • reliability.kind = DDS_RELIABLE_RELIABILITY_QOS (this value cannot be changed)

  • history.kind = DDS_KEEP_ALL_HISTORY_QOS

  • resource_limits.max_samples = 32

0..1

<distributed_logger>

When you enable Distributed Logger, Cloud Discovery Service will publish its log messages to Connext DDS. See Enabling Distributed Logger.

0..1

The contents of the tags for configuring QoS are specified in the same manner as for the Connext DDS XML QoS Profiles file. See Configuring QoS with XML, in the RTI Connext DDS Core Libraries User’s Manual.

6.2.3. Monitoring

The <monitoring> tag allows you to enable and configure remote monitoring of Cloud Discovery Service. See Monitoring.

Table 6.4 Monitoring Tags in Cloud Discovery Service’s Configuration File

Tags within <monitoring>

Description

Multiplicity

<enabled>

Whether to enable monitoring of the service.

Default: Disabled, unless administration is enabled.

0..1

<domain_id>

Domain ID used for monitoring.

Default: The domain ID specified for monitoring.

0..1

<datawriter_qos>

QoS used by monitoring DataWriter(s)

0..1

<publisher_qos>

QoS used by monitoring Publisher(s)

0..1

<domain_participant_qos>

QoS used by monitoring DomainParticipant

0..1

<statistics_sampling_period>

How frequently to sample the service’s statistics, using the tags <sec> and <nanosec>. For example, <sec>1</sec> samples the service’s statistics every second.

0..1

<status_publication_period>

How frequently to publish the service status, using the tags <sec> and <nanosec>. For example, <sec>1</sec> publishes the service’s status every second.

0..1

The contents of the tags for configuring QoS are specified in the same manner as for the Connext DDS XML QoS Profiles file. See Configuring QoS with XML, in the RTI Connext DDS Core Libraries User’s Manual.

6.2.4. Domain List

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

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

Domain List Tag

Figure 6.3 Domain List Tag Structure

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

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

6.2.4.2. Example: Allow a Subset of Domains

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

6.2.5. 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 6.4 and Table 6.6 shows the description of this element.

Transport Tag

Figure 6.4 Transport Tag Structure

Table 6.6 Transport Tag

Tags within <transport>

Description

Multiplicity

<element>

Individual transport receive resource.
See Table 6.7.

0..*

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

Table 6.7 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 Service 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 6.8 Available Transports

Alias

Description

Prefix

udpv4 or builtin.udpv4

Builtin implementation of UDPv4.

  • Class ID: NDDS_TRANSPORT_CLASSID_UDPv4

  • Reuse: Yes

dds.transport.UDPv4.builtin

udpv4_wan or builtin.udpv4_wan

Implementation of UDPv4 for WAN networks.

  • Class ID: NDDS_TRANSPORT_CLASSID_UDPv4_WAN

  • Reuse: No

Note

Your library path requires libraries from RTI Real-Time WAN Transport Support (nddsrwt).

dds.transport.UDPv4_WAN.builtin

udpv6 or builtin.udpv6

Builtin implementation of UDPv6.

  • Class ID: NDDS_TRANSPORT_CLASSID_UDPv6

  • Reuse: Yes

dds.transport.UDPv6.builtin

tcpv4_lan, tcpv4_wan, tlsv4_lan or tlsv4_wan

Implementation of TCPv4 for LAN and WAN networks.

  • Class ID: See parent.classid in Table 6.9

  • Reuse: No

Note

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

dds.transport.cds.tcp1

6.2.5.1. Preregistered UDP Transports

Cloud Discovery Service registers an instance for the following UDP transports:

  • UDPv4

  • UDPv4 WAN or the RTI Real-Time WAN Transport

  • UDPv6

There are no preset properties for any of these instances.

See the following links for properties for each of these UDP transports respectively:

6.2.5.2. Preregistered TCP Transport

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

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

Table 6.9 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

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

6.2.5.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>
            <element>
                <name>dds.transport.cds.tcp1.tcp1.public_address</name>
                <value>35.6.9.10</value>
            </element>
        </property>
    </element>
</transport>

6.2.6. Security

The <security> element allows you to enable and configure the security features provided by the Security Plugins. For further details, see Security.

Table 6.10 shows the description of this element.

Table 6.10 Security Tag

Tags within <security>

Description

Multiplicity

<property>

A sequence of name-value string pairs that allows configuring security. These are the valid properties you can configure within this tag:

  • com.rti.serv.secure.authentication.participant_discovery_protection_key

  • com.rti.serv.secure.cryptography.rtps_protection_key

For further details, see Security.

Example:
<property>
    <element>
        <name>com.rti.serv.secure.authentication.participant_discovery_protection_key</name>
        <value>str:key1</value>
    </element>
</property>

0..1

6.2.7. Forwarder

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

Figure 6.5 and Table 6.11 describe this element.

Forwarder Tag

Figure 6.5 Forwarder Tag Structure

Table 6.11 Forwarder Tag

Tags within <forwarder>

Description

Multiplicity

<event>

Configures the timing and behavior of forwarding repeating events.

Elements:

  • <refresh_period>: Sets a period at which a refresh announcement

    is automatically sent for each participant. The period resets upon sending of announcement due to a change.
    A zero seconds period value is allowed and indicates that a refresh announcement is forward upon its reception from the participant.
    Default: 60 s.

Example
<event>
    <refresh_period>
        <sec>120<sec>
        <nanosec>0<nanosec>
    </refresh_period>
</event>

0..1

<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 6.6 and Table 6.12.

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 6.6 and Table 6.12 describe this element.

Flow Controller Tag

Figure 6.6 Flow Controller Tag Structure

Table 6.12 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 6.13.

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 6.13 describes this element.

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

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

6.2.8. 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 6.7 and Table 6.14 describe this element.

Database Tag

Figure 6.7 Database Tag Structure

Table 6.14 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

6.2.9. 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 6.8 and Table 6.15 describe this element.

Resource Limits Tag

Figure 6.8 Resource Limits Tag Structure

Table 6.15 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

6.2.10. Enabling Distributed Logger

Distributed Logger is included in Connext DDS but it is not supported on all platforms; see the RTI Connext DDS Core Libraries Platform Notes for the set of platforms that support Distributed Logger.

When you enable Distributed Logger, the Cloud Discovery Service will publish its log messages to Connext DDS. Then you can use RTI Admin Console to visualize the log message data. Since the data is provided in a topic, you can also use rtiddsspy or even write your own visualization tool.

To enable Distributed Logger, use the tag <distributed_logger> within <adminstration>. For example:

<cloud_discovery_service name="MyCDS">
      <administration>
            ...
            <distributed_logger>
                <enabled>true</enabled>
            </distributed_logger>
        </administration>
        ...
</cloud_discovery_service>

For more details, see Enabling Distributed Logger in RTI Services, in the RTI Connext DDS Core Libraries User’s Manual.

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

6.4. 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 Command-Line Options for a list of the available options that can override XML settings.