Chrony with hardware timestamping

Introduction
On a local-area network, Network Time Protocol can achieve time-synchronisation accuracy of in the order of 1 millisecond. While more than enough if you get your reference time from another, remote NTP server, using it in conjunction with a more precise time source such as a Precision Time Protocol (PTP) master or a satellite-navigation (e.g. GPS) clock results in a loss of several orders of magnitude of accuracy. One alternative would of course be to use such a time source directly but that is not always possible, for instance due to the cost and complexity of equipping servers with individual GNSS receivers or due to older network infrastructure not handling PTP traffic correctly. Under such circumstances, recent versions of Chrony offer an additional solution in the form of using hardware time sources available on many modern network-interface cards to improve accuracy of NTP itself.

Chrony with hardware timestamping
This howto guide uses an example home network that has seven hosts including two that are internet facing servers. All but one (thufir) have sufficiently modern ethernet devices that can support a PTP hardware clock interface.

Host List

 * parry - An internet facing server based on an AMD Kaveri class APU (2014 vintage whose NIC on the motherboard supports PTP)
 * topshelf - An internet facing server recently refreshed with an AMD Zen2 class motherboard
 * thufir - A local host based on AMD Bulldozer class from around 2012 whose motherboard NIC is too old for PTP
 * mater - A local AMD Zen1 class host
 * mike - A local AMD Zen1 class host
 * figo - A local AMD Zen2 class host
 * tube - A local AMD Kaveri class host

Kernel support
Linux PTP version 2 support was released in 2008, and thus all current Gentoo source kernels (4.x and later) can be built with PTP clock support (CONFIG_PTP_1588_CLOCK). If you use VMs and want your virtual machines to take advantage of PTP you can also set CONFIG_PTP_1588_KVM. Also set up your network PHY device support for your line of adapters if you haven't already done so.

Verifying the NIC PTP device clock
Emerge ethtool if you haven't already done so. It can show you the PTP capabilities and associated ptp device for the NIC clock if it exists. For topshelf, the inward facing nic is eth2, and we see that clock 2 (/dev/ptp2) is associated with it.

This is what you would see instead if your device doesn't have PTP support such as the eth0 device on thufir.

Chrony config on the internet facing servers
topshelf and parry have multiple nic adapters and are directly connected to the internet with shorewall keeping out the unwashed masses. Their chrony config will differ from the other hosts because they will talk to upstream ntp.org and gentoo.org ntp servers at a higher stratum. The local home network is the private 192.168.1.0 class C subnet.

The first part of the file uses the public pool of ntp.org and gentoo ntp servers for our upstream sources. The iburst option allows topshelf and parry to have an initially larger amount of ntp transactions pack and forth with the upstream servers until the accurate time gets settled upon. However that may not necessarily happen since the initstepslew directive will take effect first. That directive will quickly slew the clock into shape upon startup if the time is off by 30 seconds or more.

The prefer option on these two designates them to be treated with higher priority amongst all of the peers. Thus either parry or topshelf will show up as the reference clock when you issue a tracking command to chronyc.

The xleave option gets used everywhere there is a peer that has PTP support. That will cause chrony to use the NIC clock to hardware timestamp the ethernet traffic it uses with the other host to update the clock. This helps to reduce jitter and improve accuracy.

The refclock directive has the host use the NIC clock as an additional reference source. As noted previously, topshelf uses /dev/ptp2 since that is the NIC clock associated with its inward facing eth2 port. It will show up as the PHC0 source in the first line of a chronyc sources command.

The hwtimestamp * directive tells chrony to enable hardware timestamping on any of the NICs it may use that support PTP.

Chrony config on a local peer
For the local peers, we have commented out the ntp.org and gentoo.org server pools since they will be relying on topshelf and parry. For thufir, we have also removed all the xleave options and commented out the refclock directive since it lacks PTP support on its NIC.

chrony with hardware timestamping in action
This is the output of a chronyc sources and tracking report on tube after the newly configured chrony has been pushed out to all of the hosts and has been running for a while. topshelf shows with "=*" since it is the reference clock. parry shows "=+" since it is regarded highly enough to be considered in the clock adjustment combining algorithm. The other peers show as "=-" since they are not currently being regarded as sources for adjustments. The PHC0 shows as "=X" since it is a hardware reference associated with the /dev/ptp0 clock on the eth0 NIC interface.

{{RootCmd|chronyc|output= chrony version 3.3 Copyright (C) 1997-2003, 2007, 2009-2018 Richard P. Curnow and others chrony comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it under certain conditions. See the GNU General Public License version 2 for details.

chronyc> sources 210 Number of sources = 8 MS Name/IP address        Stratum Poll Reach LastRx Last sample

=
================================================================== =+ parry.example.com            3   0   365     3    -48ns[  -48ns] +/-   15ms =* topshelf.example.com.>       2   0   377     7   -390ns[ -438ns] +/-   15ms =- thufir.example.com           3   0   165    10    +49us[  +49us] +/-   15ms =- mater.example.com            3   0   377     0  -4842ns[-4842ns] +/-   15ms =- figo.example.com             3   0   375     3   -459ns[ -459ns] +/-   15ms =- mike.example.com             3   0   157     2  +7333ns[+7333ns] +/-   14ms =? tube.example.com             0   0     0     -     +0ns[   +0ns] +/-    0ns chronyc> tracking Reference ID   : C0A80B21 (topshelf.example.com.1.168.192.in-addr.arpa) Stratum        : 3 Ref time (UTC) : Thu Mar 21 20:57:24 2019 System time    : 0.000000522 seconds fast of NTP time Last offset    : +0.000000025 seconds RMS offset     : 0.000001429 seconds Frequency      : 0.321 ppm fast Residual freq  : -0.000 ppm Skew           : 0.007 ppm Root delay     : 0.025426105 seconds Root dispersion : 0.002194689 seconds Update interval : 5.4 seconds Leap status    : Normal chronyc> }}
 * 1) x PHC0                         0   4   377    17   +37.4s[ +37.4s] +/-  901ns