.. include:: vars.rst

.. _section-configuration:

Configuration
*************

Configuring Cloud Discovery Service
===================================

This section provides a reference for the XML elements that conform a |RS|
configuration. For details on how to provide XML configurations to |RS|.
refer to :ref:`section-Common-Config`. This chapter describes how to write
an XML configuration.

.. _section-xml-tags-for-configuring-cloud-discovery-service:

XML Tags for Configuring |project|
==================================

This section describes the XML tags you can use in a |CDS| configuration file.
The following diagram and :numref:`TableTopLevelTag` describe the top-level
tags allowed within the root ``<dds>`` tag.

.. figure:: static/CDS_DDS_Tag.png
    :alt: Top-level Tags in the Configuration File
    :name: FigureTopLevelTag
    :align: center
    :width: 300px

    Top-level Tags in the Configuration File

.. list-table:: Top-level Tags in the Configuration File
    :name: TableTopLevelTag
    :widths: 20 50 10
    :header-rows: 1

    * - Tags within ``<dds>``
      - Description
      - Multiplicity
    * - ``<cloud_discovery_service>``
      - Specifies a |CDS| configuration. |br|

        Attributes
            - ``name``: uniquely identifies a service configuration.
              **Required**.

        Example
            .. code-block:: xml

                <cloud_discovery_service name="ExampleService">
                    <!-- your service settings ... -->
                </cloud_discovery_service>

      - 1..*.

.. _section-cloud-discovery-service-tag:

Cloud Discovery Service
-----------------------

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

When you start |CDS|, 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 |CDS| executions.

:numref:`FigureCloudDiscoveryServiceTag` and
:numref:`TableCloudDiscoveryServiceTag` describe the tags allowed within a
``<cloud_discovery_service>`` tag.

.. figure:: static/CDS_Service_Tag.png
    :alt: Cloud Discovery Service Tag
    :name: FigureCloudDiscoveryServiceTag
    :align: center
    :width: 400px

    Cloud Discovery Service Tag Structure

.. list-table:: Cloud Discovery Service Tag
    :name: TableCloudDiscoveryServiceTag
    :widths: 20 50 10
    :header-rows: 1

    * - 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, |CDS| will use the same 
        domain as administration by default.
        See :ref:`section-config-administration-tag`.
      - 0..1
    * - ``<monitoring>``
      - Enables monitoring for |CDS|, including the periodic publication of statistics.
        See :numref:`section-config-monitoring-tag`.
      - 0..1
    * - ``<domain_list>``
      - Set of domains for which the service forwards participant
        announcements. |br|
        See :ref:`section-config-domain-list`.
      - 0..1
    * - ``<transport>``
      - Selection of unicast transport resources where the service receives
        and sends participant announcements. |br|
        See :ref:`section-config-transport`.
      - 0..1
    * - ``<security>``
      - Configures the security features provided by the |RTI_SP|. |br|
        See :ref:`section-config-security`.
      - 0..1
    * - ``<forwarder>``
      - Configures the behavior of the participant announcement forwarding
        logic. |br|
        See :ref:`section-config-forwarder`.
      - 0..1
    * - ``<database>``
      - Configures the behavior of the service's internal database,
        which contains information about the discovery state. |br|
        See :ref:`section-config-database`.
      - 0..1
    * - ``<resource_limits>``
      - Service resource management policies. |br|
        See :ref:`section-config-resource-limits`.
      - 0..1

Example: Specify a Configuration in XML
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: xml

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

Starting |CDS| with the following command will use the
``<cloud_discovery_service>`` tag with the name ``EmptyConfiguration``.

.. code-block:: bash

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

.. _section-config-administration-tag:

Administration
--------------

The ``<administration>`` tag allows you to enable and configure remote
administration of |CDS|, including stopping, starting, and deleting a |CDS| 
instance.

See :ref:`section-cloud-discovery-service-administration` for details on
using remote administration.

.. list-table:: Administration Tags in |CDS_Heading|'s Configuration File
    :name: TableAdministrationTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - 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| defaults will be used.
      - 0..1
    * - ``<publisher_qos>``
      - QoS used by the administration Publisher.
        If the tag is not defined, |CONNEXT| defaults will be used.
      - 0..1
    * - ``<subscriber_qos>``
      - QoS used by the administration Subscriber.
        If the tag is not defined, |CONNEXT| defaults will be used.
      - 0..1
    * - ``<datawriter_qos>``
      - QoS used by administration DataWriter(s).
        If the tag is not defined, |CONNEXT| 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| 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 |DISTLOG|, |CDS| will publish its log messages 
        to |CONNEXT|.
        See :ref:`section-config-enabling-distributed-logger`.
      - 0..1

The contents of the tags for configuring QoS are specified in the same
manner as for the |CONNEXT| XML QoS Profiles file. See
:link_configuring_qos_xml:`Configuring QoS with XML <>`, in the |RTI_CONNEXT| 
Core Libraries User's Manual.

.. _section-config-monitoring-tag:

Monitoring
-----------

The ``<monitoring>`` tag allows you to enable and configure remote
monitoring of |CDS|.
See :ref:`section-cloud-discovery-service-monitoring`.

.. list-table:: Monitoring Tags in |CDS|'s Configuration File
    :name: TableMonitoringTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - 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| XML QoS Profiles file. See
:link_xml_qos_config:`Configuring QoS with XML <>`, in the |RTI_CONNEXT| 
Core Libraries User's Manual.

.. _section-config-domain-list:

Domain List
-----------

A ``<domain_list>`` allows you to control for which domains the discovery traffic
is propagated. :numref:`TableDomainListTag` describes the tags allowed.


:numref:`FigureDomainListTag` and
:numref:`TableDomainListTag` describe the tags allowed within a
``<domain_list>`` tag.

.. figure:: static/CDS_DomainList_Tag.png
    :alt: Domain List Tag
    :name: FigureDomainListTag
    :align: center
    :width: 400px

    Domain List Tag Structure


.. list-table:: Domain List Tag
    :name: TableDomainListTag
    :widths: 20 50 10
    :header-rows: 1

    * - Tags within ``<domain_list>``
      - Description
      - Multiplicity
    * - ``<allow_domain_id>``
      - Set of domain IDs where the service forwards participant announcements.
        |br|
        **Default:** ``DOMAIN_LIST_ALL``
      - 0..1
    * - ``<deny_domain_id>``
      - Subset of the allowed domain IDs for which the service ignores
        announcements. |br|
        **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.

Example: Deny a Few Specific Domains
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: xml

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

Example: Allow a Subset of Domains
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: xml

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


.. _section-config-transport:

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, |CDS| creates a send resource.

:numref:`FigureTransportTag` and :numref:`TableTransportTag` shows the
description of this element.

.. figure:: static/CDS_Transport_Tag.png
    :alt: Transport Tag
    :name: FigureTransportTag
    :align: center
    :width: 400px

    Transport Tag Structure


.. list-table:: Transport Tag
    :name: TableTransportTag
    :widths: 20 50 10
    :header-rows: 1

    * - Tags within ``<transport>``
      - Description
      - Multiplicity
    * - ``<element>``
      - Individual transport receive resource. |br|
        See :numref:`TableTransportElementTag`.
      - 0..*


Each ``<element>`` within ``<transport>`` is a transport unicast receive
resource, specified by a transport alias and a receive port.
:numref:`TableTransportElementTag` describes the tags allowed.


.. list-table:: Transport Element Tag
    :name: TableTransportElementTag
    :widths: 20 50 10
    :header-rows: 1

    * - Tags within ``<element>`` of a ``<transport>``
      - Description
      - Multiplicity
    * - ``<alias>``
      - Identifies a concrete transport class instantiation. |br|
        **Default:** udpv4 |br| |br|
        If the transport supports it, you can reuse the same transport instance
        by specifying the same alias. |br|

        .. note::

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

      - 0..1
    * - ``<receive_port>``
      - Port that the service listens on to receive participant announcements. |br|
        **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. |br|
                - **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:
            .. code-block:: xml

                <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, |CDS| will log a warning.

      - 0..1


|CDS| 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,
    |CDS| will log a warning.

.. list-table:: Available Transports
    :name: TableAvailableTransports
    :widths: 10 50 10
    :header-rows: 1

    * - Alias
      - Description
      - Prefix
    * - ``udpv4`` or ``builtin.udpv4``
      - Builtin implementation of UDPv4. |br|

        - **Class ID**: NDDS_TRANSPORT_CLASSID_UDPv4
        - **Reuse**: Yes
      - ``dds.transport.UDPv4.builtin``
    * - ``udpv4_wan`` or ``builtin.udpv4_wan``
      - Implementation of UDPv4 for WAN networks. |br|

        - **Class ID**: NDDS_TRANSPORT_CLASSID_UDPv4_WAN
        - **Reuse**: No

        .. note::

            Your library path requires libraries from |RTI_RWT| Support
            (``nddsrwt``).

      - ``dds.transport.UDPv4_WAN.builtin``
    * - ``udpv6`` or ``builtin.udpv6``
      - Builtin implementation of UDPv6. |br|

        - **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. |br|

        - **Class ID**: See **parent.classid** in
          :numref:`TableTcpTransportProperties`
        - **Reuse**: No

        .. note::

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

      - |CDS_TCP_PREFIX|

.. _section-registered-udp-transport:

Preregistered UDP Transports
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

|CDS| registers an instance for the following UDP transports:

- UDPv4
- UDPv4 WAN or the |RTI_RWT|
- UDPv6

There are no preset properties for any of these instances.

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

- :link_udpv4_properties:`Connext DDS UDPv4 configuration <>`
- :link_udpv4_wan_properties:`Connext DDS Real-Time WAN Transport configuration <>`
- :link_udpv6_properties:`Connext DDS UDPv6 configuration <>`

.. _section-registered-tcp-transport:


Preregistered TCP Transport
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

|CDS| registers an instance of the RTI TCP transport.
:numref:`TableTcpTransportProperties` shows a list of preset properties.

See :link_tcpv4_properties:`RTI TCP Transport configuration <>` for a list of
available properties.


.. list-table:: TCP Transport preset properties
    :name: TableTcpTransportProperties
    :widths: 50 50
    :header-rows: 1

    * - Property name (prefix with |CDS_TCP_PREFIX|)
      - 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``


Example: Reusing UDP Transport Instance for Multiple Receive Resources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: xml

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

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

.. code-block:: xml

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


.. _section-config-security:

Security
--------

The ``<security>`` element allows you to enable and configure the security
features provided by the |SP|. For further details, see :ref:`section-security`.

:numref:`TableSecurityTag` shows the description of this element.

.. list-table:: Security Tag
    :name: TableSecurityTag
    :widths: 20 50 10
    :header-rows: 1

    * - 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 :ref:`section-security`.

        Example:
            .. code-block:: xml

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

      - 0..1


.. _section-config-forwarder:

Forwarder
---------

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

:numref:`FigureForwarderTag` and :numref:`TableForwarderTag` describe
this element.

.. figure:: static/CDS_Forwarder_Tag.png
    :alt: Forwarder Tag
    :name: FigureForwarderTag
    :align: center
    :width: 400px

    Forwarder Tag Structure

.. list-table:: Forwarder Tag
    :name: TableForwarderTag
    :widths: 20 50 10
    :header-rows: 1

    * - 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. |br|
                A zero seconds period value is allowed and indicates that a 
                refresh announcement is forward upon its reception from the
                participant. |br|
                Default: 60 s.
            
        Example
            .. code-block:: xml

                <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. |br|
        This element allows you to specify the number of threads as well as
        the properties of those threads.

        Example
            .. code-block:: xml

                <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 :numref:`FigureFlowControllerTag` and
        :numref:`TableFlowControllerTag`.
      - 0..1


The ``<flow_controller>`` element allows you to configure the output traffic
of |CDS|. 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.

:numref:`FigureFlowControllerTag` and :numref:`TableFlowControllerTag`
describe this element.

.. figure:: static/CDS_FlowController_Tag.png
    :alt: Flow Controller Tag
    :name: FigureFlowControllerTag
    :align: center
    :width: 400px

    Flow Controller Tag Structure



.. list-table:: Flow Controller Tag
    :name: TableFlowControllerTag
    :widths: 20 50 10
    :header-rows: 1

    * - Tags within ``<flow_controller>``
      - Description
      - Multiplicity
    * - ``<output_capacity>``
      - Specifies a limit for the output capacity in jobs per second. |br|
        **Default:** ``LENGTH_UNLIMITED`` |br|

      - 0..1
    * - ``<max_burst_jobs>``
      - Maximum amount of announcement jobs that can be dispatched at once. |br|
        **Default:** ``<output_capacity>`` * 1 second |br|

      - 0..1
    * - ``<output_capacity_allocation>``
      - Configures the output capacity distribution depending on the
        participant announcement class.
        See :numref:`TableOutputCapacityAllocationTag`.

        Example
             .. code-block:: xml

                <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. |br|
        **Default:** ``DURATION_INFINITE``.

        Example
            .. code-block:: xml

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

:numref:`TableOutputCapacityAllocationTag` describes this element.

.. list-table:: Output Capacity Allocation Tag
    :name: TableOutputCapacityAllocationTag
    :widths: 20 50 10
    :header-rows: 1

    * - Tags within ``<output_capacity_allocation>``
      - Description
      - Multiplicity
    * - ``<new>``
      - Percentage of the maximum output capacity dedicated to the **new**
        participant announcement class. |br|
        **Default:** 40
      - 0..1
    * - ``<update>``
      - Percentage of the maximum output capacity dedicated to the **update**
        participant announcement class. |br|
        **Default:** 30
      - 0..1
    * - ``<refresh>``
      - Percentage of the maximum output capacity dedicated to the **refresh**
        participant announcement class. |br|
        **Default:** 30
      - 0..1


Note that the sum of the percentages from the three classes can never be
greater than **100**. Otherwise |CDS| 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, |CDS| will equally split the remaining of the
output capacity among them.

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

.. code-block:: xml

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


.. _section-config-database:

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.

:numref:`FigureDatabaseTag` and :numref:`TableDatabaseTag`
describe this element.


.. figure:: static/CDS_Database_Tag.png
    :alt: Database Tag
    :name: FigureDatabaseTag
    :align: center
    :width: 400px

    Database Tag Structure


.. list-table:: Database Tag
    :name: TableDatabaseTag
    :widths: 20 50 10
    :header-rows: 1

    * - Relevant tags within ``<database>``
      - Description
      - Multiplicity
    * - ``<thread>``
      - Database thread settings. |br|
        See **thread** in
        :link_database_qos:`DatabaseQosPolicy <>`.
      - 0..1
    * - ``<cleanup_period>``
      - The period at which the service database thread wakes up to clean up
        expired information.  |br|
        See **cleanup_period** in
        :link_database_qos:`DatabaseQosPolicy <>`.

        Example
            .. code-block:: xml

                <cleanup_period>
                    <sec>1</sec>
                    <nanosec>0</nanosec>
                </cleanup_period>

      - 0..1
    * - ``<initial_records>``
      - The initial number of total records. |br|
        See **initial_records** in
        :link_database_qos:`DatabaseQosPolicy <>`.
      - 0..1


.. _section-config-resource-limits:

Resource Limits
---------------

The ``<resource_limits>`` element allows you to specify upper limits of
memory consumption. In general, |CDS| 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.

:numref:`FigureResourceLimitsTag` and :numref:`TableResourceLimitsTag`
describe this element.

.. figure:: static/CDS_ResourceLimits_Tag.png
    :alt: Resource Limits Tag
    :name: FigureResourceLimitsTag
    :align: center
    :width: 400px

    Resource Limits Tag Structure

.. list-table:: Resource Limits Tag
    :name: TableResourceLimitsTag
    :widths: 20 50 10
    :header-rows: 1

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

.. _section-config-enabling-distributed-logger:

Enabling Distributed Logger
----------------------------

|DISTLOG| is included in |CONNEXT| but it is not supported on all platforms; 
see the |RTI_CONNEXT| Core Libraries Platform Notes for the set of platforms 
that support |DISTLOG|.

When you enable |DISTLOG|, the |CDS| will publish its log messages to |CONNEXT|. 
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 |DISTLOG|, use the tag ``<distributed_logger>`` within
``<adminstration>``. For example:

    .. code-block:: xml

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

For more details, see
:link_usermanual_distlog_in_services:`Enabling Distributed Logger in RTI Services <>`,
in the |RTI_CONNEXT| Core Libraries User's Manual.

.. _section-configuration-builtin:

Builtin Configuration
=====================

|CDS| 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:

.. code-block:: xml

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

Overriding XML Settings
=======================

|CDS| 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 :ref:`section-cloud-discovery-service-command-line-parameters` for a
list of the available options that can override XML settings.