.. include:: vars.rst .. _section-Admin: ********************* Remote Administration ********************* This section provides documentation on |RS| remote administration. .. Note:: |RS| remote administration is based on the |RAP| described in :ref:`section-Rap`. We recommend that you read that section before using |RS| remote administration. Below you will find an API reference for all the supported operations. Overview ======== Enabling Remote Administration ------------------------------ By default, remote administration is disabled in |RS|. To enable remote administration, you can use the ```` tag (see :ref:`section-config-routing-service`) or the ``-remoteAdministrationDomainId`` command-line parameter, which enables remote administration and sets the domain ID for remote communication (see :ref:`section-usage-executable`). Available Service Resources --------------------------- :numref:`TableRouterResources` lists the public resources specific to |RS|. 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 elements ``(rs)``, ``(dr)``, ``(c)``, ``(s)``, ``(ar)``, ``(r)``, ``(i)``, and ``(o)`` refer 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 /routing_services/MyRouter In the table, the resource identifier is written as /routing_services/(rs), where (rs) is the |ROUTINGSERVICE| name, (dr) is the Domain Route name, and so on. 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 |RS| :name: TableRouterResources :widths: 20 80 :header-rows: 1 * - Resource - Resource Identifier * - |SERVICE| - /routing_services/(rs) * - |DOMAINROUTE| - /routing_services/(rs)/domain_routes/(dr) * - |CONNECTION| or *Participant* - /routing_services/(rs)/domain_routes/(dr)/connections/(c) * - |SESSION| - /routing_services/(rs)/domain_routes/(dr)/sessions/(s) * - |AR| or |ATR| - /routing_services/(rs)/domain_routes/(dr)/sessions/(s)/auto_routes/(ar) * - |ROUTE| or |TR| - /routing_services/(rs)/domain_routes/(dr)/sessions/(s)/routes/(r) * - |ROUTE| |INPUT| or DDS |INPUT| - /routing_services/(rs)/domain_routes/(dr)/sessions/(s)/routes/(r)/inputs/(i) * - |ROUTE| |OUTPUT| or DDS |OUTPUT| - /routing_services/(rs)/domain_routes/(dr)/sssions/(s)/routes/(r)/outputs/(i) Example ^^^^^^^ This example shows you how to address a resource of each possible resource class in |RS|, using the example configuration in :ref:`section-Admin-Example` as a reference. (For a complete reference of the available configuration tags used in |RS|, see :ref:`section-xml-tags-for-configuring-routing-service`.) .. tabs:: .. tab:: |SERVICE| Entity with name "MyRouter": .. code-block:: xml ... Resource identifier: .. code-block:: html /routing_services/MyRouter .. tab:: |DOMAINROUTE| Entity with name "MyDomainRoute" in parent "MyRouter": .. code-block:: xml ... Resource identifier: .. code-block:: html /routing_services/MyRouter/domain_routes/MyDomainRoute .. tab:: *Participant* Entity with name "MyParticipant" in parent "MyDomainRoute": .. code-block:: xml ... Resource identifier: .. code-block:: html /routing_services/MyRouter/domain_routes/MyDomainRoute/connections/MyParticipant .. tab:: |SESSION| Entity with name "MySession" in parent "MyDomainRoute": .. code-block:: xml ... Resource identifier: .. code-block:: html /routing_services/MyRouter/domain_routes/MyDomainRoute/sessions/MySession .. tab:: |AR| Entity with name "MyAutoTopicRoute" in parent "MySession": .. code-block:: xml ... Resource identifier (all on one line): .. code-block:: html /routing_services/MyRouter/domain_routes/MyDomainRoute/sessions/MySession/ routes/MyTopicRoute .. tab:: |ROUTE| Entity with name "MyTopicRoute" in parent "MySession": .. code-block:: xml ... Resource identifier (all on one line): .. code-block:: html /routing_services/MyRouter/domain_routes/MyDomainRoute/sessions/MySession/ routes/MyTopicRoute .. tab:: |INPUT| Entity with name "MyInput" in parent "MyTopicRoute": .. code-block:: xml ... Resource identifier (all on one line): .. code-block:: html /routing_services/MyRouter/domain_routes/MyDomainRoute/sessions/MySession/ routes/MyRoute/inputs/MyInput .. tab:: |OUTPUT| Entity with name "MyOutput" in parent "MyTopicRoute": .. code-block:: xml ... Resource identifier (all on one line): .. code-block:: html /routing_services/MyRouter/domain_routes/MyDomainRoute/sessions/MySession/ routes/MyRoute/outputs/MyOutput Resource Object Representations ------------------------------- .. list-table:: Resource Representations in |RS| :name: TableRouterResourceRepresentations :widths: 40 60 :header-rows: 1 :class: longtable * - Resource Representation - Format (all element type definitions are from the file rti_routing_service.xsd) * - *ddsObjectRepresentation* - .. code-block:: xml * - *routerObjectRepresentation* - .. code-block:: xml * - *domainRouteObjectRepresentation* - .. code-block:: xml * - *connectionObjectRepresentation* - .. code-block:: xml * - *participantObjectRepresentation* - .. code-block:: xml * - *sessionObjectRepresentation* - .. code-block:: xml * - *autoRouteObjectRepresentation* - .. code-block:: xml * - *autoTopicRouteObjectRepresentation* - .. code-block:: xml * - *routeObjectRepresentation* - .. code-block:: xml * - *topicRouteObjectRepresentation* - .. code-block:: xml * - *inputObjectRepresentation* - .. code-block:: xml * - *outputObjectRepresentation* - .. code-block:: xml * - *ddsInputObjectRepresentation* - .. code-block:: xml .. code-block:: xml * - *ddsOutputObjectRepresentation* - .. code-block:: xml .. code-block:: xml .. _section-Admin-ApiReference: API Reference ============= This section documents each remote operation, organized by service resource class. Remote API Overview ------------------- .. Note:: To improve readability, ```` is sometimes used in place of the service resource portion of the resource identifier (e.g., /routing_services/(rs) or /routing_services/MyService). It does not represent valid syntax. .. list-table:: Remote Interface Overview :name: TableRemoteAdminAPI :widths: 20 50 30 :header-rows: 1 :class: longtable * - Resource - Operation - Description * - |SERVICE| - :ref:`CREATE /routing_services/(rs)/domain_route ` - Creates a new |DOMAINROUTE|. * - - :ref:`CREATE /routing_services/(rs)/config ` - Loads a full service configuration. * - - :ref:`GET /routing_services/(rs) ` - Returns the |SERVICE| configuration. * - - :ref:`UPDATE /routing_services/(rs) ` - Updates a |SERVICE| object. * - - :ref:`UPDATE /routing_services/(rs)/state ` - Sets a |SERVICE| state. * - - :ref:`UPDATE /routing_services/(rs):save ` - Saves the |SERVICE| loaded configuration. * - - :ref:`DELETE /routing_services/(rs)/domain_routes/(dr) ` - Deletes a |DOMAINROUTE| object. * - - :ref:`DELETE /routing_services/(rs)/config ` - Deletes the |SERVICE| configuration. * - - :ref:`DELETE /routing_services/(rs) ` - Shuts down the running |SERVICE|. * - |DOMAINROUTE| - :ref:`CREATE /routing_services/(rs)/domain_route/(dr)/sessions ` - Creates a new |SESSION|. * - - :ref:`UPDATE /routing_services/(rs)/domain_route/(dr) ` - Updates a |DOMAINROUTE|. * - - :ref:`UPDATE /routing_services/(rs)/domain_route/(dr)/state ` - Sets a |DOMAINROUTE| state. * - - :ref:`DELETE /routing_services/(rs)/domain_route/(dr)/sessions/(s) ` - Deletes a |SESSION|. * - |CONNECTION| - :ref:`UPDATE \/domain_route/connections(c):add_peer ` - Adds a list of peers in a |CONNECTION| (a *Participant* in DDS adapter). * - - :ref:`UPDATE \/domain_route/(dr)/connections(c) ` - Updates a |CONNECTION|. * - - :ref:`DELETE \/domain_route/(dr)/connections(c):remove_peer ` - Removes a list of peers in a |CONNECTION| (a *Participant* in DDS adapter). * - |SESSION| - :ref:`CREATE \/domain_route/(dr)/sessions/(s)/auto_routes ` - Creates a new |AR|. * - - :ref:`CREATE \/domain_route/(dr)/sessions/(s)/routes ` - Creates a new |ROUTE|. * - - :ref:`UPDATE \/domain_route/(dr)/sessions(s) ` - Updates a |SESSION|. * - - :ref:`UPDATE \/domain_route/(dr)/sessions(s)/state ` - Sets a |SESSION| state. * - - :ref:`DELETE \/domain_route/(dr)/sessions/(s)/auto_routes/(ar) ` - Deletes an |AR|. * - - :ref:`DELETE \/domain_route/(dr)/sessions/(s)/routes/(r) ` - Deletes a |ROUTE|. * - |AR| or |ATR| - :ref:`UPDATE \/domain_route/(dr)/sessions/(s)/auto_routes(ar) ` - Updates an |AR|. * - - :ref:`UPDATE \/domain_route/(dr)/sessions/(s)/auto_routes(ar)/state ` - Sets an |AR| state. * - |ROUTE| or |TR| - :ref:`UPDATE \/domain_route/(dr)/sessions/(s)/routes(r) ` - Updates a |ROUTE|. * - - :ref:`UPDATE \/domain_route/(dr)/sessions/(s)/routes(r)/state ` - Sets a |ROUTE| state. * - |INPUT| - :ref:`UPDATE \/domain_route/(dr)/sessions/(s)/routes(r)/inputs/(i) ` - Updates an |INPUT| (|CONNEXT| and non-|CONNEXT|). * - |OUTPUT| - :ref:`UPDATE \/domain_route/(dr)/sessions/(s)/routes(r)/outputs/(o) ` - Updates an |OUTPUT| (|CONNEXT| and non-|CONNEXT|). .. _section-RemoteAdmin-Api-Service: Service ------- .. _service-create-domain-route: .. function:: CREATE /routing_services/(rs)/domain_routes **Operation** ``create_domain_route`` Creates a |DOMAINROUTE| object from its *domainRouteObjectRepresentation* (see :numref:`TableRouterResourceRepresentations`). See :ref:`section-Rap-CommonOps-Create` (:ref:`section-Rap-CommonOps-Create`). Example Create a |DOMAINROUTE| with name "NewDomainRoute" under |SERVICE| "MyRouter", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - CREATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes * - ``string_body`` - .. code-block:: xml str\://\" ... " The newly created object has the resource identifier: .. list-table:: :header-rows: 0 * - /routing_services/MyRouter/domain_routes/NewDomainRoute .... .. _service-load: .. function:: CREATE /routing_services/(rs)/config **Operation** ``load`` Loads a new configuration for the service from its *ddsObjectRepresentation* (see :numref:`TableRouterResourceRepresentations`). If the |SERVICE| is already loaded, this operation will unload it first. The provided configuration must contain a valid |SERVICE| configuration with the same name that the initial configuration used when the service was first instantiated. If the operation fails, the service will remain in an unloaded state. **Request body** - ``string_body``: a valid |SERVICE| XML configuration document provided as |SCHEME_FILE| or |SCHEME_STR|. **Reply body** - Empty. Example Load a new configuration in |SERVICE| "MyRouter". .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - CREATE * - ``resource_identifier`` - /routing_services/MyRouter/config * - ``string_body`` - .. code-block:: xml str://" ... ... ... ... " .... .. _service-get: .. function:: GET /routing_services/(rs) **Operation**: ``get`` Returns a snapshot of the currently loaded full XML configuration as *ddsObjectRepresentation* (see :numref:`TableRouterResourceRepresentations`). See :ref:`section-Rap-CommonOps-Get` (:ref:`section-Rap-CommonOps-Get`). Example reply body: .. code-block:: xml ./service_snapshot.xml " .... .. _service-set-state: .. function:: UPDATE /routing_services/(rs)/state **Operation**: ``set_state`` Sets the state of a |SERVICE| object. See :ref:`section-Rap-CommonOps-SetState` (:ref:`section-Rap-CommonOps-SetState`). Valid requested states: * ``ENABLED`` * ``DISABLED`` * ``PAUSED`` * ``RUNNING`` Example Enable a |SERVICE| with the name "MyRouter". .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/state * - ``octet_body`` - .. code-block:: C to_cdr_buffer(RTI::Service::EntityStateKind::ENABLED) .... .. _service-save: .. function:: UPDATE /routing_services/(rs):save **Operation**: ``save`` Dumps the currently loaded XML configuration into a file. The output file is specified by the ``save_path`` configuration tag. The ``save`` operation will fail if the ``save_path`` has not been configured. **Request body** - Empty. **Reply body** - Empty. .... .. _service-delete-dr: .. function:: DELETE /routing_services/(rs)/domain_routes/(dr) **Operation** ``delete_domain_route`` Deletes the specified |DOMAINROUTE|. See :ref:`section-Rap-CommonOps-Delete` (:ref:`section-Rap-CommonOps-Delete`). .... .. _service-unload: .. function:: DELETE /routing_services/(rs)/config **Operation** ``unload`` Unloads the current configuration of the service. If the |SERVICE| is enabled, this operation will disable it first. Upon a successful request, the service will remain in an unloaded state and no other operations can be made until a configuration is loaded. **Request body** - Empty. **Reply body** - Empty. .... .. _service-shutdown: .. function:: DELETE /routing_services/(rs) **Operation** ``shutdown`` Initiates the shutdown sequence on the process where the |Service| object runs. - If |SERVICE| runs as a process executed by the shipped executable in the |RTI_CONNEXT| installation, the process will exit upon receipt of the command. - If |SERVICE| is instantiated as a library in your application, the service instance will notify the installed remote shutdown hook. In both cases, right before executing the shutdown sequence, |SERVICE| will send a reply indicating the result of the operation. Note that if the operation returns successfully, the reply may be lost and never received by remote clients, since all the contained entities are deleted, including the |RAP| entities. This operation can be invoked at any time during the lifecycle of the service. **Request body** - Empty. **Reply body** - Empty. .. _section-RemoteAdmin-Api-DomainRoute: DomainRoute ----------- .. _dr-create-session: .. function:: CREATE /routing_services/(rs)/domain_routes/(dr)/sessions **Operation**: ``create_session`` Creates a |SESSION| object from its *sessionObjectRepresentation* (see :numref:`TableRouterResourceRepresentations`). See :ref:`section-Rap-CommonOps-Create` (:ref:`section-Rap-CommonOps-Create`). Example Create a |SESSION| with the name "NewSession" under the |DOMAINROUTE| "MyDomainRoute", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - CREATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute/sessions * - ``string_body`` - .. code-block:: xml str://" ... " The newly created object has the resource identifier: .. list-table:: :header-rows: 0 * - \/domain_routes/NewDomainRoute/sessions/NewSession .... .. _dr-update: .. function:: UPDATE /routing_services/(rs)/domain_routes/(dr) **Operation**: ``update`` Updates the specified |DOMAINROUTE| object. See :ref:`section-Rap-CommonOps-Update` (:ref:`section-Rap-CommonOps-Update`). The expected XML configuration is a subset of *domainRouteObjectRepresentation* and only contains the properties that are mutable and whose values have changed. Example Update a |DOMAINROUTE| with the name "MyDomainRoute" under the |SERVICE| "MyRouter", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute * - ``string_body`` - .. code-block:: xml str://" ... " .... .. _dr-setState: .. function:: UPDATE /routing_services/(rs)/domain_routes/(dr)/state **Operation**: ``set_state`` Sets the state of a |DOMAINROUTE| object. See :ref:`section-Rap-CommonOps-SetState` (:ref:`section-Rap-CommonOps-SetState`). Valid requested states: - ``ENABLED`` - ``DISABLED`` Example Enable a |DOMAINROUTE| with the name "MyDomainRoute" under the |SERVICE| "MyRouter". .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routers/MyDomainRoute/state * - ``octet_body`` - .. code-block:: C to_cdr_buffer(RTI::Service::EntityStateKind::ENABLED) .... .. _dr-delete-session: .. function:: DELETE /routing_services/(rs)/domain_routes/(dr)/sessions/(s) **Operation** ``delete_session`` Deletes the specified |SESSION|. See :ref:`section-Rap-CommonOps-Delete` (:ref:`section-Rap-CommonOps-Delete`). **Request body** - Empty. **Reply body** - Empty. .. _section-RemoteAdmin-Api-Connection: Connection ---------- .. _connection-addPeer: .. function:: UPDATE \/domain_routes/(dr)/connections/(c):add_peer **Operation** ``add_peer`` Adds a list of peers to the specified |CONNECTION|. The |CONNECTION| implementation shall refer to a ```` object. **Request body** - ``string_body``: A comma-separated list of peer descriptors, as described in :link_locator_format:`peer descriptor format<>`. - Example peer descriptor list: .. code-block:: bash updv4://10.2.0.1,udpv4://239.255.0.1 **Reply body** - Empty. .... .. _connection-update: .. function:: UPDATE \/domain_routes/(dr)/connections/(c) **Operation**: ``update`` Updates the specified |CONNECTION| object. See :ref:`section-Rap-CommonOps-Update` (:ref:`section-Rap-CommonOps-Update`). The expected XML configuration is a subset of *participantObjectRepresentation* or *connectionObjectRepresentation* and only contains the properties that are mutable and whose value is changed. Example Update a |CONNECTION| with the name "MyParticipant" under the |DOMAINROUTE| "MyDomainRoute", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute/ connections/MyParticipant * - ``string_body`` - .. code-block:: xml str://" property_name property_new_value " Example Update a |CONNECTION| with the name "MyConnection" under the |DOMAINROUTE| "MyDomainRoute", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute/ connections/MyConnection * - ``string_body`` - .. code-block:: xml str://" property_name property_new_value .... .. _connection-removePeer: .. function:: DELETE \/domain_routes/(dr)/connections/(c):remove_peer **Operation** ``remove_peer`` Removes a list of peers from the specified |CONNECTION|. The |CONNECTION| implementation shall refer to a ```` object. **Request body** - ``string_body``: A comma-separated list of peer descriptors, as described in :link_locator_format:`peer descriptor format<>`. - Example peer descriptor list: .. code-block:: bash updv4://10.2.0.1,udpv4://239.255.0.1 **Reply body** - Empty. .. _section-RemoteAdmin-Api-Session: Session ------- .. _session-createAutoRoute: .. function:: CREATE \/domain_routes/(dr)/sessions/(s)/auto_routes **Operation**: ``create_auto_route`` Creates an |AR| or |ATR| object from its *autoRouteObjectRepresentation* or *autoTopicRouteObjectRepresentation* (see :numref:`TableRouterResourceRepresentations`). See :ref:`section-Rap-CommonOps-Create` (:ref:`section-Rap-CommonOps-Create`). Example Create an |AR| with the name "NewAutoRoute" under the |SESSION| "MySession", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - CREATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/auto_routes * - ``string_body`` - .. code-block:: xml str://" ... " The newly created object has the resource identifier: .. list-table:: :header-rows: 0 * - /routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/auto_routes/NewAutoRoute .... .. _session-createRoute: .. function:: CREATE \/domain_routes/(dr)/sessions/(s)/routes **Operation**: ``create_route`` Creates a |ROUTE| or |TR| object from its *routeObjectRepresentation* or *topicRouteObjectRepresentation* (see :numref:`TableRouterResourceRepresentations`). See :ref:`section-Rap-CommonOps-Create` (:ref:`section-Rap-CommonOps-Create`). Example Create a |ROUTE| with the name "NewRoute" under the |SESSION| "MySession", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - CREATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes * - ``string_body`` - .. code-block:: xml str://" ... " The newly created object has the resource identifier: .. list-table:: :header-rows: 0 * - /routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes/NewRoute .... .. _session-update: .. function:: UPDATE \/domain_routes/(dr)/sessions/(s) **Operation**: ``update`` Updates the specified |SESSION| object. See :ref:`section-Rap-CommonOps-Update` (:ref:`section-Rap-CommonOps-Update`). The expected XML configuration is a subset of *sessionObjectRepresentation* and only contains the properties that are mutable and whose values have changed. Example Update a |SESSION| with the name "MySession" under the |DOMAINROUTE| "MyDomainRoute", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession * - ``string_body`` - .. code-block:: xml str://" MyNewPartition " .... .. _session-setState: .. function:: UPDATE \/domain_routes/(dr)/sessions/(s)/state **Operation**: ``set_state`` Sets the state of a |SESSION| object. See :ref:`section-Rap-CommonOps-SetState` (:ref:`section-Rap-CommonOps-SetState`). Valid requested states: - ``ENABLED`` - ``DISABLED`` Example Enable a |SESSION| with the name "MySession" under the |DOMAINROUTE| "MyDomainRoute". .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routers/MyDomainRoute/ sessions/MySession/state * - ``octet_body`` - .. code-block:: C to_cdr_buffer(RTI::Service::EntityStateKind::ENABLED) .... .. _session-deleteAutoRoute: .. function:: DELETE \/domain_routes/(dr)/sessions/(s)/auto_routes/(ar) **Operation** ``delete_auto_route`` Deletes the specified |AR|. See :ref:`section-Rap-CommonOps-Delete` (:ref:`section-Rap-CommonOps-Delete`). .... .. _session-deleteRoute: .. function:: DELETE \/domain_routes/(dr)/sessions/(s)/routes/(r) **Operation** ``delete_route`` Deletes the specified |ROUTE|. See :ref:`section-Rap-CommonOps-Delete` (:ref:`section-Rap-CommonOps-Delete`). .. _section-RemoteAdmin-Api-AutoRoute: AutoRoute --------- .. _ar-Update: .. function:: UPDATE \/domain_routes/(dr)/sessions/(s)/auto_routes/(ar) **Operation**: ``update`` Updates the specified |AR| or |ATR| object. See :ref:`section-Rap-CommonOps-Update` (:ref:`section-Rap-CommonOps-Update`). The expected XML configuration is a subset of *autoRouteObjectRepresentation* or *autoTopicRouteObjectRepresentation* and only contains the properties that are mutable and whose value is changed. Note that |AR| or |ATR| don't have any children resources. All the properties defined for the XML representation can be used for the update operation. Also the |ROUTE| or |TR| created as part of an |AR| or |ATR| can be updated independently. Example Update an |AR| with the name "MyAutoRoute" under the |SESSION| "MySession", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/auto_routes/MyAutoRoute * - ``string_body`` - .. code-block:: xml str://" 1 0 " .... .. _ar-setState: .. function:: UPDATE \/domain_routes/(dr)/sessions/(s)/auto_routes/(ar)/state **Operation**: ``set_state`` Sets the state of an |AR| object. See :ref:`section-Rap-CommonOps-SetState` (:ref:`section-Rap-CommonOps-SetState`). Valid requested states: - ``ENABLED`` - ``DISABLED`` - ``RUNNING`` - ``PAUSED`` Example Pause an |AR| with the name "MyAutoRoute" under the |SESSION| "MySession". .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routers/MyDomainRoute/ sessions/MySession/auto_routes/MyAutoRoutestate * - ``octet_body`` - .. code-block:: C to_cdr_buffer(RTI::Service::EntityStateKind::PAUSED) .. _section-RemoteAdmin-Api-Route: Route ----- .. _r-update: .. function:: UPDATE \/domain_routes/(dr)/sessions/(s)/routes/(r) **Operation**: ``update`` See :ref:`section-Rap-CommonOps-Update` (:ref:`section-Rap-CommonOps-Update`). The expected XML configuration is a subset of *routeObjectRepresentation* or *topicRouteObjectRepresentation* and only contains the properties that are mutable and whose value is changed. Example Update a |ROUTE| with the name "MyRoute" under the |SESSION| "MySession", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes/MyRoute * - ``string_body`` - .. code-block:: xml str://" property_name property_new_value " .... .. _r-setState: .. function:: UPDATE \/domain_routes/(dr)/sessions/(s)/routes/(r)/state **Operation**: ``set_state`` Sets the state of a |ROUTE| object. See :ref:`section-Rap-CommonOps-SetState` (:ref:`section-Rap-CommonOps-SetState`). Valid requested states: - ``ENABLED`` - ``DISABLED`` - ``RUNNING`` - ``PAUSED`` Example Pause a |ROUTE| with the name "MyRoute" under the |SESSION| "MySession". .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routers/MyDomainRoute/ sessions/MySession/routes/MyRoutestate * - ``octet_body`` - .. code-block:: C to_cdr_buffer(RTI::Service::EntityStateKind::PAUSED) .. _section-RemoteAdmin-Api-StreamPort: Input/Output ------------ .. _i-update: .. function:: UPDATE \/domain_routes/(dr)/sessions/(s)/routes/(r)/inputs(i) **Operation**: ``update`` See :ref:`section-Rap-CommonOps-Update` (:ref:`section-Rap-CommonOps-Update`). The expected XML configuration is a subset of *routeInputObjectRepresentation* or *topicRouteInputObjectRepresentation* and only contains the properties that are mutable and whose value is changed. Example Update |INPUT| with the name "MyInput" under the |TR| "MyRoute", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes/MyRoute/inputs/MyInput * - ``string_body`` - .. code-block:: xml str://" 1 0 " Example Update |INPUT| with the name "MyInput" under the |ROUTE| "MyRoute", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes/MyRoute/inputs/MyInput * - ``string_body`` - .. code-block:: xml str://" property_name property_new_value " .... .. _o-update: .. function:: UPDATE \/domain_routes/(dr)/sessions/(s)/routes/(r)/outputs(i) **Operation**: ``update`` See :ref:`section-Rap-CommonOps-Update` (:ref:`section-Rap-CommonOps-Update`). The expected XML configuration is a subset of *routeOutputObjectRepresentation* or *topicRouteOutputObjectRepresentation* and only contains the properties that are mutable and whose value is changed. Example Update |OUTPUT| with the name "MyOutput" under the |TR| "MyRoute", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes/MyRoute/inputs/MyInput * - ``string_body`` - .. code-block:: xml str://" 1 0 " Example Update |OUTPUT| with the name "MyOutput" under the |ROUTE| "MyRoute", with its configuration provided as a |SCHEME_STR| scheme. .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``action`` - UPDATE * - ``resource_identifier`` - /routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes/MyRoute/outputs/MyOutput * - ``string_body`` - .. code-block:: xml str://" property_name property_new_value " .... .. _section-Admin-Example: Example: Configuration Reference ================================ This configuration example shows how individual commands would apply to a valid |RS| configuration. .. code-block:: xml 0 ... true ... ... ... ... ... true ... ... ... ... ... ... true ... ... ... ... ... ... ... true ... ... ... ... ... ... ... ... ... .. _section-Remote-Shell: The Remote Administration Shell =============================== Any |CONNEXT| application can be implemented to send remote administration commands and receive the corresponding responses. A shell application that sends/receives these commands is provided with |ROUTINGSERVICE|. The script for the shell application is in ``/bin/rtirssh``. Entering ``rtirssh -help`` will show you the command-line options: .. code-block:: console RTI Routing Service Shell Usage: rtirssh [options]... Options: -domainId Domain ID for the remote configuration -timeout Max time to wait for a remote response -cmdFile Run commands in this file -help Displays this information Remote Shell Commands --------------------- This section describes the remote commands using the shell interface. The available remote commands are: .. list-table:: :widths: 25 50 :header-rows: 1 * - Command - Parameters * - :ref:`add_peer` - `` p1|p2 `` * - :ref:`create` - `` domain_route|session|topic_route|auto_route [] [remote|local]`` * - :ref:`delete` - `` []`` * - :ref:`disable` - `` []`` * - :ref:`enable` - `` []`` * - :ref:`get` - ```` * - :ref:`load` - `` [remote|local]`` * - :ref:`pause` - `` []`` * - :ref:`resume` - `` []`` * - :ref:`save` - ```` * - :ref:`shutdown` - ```` * - :ref:`unload` - ```` * - :ref:`update` - `` [] [|] [remote|local]`` .. _section-Remote-Shell-add-peer: Command: add_peer ----------------- .. code-block:: add_peer p1|p2 The ``add_peer`` command passes the ``peer_list`` to the underlying DomainParticipant's ``add_peer()`` function. It is only valid for DomainParticipants in a Domain Route. Parameter ```` is like ````, but must be a Domain Route entity. Parameter ``p1|p2`` specifies if the DomainParticipant associated with ```` or ```` configuration is selected. Parameter ```` is a comma-separated list of peers. .. _section-Remote-Shell-create: Command: create --------------- .. code-block:: create domain_route|session|topic_route|auto_route [] [remote|local] The create command is similar to :ref:`update`, but the configuration is applied to a newly created entity instead of an existing one. The second parameter ``(domain_route|session|topic_route|auto_route)`` is the kind of entity to be created. If the kind is a ``domain_route``, there will be no parent. For the other kinds (``session``, ``topic_route``, or ``auto_route``), a ```` must be specified. Parameters ```` and ``[remote|local]`` are the same as those used in :ref:`update`, except that only XML snippets matching the entity kind are allowed. A full file (starting with ````...) is not valid. For example (this would be entered as a single command, with no line-breaks): .. code-block:: create example topic_route DomainRoute::Session str://" ShapeType Triangle ShapeType Triangle" .. _section-Remote-Shell-delete: Command: delete --------------- .. code-block:: delete [] You can invoke the ``delete`` command on Domain Routes, Routes and Auto Routes. It acts like the :ref:`disable` command, but also purges the configuration data for the target entity. For example: .. code-block:: delete example DomainRoute::Session::CirclesToCircles A deleted entity cannot be re-enabled, but a new one can be created. ` .. _section-Remote-Shell-disable: Command: disable ---------------- .. code-block:: disable [] The disable command disables a |ROUTINGSERVICE| entity by destroying its sub-entities and corresponding DDS objects: * Routing service: When a |ROUTINGSERVICE| is disabled, all of its Domain Routes are destroyed. You do not need to specify the entity_name to disable a |ROUTINGSERVICE|. * Domain Route: When a Domain Route is disabled, all its Routes, Topic Routes, Auto Routes, and Auto Topic Routes are destroyed, as well as both Connections (DomainParticipants for DDS). All the session threads are stopped and their corresponding adapter sessions (|PUB| and |SUB| for DDS) are also deleted. * Route, Topic Route, Auto Route and Auto Topic Route: When a Route, Topic Route, Auto Route, or Auto Topic Route is disabled, its StreamReaders and StreamWriters are destroyed, so data will no longer be routed. .. _section-Remote-Shell-enable: Command: enable --------------- .. code-block:: enable [] The enable command enables an entity that has been disabled or marked as ‘enabled=false’ in the configuration file. This command can be used to enable the following entities: * Routing service: When a |ROUTINGSERVICE| is enabled, it uses the currently loaded configuration and starts. You don't need to specify the entity_name to enable a |ROUTINGSERVICE|. * Domain Route: When a Domain Route is enabled, it creates the Participants, Routes, Topic Routes, Auto Routes, and Auto Topic Routes that it contains. The Routes, Topic Routes, Auto Routes, and Auto Topic Routes will be created enabled or disabled depending on their current configuration. Enabling a Domain Route is required to start routing data from the input domain to the output domain. * Route, Topic Route, Auto Route, and Auto Topic Route: Enabling a Route, Topic Route, Auto Route or Auto Topic Route is a necessary condition to start routing data between input and output streams. However, data routing will not start until the StreamWriter and StreamReader associated with a Route are created (see :ref:`section-Config-StreamPort-CreationMode` for additional information). .. _section-Remote-Shell-get: Command: get ------------ .. code-block:: get The get command retrieves the current configuration. The retrieved configuration, provided in an XML string format, is functionally equivalent to the loaded XML file, plus any updates (either from an update command or other remote commands that change the configuration, such as ``add_peer``). However, the retrieved configuration may not be textually equivalent. For example, the retrieved configuration may explicitly contain default values that were not in the initial XML. .. _section-Remote-Shell-load: Command: load ------------- .. code-block:: load [remote|local] The load command loads specific XML configuration code. The ``target_routing_service`` must be disabled. For more information, see How to Load the XML Configuration :ref:`here`. The XML code received must represent a valid |ROUTINGSERVICE| configuration file. The name of the ```` tag to load is identified with ````. .. _section-Remote-Shell-pause: Command: pause -------------- .. code-block:: pause When the pause command is called for a Route, the session thread containing this Route will stop reading data from the Route’s StreamReader. For |ROUTINGSERVICE|, Domain Routes, Auto Routes, and Auto Topic Routes, the execution of this command will pause the contained Topic Routes and Routes. .. _section-Remote-Shell-resume: Command: resume --------------- .. code-block:: resume When the resume command is called for a Route, the session thread containing this Route will continue reading data from the Route’s StreamReader. For |ROUTINGSERVICE|, Domain Routes, Auto Routes and Auto Topic Routes, the execution of this command will resume the contained Topic Routes and Routes. .. _section-Remote-Shell-save: Command: save ------------- .. code-block:: save This command writes the current configuration to a file. The file itself is specified with ```` (see tag within the :ref:`TableAdministrationTag` table). If ```` has not been specified, the save command will fail. If the file specified by ```` already exists, the file will be overwritten. The saved configuration is functionally equivalent to the loaded XML file plus any updates (either from an ``update`` command or other remote commands that change the configuration, such as ``add_peer``). However it may not be textually equivalent. For example, the saved XML configuration may explicitly contain default values that were not in the initial XML. .. Note:: If the ```` tag (see tag within the :ref:`TableAdministrationTag` table) is set to ``TRUE``, this will automatically trigger a save command when configuration updates are received. .. _section-Remote-Shell-shutdown: Command: shutdown ----------------- .. code-block:: shutdown The shutdown command initiates the shutdown sequence on the process where the ``target_routing_service`` runs. The result of the remote shutdown command depends on how |ROUTINGSERVICE| is instantiated: * If Routing Service runs as a process executed by the shipped executable in your |RTI_CONNEXT| installation, the process will exit upon command reception. * If |ROUTINGSERVICE| is instantiated as a library in your application, the service instance will notify the installed remote shutdown hook. In this case, the application creating the Routing Service instance is responsible to handle the shutdown sequence. If the shutdown hook is not set, the command request will fail with a response indicating an error. On a successful shutdown request, |ROUTINGSERVICE| will send a reply with ``RTI_ROUTING_SERVICE_COMMAND_RESPONSE_OK``, or ``RTI_ROUTING_SERVICE_COMMAND_RESPONSE_ERROR`` and an error message indicating the problem. This command will take effect regardless of the ``target_routing_service``'s enabled state. .. _section-Remote-Shell-unload: Command: unload --------------- .. code-block:: unload The unload command unloads the current configuration that the target_routing_service is using, so you can change it with a subsequent :ref:`load` command. The ``target_routing_service`` must be disabled for this command to succeed. .. _section-Remote-Shell-update: Command: update --------------- .. code-block:: update [] [| [remote|local] The update command changes the configuration of a specific entity. The following table shows the parameters that can be changed for each entity: .. list-table:: :widths: 20 50 50 :header-rows: 1 :class: longtable * - Entity - Mutable (can be changed at any time) - Immutable (can only be changed when disabled) * - Routing Service - * ```` * ```` * ```` * ```` * ```` * ```` - * ```` * ```` * ```` * ```` * ```` * ```` * - Domain Route - * ````: Mutable properties in ```` (adapter-specific) * ````: Mutable QoS policies in ```` * ```` * ```` - * ````: Immutable properties in ```` (adapter-specific) * ````: Immutable QoS policies in ```` * ```` * ```` * - Session - * (Non-DDS) Mutable properties in ```` (adapter-specific) * (DDS) Mutable QoS policies in ```` and ```` * ```` * ```` - * (Non-DDS) Immutable properties in ```` (adapter-specific) * (DDS) Immutable QoS policies in ```` and ```` * ```` * ```` * - Route - * Mutable properties in ```` (adapter-specific) * Mutable properties in ```` (transformation-specific) - * Immutable properties in ```` (adapter-specific) * Immutable properties in ```` (transformation-specific) * - Auto Route - * Mutable properties in ```` (adapter-specific) - * Immutable properties in ```` (adapter-specific) * - Topic Route - * Mutable QoS policies in ```` and ```` * Mutable properties in ```` (transformation-specific) * ```` * ```` * ```` * ```` * ```` * ```` * ```` - * Immutable properties in ```` and ```` * ```` * ``/`` * ```` * ```` * - Auto Topic Route - * Mutable QoS policies in ```` and ```` * Mutable properties in ```` (transformation-specific) * ```` * ```` * ```` * ```` * ```` * ```` - * Immutable properties in ```` and ```` * ```` * ``/`` * ```` * ```` * ```` * ```` * ```` * ```` * ```` * ```` If you try to change an immutable parameter in an entity that is enabled, you will receive an error message. To change an immutable parameter, you must disable the |ROUTINGSERVICE| entity, change the parameter, and then enable the |ROUTINGSERVICE| entity again. You can send an XML snippet (or an assignment expression) that only contains the values you want to change for that entity, or you can send a whole well-formed configuration file: * If you send an XML snippet (or an assignment expression), only the changes you specify will take effect. For example, suppose you send this command: .. code-block:: update ShapeRouter DomainRoute1::Session1::SquareToCircles str://" 1 " or .. code-block:: update ShapeRouter DomainRoute1::Session1::SquareToCircles topic_route.input.datareader_qos.deadline.period.sec = 1 The Topic Route ``DomainRoute1::Session1::SquareToCircles`` will only change the period value in the Deadline QoS for that particular |DR|. Now suppose that later on you send this command: .. code-block:: update ShapeRouter DomainRoute1::Session1::SquareToCircles str://" MyPropMyValueRemote " This would only change the Property QoS; the Deadline QoS would keep the setting from the prior command. In both cases, an update command can only reconfigure one entity at a time and |ROUTINGSERVICE| will ignore all contained entities. For example, a command to update a session will not modify the configuration of its contained Routes. If you need to reconfigure several entities at the same time, consider using the :ref:`load` command. * If you send a well-formed configuration file (starting with ````), the properties in the Route (QoS values in the Topic Route) will be completely replaced with the properties (QoS values) defined in the XML code. If a QoS value for a Topic Route is not defined in the XML code, |ROUTINGSERVICE| will use the |CONNEXT| default.