PTPd: Time synchronization for (realtime) Linux systems with Tux

PTPd: Time synchronization for (realtime) Linux systems with Tux

Did you ever wonder how you can configure PTPd services on your Linux system?

Hey, my name is "Tux" and this tutorial will show you how you can get PTPd up and running to have a reliable time synchronization between all involved ethernet hosts.

First thoughts

Alternatively to the time synchronization tool NTP, which is not useful in a realtime environment, PTP was designed. Unlike NTP, PTP is based on Multicast technology (Master/Slave) while NTP is based on Client-Server technology. PTP was designed for synchronizing system time between a PTP master and one or multiple PTP slaves as precise as possible. There do exists two different types of PTP applications: hard- or software driven applications or even both in a single application. Hardware driven PTP applications in general are a lot more reliable than software driven PTP applications, especially when used in realtime systems. The disadvantage of hardware driven PTP is the requirement for physical hardware that supports PTP (dedicated PTP clock chip onto master NIC and slaves NIC(s) and optional switches/routers in between). When there is no need for hardware driven PTP (for example in test environments) PTPd can be used.
PTPd is a software driven only PTP application and therefore it cannot get controlled by dedicated hardware.
Advantage: No financial issues but on cost of precision.
Beware: PTPd is very limited on realtime usability and therefore it should only be used after checking all requirements on the realtime system! For critical realtime applications hardware based PTP should always be the first choice.

Example of usage

Start of tutorial

Platform independent variants of installation

Ubuntu 14.04 with current version of PTPd from GitHub.com

Download source code files from here. Copy source code file into the following directory (replace the following placeholders <x> with corresponding version number according the downloaded file):

$ cp ptpd-<x>.<x>.<x>.tar.gz /opt

Navigate into folder /opt:

$ cd /opt

Extract the ptpd-<x>.<x>.<x>.tar.gz file here:

$ tar xvzf ptpd-<x>.<x>.<x>.tar.gz

Delete the ptpd-<x>.<x>.<x>.tar.gz file:

$ rm -rf ptpd-<x>.<x>.<x>.tar.gz

Rename the ptpd-<x>.<x>.<x> folder into ptpd:

$ mv "/opt/ptpd-<x>.<x>.<x>" /opt/ptpd

Navigate into folder /opt/ptpd:

$ cd /opt/ptpd

Now execute the following commands successively:

$ ./configure
$ make
$ make install

Next step is configuring autostart of PTPd service on operation system's start.
Create a file <myStartScript>.sh inside the /usr/local/bin/ folder…

$ vi /usr/local/bin/<myStartScript>.sh

…and add the following content (Beware: sleep is required because of autostart failure if the corresponding networkinterface's drivers are not being loaded fast enough on operating system's start.),…

sleep 30

Variant Master

$ sudo /opt/ptpd/src/ptpd2 -M -i <myNetworkInterface>

Variant Slave

$ sudo /opt/ptpd/src/ptpd2 -s -i <myNetworkInterface>

…save the file and quit the editor.
Now make the file executable:

$ chmod +x /usr/local/bin/<myStartScript>.sh

Now edit the file:

$ vi /etc/rc.local

Before the already existing entry exit 0 add the following content:

/usr/local/bin/<meinStartSkript>.sh
exit 0

Optional

If there are additional processes required being started via rc-.local file it is required to separate those processes by an &-symbol. Example:

/usr/local/bin/<myFirstStartScript>.sh &
/usr/local/bin/<mySecondStartScript>.sh
exit 0

Now save the file and quit the editor.
Reboot the system and check if ptpd2 service is running:

$ ps -A | grep ptpd2

Beware: When no message appears the service is not running!

Ubuntu 14.04 and 16.04 with PTPd from default repository

Installation

pdpdpackage installation via default repository:

$ apt-get install ptpd

Edit the following file…

$ vi /etc/default/ptpd

…and change the following default entries according to the following instructions (Beware: case sensitive!)
START_DAEMON = no → change to → START_DAEMON = yes

Variant Ubuntu 16.04 Master

PTPD_OPTS = "" → change to → PTPD_OPTS = "-M -i <myNetworkInterface>"

Variant Ubuntu 14.04 Master

PTPD_OPTS = "" → change to → PTPD_OPTS = "-G -h -b <myNetworkInterface>"

Variant Ubuntu 16.04 Slave

PTPD_OPTS = "" → change to → PTPD_OPTS = "-s -i <myNetworkInterface>"

Variant Ubuntu 14.04 Slave

PTPD_OPTS = "" → change to → PTPD_OPTS = "-g -h -b <myNetworkInterface>"

Save the file and quit the editor.
Next step is configuring autostart of PTPd service on operation system's start.
Create a file <myStartScript>.sh inside the /usr/local/bin/ folder…

$ vi /usr/local/bin/<myStartScript>.sh

sleep 30

Variant Ubuntu 16.04 Master

$ sudo ptpd -M -i <myNetworkInterface>

Variant Ubuntu 14.04 Master

$ sudo ptpd -G -h -b <myNetworkInterface>

Variant Ubuntu 16.04 Slave

$ sudo ptpd -s -i <myNetworkInterface>

Variant Ubuntu 14.04 Slave

$ sudo ptpd -g -h -b <myNetworkInterface>

…save the file and quit the editor.
Now make the file executable:

$ chmod +x /usr/local/bin/<myStartScript>.sh

Now edit the file:

$ vi /etc/rc.local

Before the already existing entry exit 0 add the following content:

/usr/local/bin/<myStartScript>.sh
exit 0

Optional

If there are additional processes required being started via rc-.local file it is required to separate processes by an &-symbol. Example:

/usr/local/bin/<myFirstStartScript>.sh &
/usr/local/bin/<mySecondStartScript>.sh
exit 0

Now save the file and quit the editor.
Reboot the system and check if ptpd service is running:

$ service ptpd status

Variant Ubuntu 16.04

As an output message there is a green «light» being generated (there may be a delay of about 10 seconds).

Variante Ubuntu 14.04

As an output message «ptpd is running» is showing up (there may be a delay of about 10 seconds).

Troubleshooting and additional information on PTP and PTPd

Whether physical NICs do support hardware driven PTP can be checked by executing the following command:
```
$ ethtool -T <myNetworkInterface>
```
Optional: If using a WiFi module as a network interface and it is required to check whether the connection from Linux PC to access point does support Fast Roaming (802.11 r) (helpful for realizing uninterruptedly time synchronozation) execute the following commands:
```
$ wpa_cli roam <myAccessPointMACaddress>
$ wpa_cli scan
$ wpa_cli scan_results
```
If for example WPA2-PSK+FT is being showed then Fast Roaming (FT / Fast Transition) is supported. Beware: When 802.11r is activated on access point it is strongly recommended to activate 802.11k too (please have a look into the internet for further information ). On top on that, if FT is required, access point and NIC drivers for Linux OS must support FT technology.
A disconnecton from master to slave and other way around does not affect the PTPd runtime service. To be more clear: If PTP master is being rebooted the time synchronization will continue after reboot automatically as soon as the PTP master has boot up and it's PTPd service has started automatically. There is no need for manual restart of PTP slave's service. The same for the other way around: When a slave reboots the PTP master's service has not to be restarted.
For PTPd to operate, it must be run on at least two computers connected through an Ethernet hub or switch or a direct connection. It is possible to have PTPd coordinate two (and only two!) computers through a routed connection by running PTPd on each computer with the -u argument followed by the IP address of the target computer.
PTP can be combined with other time synchronization variants. Example: A PTP master can get it's local time periodically by NTP (layer 3) time server and then distribute it's time via PTP to it's slaves.
PTP is using Multicast by default but can also be configured for Unicast operation.