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.

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.

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.

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.

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.

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.

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.

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.

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.