.. xqd1614091832213
.. _install-ptp-notifications:

=========================
Install PTP Notifications
=========================

|PTP| notification is packaged as a system application and is managed
using the :command:`system application` and :command:`system helm-override`
commands.

The application monitors time related services on a host and provides an API
for subscribing to asynchronous status notifications as well as the ability to
pull the state of each service on demand.

.. note::

Changes to a node's |PTP| configuration, applied using the
:command:`system ptp-instance-apply`, requires the ``ptp-notification``
application to be removed and reapplied, using the
:command:`system application-remove ptp-notification`, and
:command:`system application-apply ptp-notification` commands.
This allows the containers to reload the updated configuration files and
monitor the services correctly.

**v1 API**

The legacy functionality of ``ptp-notification`` remains available and is
accessible through the v1 API; v1 is only capable of reporting status changes
for the |PTP| Sync State on a system.

**Limitations**

The v1 API only supports monitoring a single ``ptp4l + phc2sys`` instance.
Ensure the system is not configured with multiple instances when using the v1
API.

**v2 API**

The API conforms to O-RAN.WG6.O-Cloud Notification API-v02.01. Using the v2
API, multiple ``ptp4l`` instances can be tracked for independent |PTP| Sync
State and |PTP| Clock Class notifications.

The application monitors the following services:

- PTP Sync State

- PTP Clock Class

- OS Clock Sync State

- GNSS Sync State

- Overall System Sync State

.. rubric:: |context|

You must provide Helm override values indicating the ``ptp4l`` and ``phc2sys``
instances that you want tracked by your ``ptp-notification`` application.

Since multiple ``ptp4l`` instances can be supported on a node, you must specify
the ``ServiceName`` of the instance that the ``ptp-notification`` application
should track.

For example, follow the steps below:

.. rubric:: |proc|

#. Apply labels to nodes that will be running the ``ptp-notification``.

#. Apply the registration label to the controller nodes.

.. code-block::

~(keystone_admin)]$ system host-label-assign controller-0 ptp-registration=true

#. Apply the notification label to each node that is configured for PTP
clock synchronization.

.. code-block::

~(keystone_admin)]$ system host-label-assign controller-0 ptp-notification=true
~(keystone_admin)]$ system host-label-assign compute-0 ptp-notification=true

#. Verify the labels.

.. code-block::

~(keystone_admin)]$ system host-label-list <node name>

#. Locate the application tarball on the system controller.

.. code-block::

~(keystone_admin)]$ ls /usr/local/share/applications/helm/ptp-notification-<version>.tgz

#. Upload the ``ptp-notification`` application using the command below.

.. code-block::

~(keystone_admin)]$ system application-upload <path to application>

#. Verify if the application is in the uploaded state.

.. code-block::

~(keystone_admin)]$ system application-list

#. Apply Helm overrides as required. Create a yaml file and update the fields
that require Helm overrides.

.. code-block::

~(keystone_admin)]$ system helm-override-update ptp-notification ptp-notification notification --values notification-override.yaml

.. note::

You can override the default values for the ``ptp-notification``
application either by creating separate override sections for v1
and v2 APIs or by including v1 and v2 APIs in a single file as
shown in the example below.

.. code-block:: none

~(keystone_admin)]$ cat notification-override.yaml
ptptracking:
ptp4lServiceName: ptp4l-legacy
phc2sysServiceName: phc2sys-legacy
logging_level: INFO
ptp4lClockClassLockedList: "6,7,135"
device:
holdover_seconds: 15
poll_freq_seconds: 2
ptptrackingv2:
ptp4lServiceName: True
phc2sysServiceName: True
ts2phcServiceName: True
ptp4lClockClassLockedList: "6,7,135"
phc2sysToleranceThreshold: 1000
log_level: INFO
control_timeout: 2
device:
holdover_seconds: 15
osclock:
holdover_seconds: 15
overall:
holdover_seconds: 15

#. To configure the ``ptp-notification`` v1 API in a seperate section,
include the following in the ``notification-override.yaml`` file.
Ensure that values are updated to match the configured instance
names on your system.

.. code-block:: none

ptptracking:
enabled: True
ptp4lSocket: /var/run/ptp4l-instancename
ptp4lServiceName: ptp4l-instancename
phc2sysServiceName: phc2sys-instancename
logging_level: INFO
ptp4lClockClassLockedList: "6,7,135"
device:
holdover_seconds: 15
poll_freq_seconds: 2

``ptptracking``

where the values are:

``ptp4lSocket``
Update this value to include the correct instance name of your
configured ptp4l instance.

``ptp4lServiceName``
Update this value to the instance name of your configured ptp4l
instance.

``phc2sysServiceName``
Update this value to the instance name of your configure phc2sys
instance.

``logging_level: INFO``
Set the logging level. DEBUG can be used for additional logs.

``ptp4lClockClassLockedList``
Set the list of clock classes that will allow ``ptp-notification``
to report **Locked**. The clockClass for a monitored ptp4l instance
is read via the |PMC|. If the instance clockClass matches one of
the ``ptp4lClockClassLockedList`` values, then ``ptp-notification``
will report **Locked** for that instance.

The default values are "6,7,135", which means that
``ptp-notification`` will report locked when reading a clockClass
of 6, 7 or 135 from the configured ptp4l instance. These values are
recommended for nodes operating as Boundary Clock (BC).

For nodes operating as |GM|, it is recommended to set the value to
"6", so that only clockClass 6 is reported as locked.

``holdover_seconds``
``holdover_seconds`` configures how long each service will stay in
the HOLDOVER state before transitioning to FREERUN. The holdover
value used by the application equates to: holdover_seconds -
(poll_freq_seconds * 2).

This is done in order to account for time between the monitor
polling cycles. The ``holdover_seconds`` value should be configured
to match the validated holdover time provided by the device
manufacturer.

``poll_freq_seconds``
``poll_freq_seconds`` sets how frequently, in seconds the services
are checked.

#. To configure the ``ptp-notification`` v2 API in a separate section,
include the following in the ``notification-override.yaml`` file.
Ensure that values are updated to match the configured instance
names on your system.

.. code-block:: none

ptptrackingv2:
ptp4lServiceName: True
phc2sysServiceName: True
ts2phcServiceName: True
log_level: INFO
ptp4lClockClassLockedList: "6,7,135"
phc2sysToleranceThreshold: 1000
control_timeout: 2
device:
holdover_seconds: 15
osclock:
holdover_seconds: 15
overall:
holdover_seconds: 15

``ptptrackingv2``

where the values are:

``ptp4lServiceName: True``

``phc2sysServiceName: True``

``ts2phcServiceName: True``
- The ServiceName fields are defaulted to "True" in the
application and do not need to be altered.

- A service can be set to "False" in order to disable tracking
for that type. However, if a service type is not configured on
the node (i.e. node does not use ts2phc), then the application
automatically determines this and does not attempt to monitor
the node.

- Use these fields if there is a service that is configured on
the node that you do NOT want to track.

``log_level: INFO``
Set the logging level. DEBUG can be used for additional logs.

For nodes operating as |GM|, it is recommended to set the value to
"6", so that only clockClass 6 is reported as locked.

``phc2sysToleranceThreshold``
Default value: 1000

Set the skew threshold in nanoseconds at which ``ptp-notification``
will report that the system clock is no longer considered
**Locked**.

The ``ptp-notification`` application compares the time of the
system clock to the configured source PHC. If the delta between the
system clock and the |PHC| is greater than the
``phc2sysToleranceThreshold``, a notification will be generated
that the system clock is not locked.

``control_timeout: 2``
control_timeout sets how frequently, in seconds the services are checked.
Value applies to all service types.

``device``
``device`` refers to ptp4l monitoring

- ``holdover_seconds: 15``

- ``poll_freq_seconds: 2``

``osclock``
holdover_seconds: 15

``overall``
holdover_seconds: 15
``holdover_seconds`` configures how long each service will stay
in the HOLDOVER state before transitioning to FREERUN. The
holdover value used by the application equates to:
holdover_seconds - (control_timeout * 2).

This is done in order to account for time between the monitor
polling cycles. The ``holdover_seconds`` value should be
configured to match the validated holdover time provided by the
device manufacturer.

#. View existing values.

.. code-block:: none

~(keystone_admin)]$ system helm-override-show ptp-notification ptp-notification notification

#. Update and apply the values.

Application values can be added by the user and applied, using the following commands.

.. note::

Changes to the ``ptp-notification`` override values require the
application to be removed and re-applied in order to re-create the
application containers.

.. code-block:: none

~(keystone_admin)]$ system application-remove ptp-notification

~(keystone_admin)]$ system helm-override-update ptp-notification ptp-notification notification -–values <notification-override.yaml>

~(keystone_admin)]$ system application-apply ptp-notification

#. Verify the Helm overrides.

.. code-block::

~(keystone_admin)]$ system helm-override-show ptp-notification ptp-notification notification

#. Apply ``ptp-notification`` using the command below.

.. code-block::

~(keystone_admin)]$ system application-apply ptp-notification

#. Verify application status and pod status using the following commands:

#. Application Status

.. code-block::

~(keystone_admin)]$ system application-list

#. Pod Status

.. code-block::

~(keystone_admin)]$ kubectl get pods -n notification -o wide

.. rubric:: |postreq|

|prod-long| supports applications that rely on PTP for synchronization.
These applications are able to receive PTP status notifications from |prod-long|
hosting the application. For more information see:

- :ref:`PTP Notifications Overview <ptp-notifications-overview>`

- `API PTP Notifications <https://docs.starlingx.io/api-ref/ptp-notification-armada-app/api_ptp_notifications_definition_v1.html>`__

.. only:: partner

.. include:: /_includes/install-ptp-notifications-3a94b1ea1ae3.rest