.. include:: vars.rst .. _section-cloud-discovery-service-administration: Remote Administration ===================== A control client (such as *RTI Admin Console*) can use this interface to remotely control |CDS|. .. Note:: |CDS| remote administration is based on the |RAP| described in :ref:`section-Rap`. Please refer to that manual for a detailed discussion on the workings of remote administration in |CDS|. Below you will find an API reference for all the supported operations. .. _section-cloud-discovery-service-enable-remote-administration: Enabling Remote Administration ------------------------------ By default, remote administration is disabled in |CDS|. To enable remote administration you can use the ```` XML tag (see :ref:`section-config-administration-tag`) or the ``-remoteAdministrationDomainId`` command-line parameter (see :ref:`section-cloud-discovery-service-command-line-parameters`). Both of these methods enable remote administration and set the domain ID for remote communication. Available Service Resources --------------------------- :numref:`TableCloudDiscoveryServiceResources` lists the public resources specific to |CDS|. Each resource identifier is expressed as a hierarchical sequence of identifiers, including parent and target resources. (See :ref:`section-Arm-ResourceId` for details.) In the table below, the element ``(cds)`` refers to the name of an entity of the corresponding class as specified in the configuration in the ``name`` attribute. For example, in the following configuration: .. code-block:: xml ... The resource identifier is: .. code-block:: html /cloud_discovery_services/MyCDS In the table below, the resource identifier is written as /cloud_discovery_services/(cds), where (cds) is the service name. This nomenclature is used in the table to give you an idea of the structure of the resource identifiers. For actual example resource identifier names, see the example section that follows. .. list-table:: Resources and their identifiers in |CDS| :name: TableCloudDiscoveryServiceResources :widths: 20 80 :header-rows: 1 * - Resource - Resource Identifier * - |CDS| - /cloud_discovery_services/(cds) * - *Database* - /cloud_discovery_services/(cds)/database/[subset_info] where ``[subset_info]`` represents a specific smaller piece of the stored discovery information. The current available subsets are: - ``locators``: List of original and resolved locators for a specified participant. Example ^^^^^^^ This example shows you how to address a resource of each possible resource class in |CDS|. .. rubric:: |CDS| Entity with name "MyCDS": .. code-block:: xml ... Resource identifier: .. code-block:: html /cloud_discovery_services/MyCDS .. _section-cloud-discovery-service-remote-commands: Remote API Overview ------------------- .. list-table:: Remote Interface Overview :name: TableCloudDiscoveryServiceRemoteAdministrationAPI :widths: 10 50 30 :header-rows: 1 * - Resource - Operation - Description * - CloudDiscoveryService - :ref:`DELETE /cloud_discovery_services/(cds) ` - Shuts down a running |CDS| instance. * - - :ref:`UPDATE /cloud_discovery_services/(cds)/state ` - Sets a |CDS| state. * - - :ref:`GET /cloud_discovery_services/(cds)/state ` - Gets a |CDS| state. * - - :ref:`GET /cloud_discovery_services/(cds)/database/locators ` - Gets the list of original and resolved locators for a concrete participant. |CDS_Heading| ------------- .. _cloud-discovery-service-self-delete: .. function:: DELETE /cloud_discovery_services/(cds) **Operation** ``shutdown`` This operation will cause |CDS| to shutdown. .. _cloud-discovery-service-self-state-update: .. function:: UPDATE /cloud_discovery_services/(cds)/state **Operation** ``set_state`` Sets the state of a |CDS| object. The action is parameterized on octet_body, which could have the following values: See :ref:`section-Rap-CommonOps-SetState`. Valid requested states: * ``STARTED`` * ``STOPPED`` * ``ENABLED`` * ``DISABLED`` - Example To stop an instance of |CDS| with the name "MyCDS": .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /cloud_discovery_services/MyCDS/state * - ``octet_body`` - .. code-block:: C to_cdr_buffer(RTI::Service::EntityStateKind::STOPPED) For example code refer to :ref:`section-Rap-Communication-AccessingExample`. .. _cloud-discovery-service-self-state-get: .. function:: GET /cloud_discovery_services/(cds)/state **Operation** ``get_state`` Gets the state of a |CDS| object. The value is contained in the reply octet_body, which could have the following values: See :ref:`section-Rap-CommonOps-GetState` Valid reply states: * ``STARTED`` * ``STOPPED`` - Example To inspect the current state of an instance of |CDS| with the name "MyCDS": .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - GET * - ``resource_identifier`` - /cloud_discovery_services/MyCDS/state .. list-table:: :widths: 30 70 :header-rows: 1 * - Reply Field - Value * - ``octet_body`` - .. code-block:: C from_cdr_buffer(RTI::Service::Admin::CommandReply::octet_body) For example code refer to :ref:`section-Rap-Communication-AccessingExample`. Database -------- .. _cloud-discovery-service-self-database-locators-get: .. function:: GET /cloud_discovery_services/(cds)/database/locators **Operation** ``get_participant_locators`` Gets the list of resolved and original locators for a specified participant. The result is returned in the reply's string body as a JSON string with the following format: .. code-block:: C { "locators": { "original":{ "metatraffic":[ "original_mt_locator1", "original_mt_locator1", ... ], "default":[ "original_def_locator1", "original_def_locator2", ... ] }, "resolved":{ "metatraffic":[ "resolved_mt_locator1", "resolved_mt_locator2", ... ], "default":[ "resolved_def_locator1", "resolved_def_locator2", ... ] } } } The original locator set represent the locators contained in the participant announcement as it is received. The resolved locator set represent the locators |CDS| updates or extend to contain additional information necessary for the peer participants. This is for example important when using the *|RTI_RWT|*. The participant is provided in the string body as the string representation of the GUID with format: .. code-block:: C 0x0101C372,0x17D4CED6,0xEA7B3DA5:0x000001C1 - Example To locator information for a specific participant existing in the database of a |CDS| instance with the name "MyCDS": .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - GET * - ``resource_identifier`` - /cloud_discovery_services/MyCDS/database/locators * - ``string_body`` - .. code-block:: C 0x0101C372,0x17D4CED6,0xEA7B3DA5:0x000001C1 .. list-table:: :widths: 30 70 :header-rows: 1 * - Reply Field - Value * - ``string_body`` - .. code-block:: C { "locators": { "original":{ "metatraffic":[ "udpv4_wan://f=1,u={BD,73,FC,9E,D5,00,AB,6D,40},P=10.0.2.15:0:32410" ], "default":[ "udpv4_wan://f=1,u={BD,73,FC,9E,D5,00,AB,6D,40},P=10.0.2.15:0:32411" ] }, "resolved":{ "metatraffic":[ "udpv4_wan://f=7,u={BD,73,FC,9E,D5,00,AB,6D,40},P=188.78.49.211:56532:32410" ], "default":[ "udpv4_wan://f=7,u={BD,73,FC,9E,D5,00,AB,6D,40},P=188.78.49.211:56532:32410" ] } } }