ptp4l

ptp4l is linuxptp's daemon. With nothing better configured it decides, by the Best Master Clock Algorithm (BMCA), that it is the best clock present and prints assuming the grand master role; run with -s it is slave-only and locks onto the grandmaster, moving LISTENING → UNCALIBRATED → slave. It then reports one line per exchange — master offset <ns> s0 freq <ppb> path delay <ns> — the offset and path delay in nanoseconds. The servo state s0 means measuring only; a clock being disciplined climbs s0 → s1 → s2. PTP timestamps go closest to the wire the hardware allows: a PTP NIC stamps in hardware (-H), otherwise the kernel stamps in software (-S), which is real PTP but coarser. Event messages (Sync, Delay_Req) ride UDP 319, general ones (Follow_Up, Delay_Resp, Announce) UDP 320, by default to the multicast group 224.0.1.129.

ptp4l command usage

ptp4l [-f FILE] -i CARD (-4|-6|-2) (-S|-H) [-s] [-m] [--clock_servo nullf] [--summary_interval N]

Options

-f FILE

read settings from a file ([global] lines such as time_stamping software, logSyncInterval -3)

-i CARD

the network card to run PTP on

-4

carry PTP over UDP/IPv4 (−6 for IPv6, −2 for raw Ethernet)

-S

software timestamping, for a card with no PTP hardware (−H uses the hardware clock)

-s

slave only: lock onto the grandmaster, never become it

-m

print messages to the screen

--clock_servo nullf

measure the offset but steer no clock

--summary_interval N

report every sample (−10) rather than periodic averages

ptp4l examples

ptp4l -i eth0 -4 -S -m

Runs PTP on a card over UDP/IPv4 with software timestamping, becoming the grandmaster if no better clock is present.

ptp4l -i eth0 -4 -S -s -m

Runs PTP as a slave only, locking onto the grandmaster and printing the offset each exchange.

ptp4l -i eth0 -4 -S -s -m --clock_servo nullf --summary_interval -10

Measures the offset and path delay every exchange without steering any clock.

ptp4l -f /etc/linuxptp/ptp4l.conf -i eth0 -s -m

The same slave with its settings in a file, as the ptp-and-nts lab runs it.

Reading the output

$ ptp4l -i eth0 -4 -S -s -m
ptp4l[12.3]: selected best master clock 001122.fffe.334455
ptp4l[12.4]: port 1 (eth0): LISTENING to UNCALIBRATED on RS_SLAVE
ptp4l[13.1]: master offset        -31 s0 freq      +0 path delay      9240

• s0 is the servo state: measuring only. A clock being disciplined climbs s0 → s1 → s2 as it locks.
• master offset and path delay are in nanoseconds; with software timestamping the delay is microseconds, not the tens of nanoseconds a PTP NIC gives.
• The grandmaster is chosen by the Best Master Clock Algorithm; with nothing better a device prints assuming the grand master role.

Pitfalls

• A container has no PTP hardware clock: use -S. It also may not set the shared host clock, so with the null servo the state stays s0 — it measures, it does not steer.
• Event messages ride UDP 319 and general ones UDP 320: a firewall between master and slave must pass both.

Run it on real machines