Install PTP Notifications

PTP notification is packaged as a system application and is managed using the system application and 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.

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

About this task

StarlingX provides the capability for application(s) to subscribe to asynchronous PTP status notifications and pull for the PTP state on demand.

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:

Procedure

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

   1. Apply the registration label to the controller nodes.

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

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

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

   3. Verify the labels.

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

2. Locate the application tarball on the system controller.

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

3. Upload the ptp-notification application using the command below.

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

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

   ~(keystone_admin)]$ system application-list
   

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

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

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

      ptptrackingv2:
        ptp4lServiceName: True
        phc2sysServiceName: True
        ts2phcServiceName: True
        log_level: INFO
        ptp4lClockClassLockedList: "6,7,135"
        phc2sysToleranceThreshold: 1000
        control_timeout: 2
        device:
          holdover_seconds: 14400  # Match device manufacturer spec
        gnss:
          holdover_seconds: 14400
        osclock:
          holdover_seconds: 14400
        overall:
          holdover_seconds: 14400
      

      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.

      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.

      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

      Sets how frequently, in seconds, the services are polled for state changes. Applies to all service types. Default: 2.

Holdover Parameters

The following parameters control how long each component of the ptp-notification service remains in the Holdover state before transitioning to Freerun. Each parameter is optional. When not set via Helm override, the application uses the following priority chain to resolve the holdover value:

1. Helm override (sets an environment variable in the container)

2. Per-instance value from instance-monitoring.conf (see PTP Instance Monitoring Parameters)

3. Code default: 30 seconds

Note

The instance-monitoring.conf file is always generated during PTP instance deployment with a system default of 14400 seconds (4 hours) for holdover_seconds. This means that in a default installation without any user overrides, the effective holdover time is 14400 seconds, not the 30-second code default. The code default is only used as a last resort if the config file is missing or unreadable.

The config file values can be customized using system ptp-instance-parameter-add with the --section monitoring option. When both a Helm override and a per-instance config file value are present, the Helm override takes precedence.

device

Controls the holdover duration for ptp4l instance monitoring.

holdover_seconds: Duration in seconds that a ptp4l instance will remain in Holdover before transitioning to Freerun. System default: 14400 (4 hours).

If the ptp4l instance shares a PTP device with a ts2phc instance, the effective holdover time is the minimum of the ptp4l holdover and the ts2phc (GNSS) holdover. This ensures that the ptp4l holdover does not exceed the validity of its upstream timing source.

gnss

Controls the holdover duration for ts2phc (GNSS) instance monitoring.

holdover_seconds: Duration in seconds that a GNSS timing source will remain in Holdover before transitioning to Failure-Nofix. System default: 14400 (4 hours).

osclock

Controls the holdover duration for OS clock (phc2sys) monitoring.

holdover_seconds: Duration in seconds that the OS clock will remain in Holdover before transitioning to Freerun. System default: 14400 (4 hours).

overall

Controls the holdover duration for the overall sync state notification.

holdover_seconds: Fallback holdover duration in seconds. System default: 14400 (4 hours).

Note

The overall sync state holdover time is dynamically calculated at each poll cycle as the minimum of the active sync chain component holdover times. For example, if the OS clock holdover is 30 seconds and the upstream PTP source holdover is 45 seconds, the effective overall holdover is 30 seconds. The configured holdover_seconds value is only used as a fallback when the active sync chain cannot be determined.

The holdover_seconds value should be configured to match the validated holdover time provided by the device manufacturer.

Note

For new deployments, it is recommended to configure holdover values using system ptp-instance-parameter-add with the --section monitoring option instead of Helm overrides. This allows per-instance holdover configuration and ensures that both collectd and ptp-notification use the same values. See PTP Instance Monitoring Parameters for details.

1. View existing values.

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

2. Update and apply the values.

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

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

1. Verify the Helm overrides.

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

2. Apply ptp-notification using the command below.

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

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

   1. Application Status

      ~(keystone_admin)]$ system application-list
      

   2. Pod Status

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

Automatic Configuration Reload

The ptp-notification service automatically detects changes to PTP configuration files and reloads without requiring a container restart. When configuration files in the /ptp/ directory are created, modified, or deleted, the tracking daemon detects the change and restarts with the updated configuration within approximately 4-6 seconds.

This behavior is transparent to users and requires no manual intervention. Container restart counts are not affected by configuration reloads.

To confirm that a reload has occurred, check the ptp-notification pod logs:

~(keystone_admin)]$ kubectl logs -n notification <ptp-notification-pod> \
    -c ptptracking | grep -i "reload\|restart\|config"

Configure Liveness Probes for PTP Notification Pods

Helm overrides can be used to configure liveness probes for the following ptp-notification containers:

• locationservice-base

• notificationservice-base-v2

To enable the liveness probe for each container, include the following in the notification-override.yaml file:

location:
  endpoint:
    port: 8080
    liveness: True
    livenessDelaySeconds: 60
    livenessPeriodSeconds: 3
    livenessFailureThreshold: 3
    livenessTimeoutSeconds: 3
ptptrackingv2:
  endpoint:
    port: 8082
    liveness: True
    livenessDelaySeconds: 60
    livenessPeriodSeconds: 3
    livenessFailureThreshold: 3
    livenessTimeoutSeconds: 3

Apply the override values using the following commands:

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

Postrequisites

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

• PTP Notifications Overview

• https://docs.starlingx.io/api-ref/ptp-notification-armada-app/api_ptp_notifications_definition_v2.html

Change default rabbitmq credentials

PTP Notification deploys two separate rabbitmq instances with a default username and password. These values can be changed using the Helm overrides below:

Procedure

1. Remove the application if it is currently installed

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

2. Create an override file with these entries:

   cat <<EOF>> /home/sysadmin/notification-rabbitmq.yaml
   registration:
       endpoint:
           port: 5672
           user: <new username>
           pass: <new password>
   notification:
       endpoint:
           port: 5672
           user: <new username>
           pass: <new password>
   EOF
   

3. Apply the Helm overrides

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

4. Apply ptp-notification.

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