Quick Start Guide

  • Published on Oct 30, 2024
  • 4 minute(s) read
  • Migration Team

System requirements

PTP4L is a dependency of several Telos Alliance solutions, and as such, it is included in the hardware specifications for those solutions. This container must be deployed on the same container host as the product for which it is providing synchronization.  As with all Telos Alliance containers, PTP4L works on any Linux-based Open Container Initiative compliant runtime.

Required

Item

Description

✔️

OCI Runtime

Container Runtime

✔️

sudo privileges

Ability to run commands as root using sudo

Determine PTP timestamping method

In order to set up PTP4L, the time stamping method being used must be determined. There are two modes for PTP timestamping: hardware or software. Hardware timestamping is highly preferred, but software timestamping is possible as well (with some caveats).

Testing a network interfaces timestamping method

  • Install ethtool by executing this command: sudo apt install ethtool

If ethtool is already installed a message stating this will be printed in the terminal. In this case the steps to install ethtool can be skipped.

  • When prompted to enter your password, type this in and press Enter

  • After successfully entering the password, one last confirmation prompt will appear. Type y to continue.

  • Type the command ip addr

  • All of the system's enabled network interfaces will now be listed on screen. Identify the interface you have connected to your AoIP network and note down its name.

Ethernet interfaces are often listed in the format "enoX" or "enpXsY", where X and Y are positive integers

  • Execute the command ethtool -T <iface>, where <iface> is the name of your AoIP network interface

The prior command will query the system for the capabilities of the AoIP network interface. Some text will print to your screen. Notice the lines that appear under the "Capabilities:" header.

To support hardware timestamping, the following lines must all appear:

SOF_TIMESTAMPING_RAW_HARDWARE

SOF_TIMESTAMPING_TX_HARDWARE

SOF_TIMESTAMPING_RX_HARDWARE

If the above lines appear, you will be using hardware timestamping; note the PTP Hardware Clock value, as it may be needed later. If the above lines do not appear, determine if only these lines are present:

SOF_TIMESTAMPING_SOFTWARE

SOF_TIMESTAMPING_TX_SOFTWARE

SOF_TIMESTAMPING_RX_SOFTWARE

If only the above lines appear, this means you will be using software timestamping.

Beware timestamping if your PTP grandmaster is an xNode or other grandmaster using arbitrary time (ie. not using accurate, absolute time); note that your Docker host system time will be reset to whatever arbitrary time your PTP grandmaster is using. Often this is a time in 1970. This will not occur if hardware timestamping is used.

Installation Methods

Telos Guide Script

Telos offers a guided script that is ideal for new container users or machines which will be dedicated to running Telos Alliance products. If you are integrating PTP4L with an existing container-based system, we recommend following the manual instructions instead.

Installing PTP4L with the Telos Alliance Script

We assume that you are using a compliant platform and that you have an understanding of Linux and containers.

Prerequisites

  • Ubuntu 20.04 LTS or 18.04 LTS

  • Knowledge of whether the system is using macvlan or host for Docker networking

  • The Telos setup script has already been run

  • sudo privileges

If the Telos setup script has not been run, please click here.

Installation PTP4L host networking

  • At the prompt install a Telos product from template: , press y

  • Look for the option ptp4l, enter the index associated with it, and press Enter

  • A prompt will appear to enter a unique name for this instance. Telos recommends "ptp4l"

  • Next, a prompt to set the repository variable will appear. Leave this blank to use the default.

  • Following the repository, a tag may be set by the user. Again, leaving this blank will use the default.

  • The script will now prompt for any specific PTP Arguments. Based on the result of your timestamping test, the information for this field varies.

    • Hardware timestamping: Enter -i <iface> -H where <iface> is the name of the AoIP interface, then press Enter

    • Software timestamping:  Enter -i <iface> where <iface> is the name of the AoIP interface, then press Enter

  • After pressing enter, the setup script will instantiate a PTP4L container on your system. When it is done, a message will print stating creating PTP4L ... done

Installation PTP4L with macvlan networking

  • At the prompt install a Telos product from template: , press y

  • Look for the option ptp4l-macvlan, enter the index associated with it, and press Enter

  • A prompt will appear to enter a unique name for this instance. Telos recommends "ptp4l"

  • Next, a prompt to set the repository variable will appear. Leave this blank to use the default.

  • Following the repository, a tag may be set by the user. Again, leaving this blank will use the default.

  • The script will now prompt for any specific PTP Arguments. Based on the result of your timestamping test, the information for this field varies.

    • Hardware timestamping: Enter -i <iface> -H where <iface> is the name of the AoIP interface, then press Enter

    • Software timestamping: Leave this field blank, and press Enter to continue

  • Set the IP Address that should be assigned to the PTP4L container

  • After pressing enter, the setup script will instantiate a PTP4L container on your system. When it is done, a message will print stating creating PTP4L ... done

When adding PTP4L to a larger container deployment, the best practice is to utilize the existing tools that are administering the system. This document assumes the reader has experience using containers and can read a Docker Compose file. This document also only covers the unique variables needed to make an PTP4L run.

PTP4L has a default set of arguments. If you need to edit these for your system, they can be changed by using the command property in the Docker Compose template below. The syntax for these command follows the standard for PTP4L, which can be found here.

PTP4L can be deployed using any solution that can control Docker containers. This document contains examples of Docker Compose. Example 1 shows how to use PTP4L when using host networking, while Example 2 demonstrates how to use a PTP4L with maclvan.  Both examples will require some variables to be adjusted before using them.

Related articles