.. include:: ../vars.rst .. _chapter-observability-framework: *************************************** Support for RTI |OBSERVABILITY_HEADING| *************************************** .. note:: This chapter demonstrates how to configure the |RTI_SP_PRODUCT| to secure DDS communications between |RTI_MONITORINGLIBRARY2| and |RTI_COLLECTORSERVICE|. Therefore, it assumes you already configured |RTI_OBSERVABILITY| in your system. For information about configuration, usage, and components of |OBSERVABILITY|, refer to the :link_addon_products_observability_up_two:`RTI Connext Observability Framework User's Manual `. If your |CONNEXT| applications use |RTI_OBSERVABILITY|, you may want to secure the DDS traffic published by |MONITORINGLIBRARY2| and control which |COLLECTORSERVICE| can subscribe to it. :link_addon_products_observability_up_two:`Telemetry data ` may contain sensitive information about your system (for example, logging messages) that must be protected from unauthorized access. |MONITORINGLIBRARY2| uses a |DP|, |TOPICs|, and |DWs| to publish telemetry data. |COLLECTORSERVICE| uses a |DP|, |TOPICs|, and |DRs| to subscribe to that data. Therefore, the |RTI_SP_PRODUCT| can be used to secure the communications between them as if they were regular |CONNEXT| applications. The |GovernanceDoc| and the |PermissionsDoc| provide specific XML tags for Observability. Configuring security for telemetry data does not affect your application data. You can secure telemetry data independently from your application data and vice versa. .. important:: * Refer to :ref:`section-recommendations-for-usage-with-observability` for suggestions on how to configure the |RTI_SP_PRODUCT| for |RTI_OBSERVABILITY|. * |LIGHT_SP_BUILTIN| **is not supported** for |RTI_OBSERVABILITY|. Creating a |GovernanceDoc| for |OBSERVABILITY_HEADING| ------------------------------------------------------ The first thing you need to determine is the level of protection you want for telemetry data (:xmlval:`ENCRYPT`, :xmlval:`ENCRYPT_WITH_ORIGIN_AUTHENTICATION`, :xmlval:`SIGN`, :xmlval:`SIGN_WITH_ORIGIN_AUTHENTICATION`, or :xmlval:`NONE`). Metrics and logs can have different levels of sensitivity, so you may want to protect them differently. Use the :xmltag:`monitoring_metrics_protection_kind` and :xmltag:`monitoring_logging_protection_kind` tags to set the protection level for metrics and logs, respectively. For example, if you want to encrypt logs but not metrics: .. literalinclude:: ../snippets/observability_governance_file_sign_metrics_encrypt_logs.xml :language: xml :emphasize-lines: 15-16 :caption: Example |GovernanceDoc| for |OBSERVABILITY| .. note:: :xmltag:`monitoring_metrics_protection_kind` applies to both event and periodic metrics. If one of these tags is not present in the |GovernanceDoc|, the protection level for that data (metrics or logs) is inherited from :xmltag:`discovery_protection_kind`. Both tags are optional. .. attention:: Protection kinds for Observability |TOPICs| must be configured using the XML tags described in this section. If they are configured using the |TOPIC| names in the :xmltag:`topic_expression` tag, an error will occur. Using wildcards will not result in an error. However, even if the wildcard matches a |TOPIC| name, the rule will not be applied. .. important:: If you also want to secure remote administration commands, you need to protect the ServiceRequest channel using the :xmltag:`service_request_protection_kind` XML tag. See :ref:`section-service-request-protection-kind` for further information. Creating a |PermissionsDoc| for |COLLECTORSERVICE_HEADING| ---------------------------------------------------------- The second thing you need to determine is which *Collector Services* can subscribe to telemetry data and which data they can subscribe to. For example, you may want to allow one |COLLECTORSERVICE| to subscribe to all telemetry data, while another subscribes only to metrics. Use the :xmltag:`subscribe_monitoring` XML tag in the |PermissionsDoc| to set which data a |COLLECTORSERVICE| instance can subscribe to. In the following example |PermissionsDoc|, the |COLLECTORSERVICE| subscribes to all telemetry data: .. literalinclude:: ../snippets/observability_permissions_file_subscribe_monitoring_all.xml :language: xml :emphasize-lines: 17 :caption: Example |PermissionsDoc| for |COLLECTORSERVICE| Valid values for :xmltag:`subscribe_monitoring` are :xmlval:`ALL` (logging and metrics), :xmlval:`METRICS`, and :xmlval:`NONE`. Note that a |COLLECTORSERVICE| cannot subscribe to logging data only. Also, this tag can only be used in allow rules. .. attention:: * The default rule for |OBSERVABILITY| endpoints is always :xmlval:`DENY` regardless of the value configured in the |PermissionsDoc|. * The :xmlval:`METRICS` value for the :xmltag:`subscribe_monitoring` tag **is not currently supported**. * Observability endpoint permissions must be configured using the :xmltag:`subscribe_monitoring` XML tag. If these permissions are configured using the |TOPIC| names in :xmltag:`topics`, an error will occur. Using wildcards will not result in an error. However, even if the wildcard matches a |TOPIC| name, the rule will not be applied. Allow rules in the |PermissionsDoc| are evaluated in order. If the Observability Domain ID matches the allowed :xmltag:`domains`, the |RTI_SP_PRODUCT| will check the :xmltag:`subscribe_monitoring` tag in that allow rule. The rule will be ignored, and the next rule will be evaluated, if the tag is not present, if the tag is set to :xmlval:`NONE`, or if the current |TOPIC| is the logging |TOPIC| and the tag is set to :xmlval:`METRICS`. The process continues until a rule applies. If none of the allow rules apply, the default rule will be applied (always :xmlval:`DENY`). Creating a |PermissionsDoc| for |MONITORINGLIBRARY2_HEADING| ------------------------------------------------------------ Publishing telemetry data **is always allowed**. Therefore, you do not need to create a special |PermissionsDoc| for |MONITORINGLIBRARY2|. You can reuse the same |PermissionsDoc| you created for |COLLECTORSERVICE| (although :xmltag:`subscribe_monitoring` is not required in this case). Enabling |RTI_SP_PRODUCT_HEADING| in |COLLECTORSERVICE_HEADING| --------------------------------------------------------------- The enablement of the |RTI_SP_PRODUCT| in |COLLECTORSERVICE| will depend on how you deployed |COLLECTORSERVICE| in your system. Using Docker Compose (Prepackaged) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you are using the prepackaged Docker Compose for your |RTI_OBSERVABILITY| deployment, the |RTI_OBSERVABILITY| components are configured using a JSON file the first time you run the ``rtiobservability`` script. Add the security artifacts to your JSON configuration file, as shown in the following example: .. code-block:: JSON :caption: Example JSON configuration file for |RTI_OBSERVABILITY| with |RTI_SP_PRODUCT| :emphasize-lines: 11-18 { "hostname": "localhost", "securityConfig": { "basicAuthUsername": "...", "basicAuthPassword": "...", "httpsSecurity": { "caCertificate": "...", "serverCertificate": "...", "serverKey": "..." }, "ddsSecurity": { "identityCaCertificate": "path/to/identityCaCert.pem", "permissionsCaCertificate": "path/to/permissionsCaCert.pem", "identityCertificate": "path/to/identityCert.pem", "identityKey": "path/to/identityKey.pem", "signedPermissionsFile": "path/to/signedPermissions.p7s", "signedGovernanceFile": "path/to/signedGovernance.p7s" } } } See :link_addon_products_observability_up_two:`Configure the JSON File in the RTI Connext Observability Framework User's Manual ` for further information on the JSON configuration file syntax and usage. If the JSON configuration contains the security artifacts, the |RTI_SP_PRODUCT| will be enabled automatically in |COLLECTORSERVICE|. Using Docker (Separate Deployment) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you are using a separate Docker deployment, the security artifacts should be bind-mounted when running the |COLLECTORSERVICE| Docker container as follows: .. code-block:: console :caption: Example bind-mounting of security artifacts for |COLLECTORSERVICE| -v path/to/identityCaCert.pem:/rti/security/dds/identity_ca.pem -v path/to/permissionsCaCert.pem:/rti/security/dds/permissions_ca.pem -v path/to/identityCert.pem:/rti/security/dds/identity_certificate.pem -v path/to/identityKey.pem:/rti/security/dds/private_key.pem -v path/to/signedPermissions.p7s:/rti/security/dds/permissions.p7s -v path/to/signedGovernance.p7s:/rti/security/dds/governance.p7s In addition, you need to set the ``CFG_NAME`` environment variable to one of the provided Docker image's builtin configurations that enable the |RTI_SP_PRODUCT| in |COLLECTORSERVICE|. See :link_addon_products_observability_up_two:`Docker (Separate Deployment) in the RTI Connext Observability Framework User's Manual ` for further information on the builtin configurations. For additional information on how to use the Docker image included with |COLLECTORSERVICE|, refer to `Docker's Collector Service article `_. Enabling |RTI_SP_PRODUCT_HEADING| in |MONITORINGLIBRARY2_HEADING| ----------------------------------------------------------------- To enable the |RTI_SP_PRODUCT| in |MONITORINGLIBRARY2|, you need to define a QoS profile with the properties related to security artifacts (|RTI_SP_PRODUCT| enablement, certificates, |GovernanceDoc|, and |PermissionsDoc|). Then, you need to set that profile name in ``participant_factory_qos.monitoring.distribution_settings.dedicated_participant.participant_qos_profile_name`` (see :link_connext_dds_pro_um:`MONITORING QosPolicy (DDS Extension) <#users_manual/MONITORING_QosPolicy.htm>` for further information on this field). For example: .. literalinclude:: ../snippets/observability_monitoring_qos_profile_with_security.xml :language: xml :emphasize-lines: 60-62 :caption: Example QoS configuration for enabling |RTI_SP_PRODUCT| in |MONITORINGLIBRARY2| .. note:: You can see an example of how to enable the |RTI_SP_PRODUCT| in |MONITORINGLIBRARY2| in the shipped Temperature example (``/observability/c++``). This example is described in detail in the :link_addon_products_observability_up_two:`RTI Connext Observability Framework Getting Started Guide `.