.. include:: vars.rst

.. _section-usage:

Usage
*****

This chapter explains how to run *Cloud Discovery Service* from a command-line tool. 
In particular, it describes:

- How to Start *Cloud Discovery Service* (:numref:`section-starting-cloud-discovery-service`).
- How to Stop *Cloud Discovery Service* (:numref:`section-stopping-cloud-discovery-service`).
- *Cloud Discovery Service* Command-line Parameters (:numref:`section-cloud-discovery-service-command-line-parameters`).

.. _section-starting-cloud-discovery-service:

Starting Cloud Discovery Service
---------------------------------
*Cloud Discovery Service* runs as a separate application. The script to run the
executable is in ``<NDDSHOME>/bin``.

.. code-block:: bash

    rticlouddiscoveryservice [options]

To start *Cloud Discovery Service* with a default configuration, enter:

.. code-block:: bash

    $NDDSHOME/bin/rticlouddiscoveryservice

This command will run *Cloud Discovery Service* indefinitely until you
stop it. See :numref:`section-stopping-cloud-discovery-service`.

.. note::
    
   *Cloud Discovery Service* is pre-loaded with a built-in configuration that
   has default settings. See :numref:`section-configuration-builtin`.

:numref:`TableCommandLineParameters` describes the command-line parameters.

.. _section-stopping-cloud-discovery-service:

Stopping Cloud Discovery Service
--------------------------------
To stop *Cloud Discovery Service*, press Ctrl-c. *Cloud Discovery Service*
will perform a clean shutdown.

.. _section-cloud-discovery-service-command-line-parameters:

Cloud Discovery Service Command-Line Parameters
-----------------------------------------------
The following table describes all the command-line parameters available in
*Cloud Discovery Service*. To list the available commands, run 
``rticlouddiscoveryservice -h``.

.. |br| raw:: html

   <br />

.. list-table:: Cloud Discovery Service Command-line Parameters
    :name: TableCommandLineParameters
    :widths: 5 10
    :header-rows: 1

    * - Parameter
      - Description
    * - ``-allowDomain <string>``
      - Set of forwarded domain IDs. Remaining domains are ignored. |br|        
        **Default:** ``DOMAIN_LIST_ALL`` (forward all domains). |br|
        **Overrides:** ``domain_list/allow_domain_id``
    * - ``-denyDomain <string>``
      - Subset of ignored domain IDs from the allowed domains. |br|
        **Default:** empty string (none is ignored) |br|
        **Overrides:** ``domain_list/deny_domain_id``
    * - ``-cfgFile <string>``
      - Path to the configuration file. |br|
        **Default:** (unspecified)
    * - ``-cfgName <string>``
      - Name of the *Cloud Discovery Service* configuration to be loaded. |br|
        It must match a ``<cloud_discovery_service>`` tag in the configuration 
        file. |br|
        **Default:** rti.cds.builtin.config.default. 
    * - ``-heapSnapshotDir <dir>``
      - Output directory where the heap monitoring snapshots are dumped. |br|
        The filename format is RTI_heap_<appName>_<processId>_<index>.
        Used only if heap monitoring is enabled. |br|
        **Default**: current working directory
    * - ``-heapSnapshotPeriod <sec>``
      - Period at which heap monitoring snapshots are dumped.
        Enables heap monitoring if > 0. |br|
        **Default**: 0 (disabled)
    * - ``-help``
      - Prints this help and exits.
    * - ``-ignoreXsdValidation``
      - Loads the configuration even if the XSD validation fails.
    * - ``-listConfig``
      - Prints the available configurations and exits.
    * - ``-maxObjectsPerThread <int>``
      - Maximum number of thread-specific objects that can be created. |br|
        **Default:** 2048
    * - ``-stopAfter <int>``
      - Number of seconds the *Cloud Discovery Service* runs before it 
        stops. |br|
        **Default:** (infinite).
    * - ``-transport <string>``
      - A comma separated list of transport resources, where each resource is 
        specified in the form: ``[alias:]receive_port`` |br|
        **Default:**  udpv4:7400 |br|
        **Overrides:** ``transport``
    * - ``-verbosity <int>``
      - Controls what type of messages are logged: |br| |br|
        0. Silent |br|
        1. Exceptions (*Connext DDS* and *Cloud Discovery Service*) |br|
        2. Warnings (*Cloud Discovery Service*) |br|
        3. Warnings (*Connext DDS*) |br|
        4. Local (*Cloud Discovery Service*) |br|
        5. Remote (*Cloud Discovery Service*) |br|
        6. Activity (*Cloud Discovery Service*) and Local (*Connext DDS*) |br| |br|
        Each verbosity level, ``n``, includes all the verbosity level smaller
        than ``n``.
    * - ``-version``
      - Prints the Cloud Discovery Service version and exits.

All the command-line parameters are optional; if specified, they override
the values of their corresponding settings in the loaded XML configuration. 
See :numref:`section-configuration` for the set of XML elements that can be 
overriden with command-line parameters.