ptpd(8)

📦 version 2.3.1-debian1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ ptpd(8) ✨ — the Precision Time Protocol daemon

okay bestie, sit down, hydrate, because today we're talking about ptpd, the Precision Time Protocol daemon, and this is the manual page for it. this is part 1 of 2 so don't go anywhere 💅

NAME 🎀

ptpd — Precision Time Protocol daemon (1588-2008)

SYNOPSIS 🌸

ptpd [ -?hH ] [ -e SETTING ] [ -kvOLAl ] [ -smMyEPanCV ] [ -c FILE ] [
-R DIR ] [ -f FILE ] [ -S FILE ] [ -d DOMAIN ] [ -u ADDRESS ] [ -r
NUMBER ] -i INTERFACE

DESCRIPTION 💖

so. PTPd is a daemon that implements the Precision Time Protocol (PTP) Version 2, exactly as defined by the IEEE 1588-2008 standard. PTP was literally invented to give LAN-connected computers very precise time coordination — like, clock-sync but make it ✨fancy✨.

👑 the daemon must run as root, no cap, because it needs to manipulate the system clock and use low port numbers. that's not a suggestion, that's the law.

PTPd is feature rich fr fr — it supports IPv4 multicast, unicast and hybrid mode (mixed) operation, plus Ethernet mode. and listen: even without hardware assistance, PTPd can achieve and maintain sub-microsecond level timing precision, and it can withstand PTP Grandmaster failovers, link failures and restarts with minimal impact to timing performance. it's giving main character energy 🦋

PTPd is lightweight, portable, and currently supports Linux, FreeBSD and Mac OS X, running on multiple CPU architectures, 32-bit and 64-bit, including x86 and ARM. slay.

COMMAND-LINE CONFIGURATION 🧚

as of version 2.3.0, the configuration file is the preferred mechanism for configuring PTPd. so the short options (-x) and long options (--xxxxx) mostly give you basic control over daemon operation, and only the very basic PTP protocol settings.

the rest of the settings (peep ptpd2.conf(5) for those 👀) can also be specified as command-line options, but they take the long --key:section="value" form. iykyk.

BASIC DAEMON OPTIONS ⭐

  • -c, --config-file PATH — path to the configuration file (check out ptpd2.conf(5))
  • -k, --check-config — check the configuration and dip out — returns 0 if the configuration is correct
  • -v, --version — print the version string and exit
  • -h, --help — show the help screen
  • -H, --long-help — show detailed help for all settings and behaviours
  • -e, --explain SETTING — show help for a single setting (section:key)
  • -O, --default-config — show the default configuration and exit (the output is usable as a configuration file, cute)
  • -L, --ignore-lock — skip lock file checks and locking (also global:ignore_lock)
  • -A, --auto-lock — use preset / port mode specific lock file names — super useful when you're running multiple instances
  • -l, --lockfile — specify the lock file path (also global:lock_file)
  • -p, --print-lockfile — print the path to the lock file and exit (handy for init scripts combined with auto lock files)
  • -R, --lock-directory DIR — directory to store lock files in (also global:lock_directory)
  • -f, --log-file PATH — path to the log file (also global:logfile)
  • -S, --statistics-file PATH — path to the statistics file (also global:statistics_file)

BASIC PTP PROTOCOL OPTIONS 🌈

  • -i, --interface DEV — REQUIRED: interface to use — eth0, etc. (also ptpengine:interface)
  • -d, --domain NUMBER — PTP domain number to become part of (also ptpengine:domain)
  • -s, --slaveonly — slave only mode (also ptpengine:preset=slaveonly)
  • -m, --masterslave — full IEEE 1588 implementation: master, slave when not best GM (also ptpengine:preset=masterslave)
  • -M, --masteronly — master only mode: passive when not best GM (also ptpengine:preset=masteronly)
  • -y, --hybrid — hybrid mode — mixed multicast and unicast operation (multicast for sync and announce, unicast for delay request and response (also ptpengine:ip_mode=hybrid)
  • -U, --unicast — unicast operation — (also ptpengine:ip_mode=unicast). for a GM, unicast destinations must be specified (-u, --unicast-destinations, ptpengine:unicast_destinations) unless you're using unicast negotiation (-g, --unicast-negotiation, ptpengine:unicast_negotiation=y) for delay request and response (also ptpengine:ip_mode=hybrid). for a slave, unicast destinations must be specified if not using unicast negotiation.
  • -g, --unicast-negotiation — enable unicast message delivery and interval negotiation using signaling messages, as used by the Telecom profile (this also enables ptpengine:ip_mode=unicast)
  • -u, --unicast-destinations ip/host, ip/host, ... — list of unicast destinations — see --unicast (also ptpengine:ip_mode=unicast + ptpengine:unicast_destinations)
  • -E, --e2e — end to end delay mechanism (also ptpengine:delay_mechanism=E2E)
  • -E, --p2p — peer to peer delay mechanism (also ptpengine:delay_mechanism=P2P)
  • -a, --delay-override — in slave state, override the delay request interval announced by the master (also ptpengine:log_delayreq_override) — the value of ptpengine:log_delayreq_interval is what gets used
  • -r, --delay-interval NUMBER — specify the delay request message interval (log 2) — (also ptpengine:log_delayreq_interval)
  • -n, --clock:no_adjust — do not adjust the clock (also clock:no_adjust)
  • -D<DD...>, --debug — debug level (also global:debug_level) — only if compiled with RUNTIME_DEBUG
  • -C, --foreground — don't run in the background (also global:foreground=Y)
  • -V, --verbose — run in the foreground, log all the messages to standard output (also global:verbose_foreground=Y)

COMPATIBILITY OPTIONS 🙈

PTPd supports the following options compatible with versions before 2.3.0:

  • -b DEV — network interface to use
  • -i NUMBER — PTP domain number
  • -g — slave only mode
  • -G — ´Master mode with NTP´ (master only mode)
  • -W — ´Master mode without NTP´ (master / slave mode)
  • -U — hybrid mode (mixed unicast + multicast operation)
  • -Y NUMBER — delay request interval (log 2)
  • -t — do not adjust the clock
💀 NOTE: the above options are deprecated and will be removed in subsequent versions. until then, their use will issue a warning. so like… don't get attached bestie.

PTPD PORT STATES 👑

  • init — INITIALIZING
  • flt — FAULTY
  • lstn_init — LISTENING (first time)
  • lstn_reset — LISTENING (subsequent reset)
  • pass — PASSIVE (not best master, not announcing)
  • uncl — UNCALIBRATED
  • slv — SLAVE
  • pmst — PRE-MASTER
  • mst — MASTER (active)
  • dsbl — DISABLED
  • ? (unk) — UNKNOWN state

📊 STATISTICS LOG FILE FORMAT 📊

Okay bestie, this is the part where your clock tells you everything about how it's doing. When the statistics log is enabled (ptpengine:log_statistics, verbose foreground mode or log file - ptpengine:statistics_file), a PTPd slave will log clock sync info every single time it receives a Sync and a Delay Response message. Obsessed.

When PTPd starts up, or when it flushes the log, a comment line gets logged — and yes, it starts with # — containing the names of all the columns. The format of this log is a series of comma-separated values (CSV), so it drops straight into statistics tools and most spreadsheet software for analysis and graphing. Slay.

Heads up: this log can get very large if you're running PTPd for long periods of time with high message rates. To cut down on the number of messages logged, use the global:statistics_log_interval setting to limit the output to one message per configured interval only. The size and max number of the statistics log can also be controlled — (see ptpd2.conf(5)).

The meaning of the columns is as follows:

  • Timestamp — Time when the message was received. This can take the form of text date / time or Unix timestamp (with fractional seconds), or both (in which case an extra field is added), depending on the global:statistics_timestamp_format setting (see ptpd2.conf(5)). When you're importing the log into plotting software: if the software can understand Unix time, it's best to set the timestamp format to unix or both, because some software will not properly deal with the fractional part of the second when converting the date and time from text. Lowkey a trap, fr fr.
  • State — Port state (see PTP PORT STATES).
  • Clock ID — Port identity of the current best master, as defined by IEEE 1588. This will be the local clock's ID if the local clock is the best master. Displayed as clock_id/port(host). Port is the PTP clock port number, not to be confused with UDP ports. The clock ID is an EUI-64 64-bit ID, usually converted from the 48-bit MAC address, by inserting 0xfffe between the lower and upper half of the MAC address. PTPd will attempt to convert the clock ID back to MAC address and look up the hostname from /etc/ethers (see ethers(5)). Populating the ethers file will help the administrator recognise the masters by familiar hostnames. Cute, right? 💅
  • One Way Delay — Current value of one-way delay (or mean path delay) in seconds, calculated by PTPd in slave state from the Delay Request - Delay Response message exchange. Note: if this value remains at zero, this usually means that no Delay Response messages are being received, likely due to a network issue. 😭
  • Offset From Master — Current value of offset from master in seconds — this is the main output of the PTP engine in slave state, which is the input of the clock servo for clock corrections. This is the value typically observed when estimating the slave performance. Main character value tbh.
  • Slave to Master — Intermediate offset value (seconds) extracted from the Delay Request - Delay Response message exchange, used for computing one-way delay. If the last value was rejected by a filter, the previous value will be shown in the log. This value will also be zero if no Delay Response messages are being received.
  • Master to Slave — Intermediate offset value (seconds) extracted from the Sync messages, used for computing the offset from master. If the last value was rejected by a filter, the previous value will be shown in the log.
  • Observed Drift — The integral accumulator of the clock control PI servo model — frequency difference between the slave clock and master clock. This value becomes stable when the clock offset has stabilised, and can be used (and is) to detect clock stability. ✨
  • Last Packet Received — This field shows what message was received last — this will be S for Sync and D for Delay Response. If a slave logs no D entries, this means it's not receiving Delay Response messages, which could be a network issue. Vibe check your network bestie.
  • One Way Delay Mean — One-way delay mean computed over the last sampling window.
  • One Way Delay Std Dev — One-way delay standard deviation computed over the last sampling window.
  • Offset From Master Mean — Offset from master mean computed over the last sampling window.
  • Offset From Master Std Dev — Offset from master standard deviation computed over the last sampling window.
  • Observed Drift Mean — Observed drift / local clock frequency adjustment mean computed over the last sampling window.
  • Observed Drift Std Dev — Observed drift / local clock frequency adjustment standard deviation computed over the last sampling window. The lower the value, the less aggressively the clock is being controlled and therefore the more stable it is. 🌸
  • raw delayMS — Raw (unfiltered) delayMS value — useful for evaluating outliers and filter performance.
  • raw delaySM — Raw (unfiltered) delaySM value — useful for evaluating outliers and filter performance.
NOTE: All the statistical measures (mean and std dev) will only be computed and displayed if PTPd was built without --disable-statistics. The duration of the sampling period is controlled with the global:statistics_update_interval setting — (see ptpd2.conf(5)).

🚨 HANDLED SIGNALS 🚨

PTPd handles the following signals, and honestly some of these are so useful:

  • SIGHUP — Reload configuration file (if used) and reopen log files.
  • SIGUSR1 — When in slave state, force clock step to current Offset from Master value. Iconic behaviour.
  • SIGUSR2 — Dump all PTP protocol counters to current log target (and clear if ptpengine:sigusr2_clears_counters set).
  • SIGINT | SIGTERM — Clean exit — close logs and other open files, clean up lock file and exit. 🫶
  • SIGKILL — Force an unclean exit. Not cute, no cleanup, just chaos. 💀

🎀 EXIT CODES 🎀

Upon exit, ptpd2 returns 0 on success — either successfully started in daemon mode, or otherwise exited cleanly. 0 is also returned when the -k (--check-config) option is used and the configuration was correct.

A non-zero exit code is returned on errors:

  • 3 is returned on lock file errors and when ptpd2 could not be started as daemon.
  • 2 is returned on memory allocation errors during startup.
  • 1 is returned for all other error conditions such as configuration errors, running ptpd2 in help mode or with no parameters, on self shutdown, network startup errors and when attempting to run ptpd2 as non-root.

So like, 1 is the "it's giving problems" code. Periodt.

💻 SUPPORTED PLATFORMS AND ARCHITECTURES 💻

PTPd is fully supported on Linux and FreeBSD, because that's what the core developers focus on. OpenBSD and NetBSD are also supported, but they get less developers' attention. So is Mac OS X, and as of PTPd 2.3.1 also OpenSolaris (11) derivatives (tested on OmniOS). Sun's / Oracle's Solaris 11 has not been tested but in essence, it should work as intended.

Solaris 10 is NOT supported because it does not provide the SO_TIMESTAMP socket option. It should theoretically be possible to use Solaris 10 using the pf facility as used by snoop, but there is currently no ongoing effort to achieve this.

Patches for QNX/Neutrino have been provided, but cannot yet officially be merged because of no availability of QNX to the developers. Some users have ported PTPd to other RTOS, but this has not been merged either. The way that these ports are just sitting there unmerged 😭

As of 2.3.1, PTPd runs entirely in software and only relies on kernel and OS APIs, so there are no hardware dependencies. Any little-endian or big-endian port of modern versions of the supported OSes should work, but only x86 and ARM are actively tested. The only dependencies close to hardware can be NIC drivers and how and if they impact software timestamping.

⏱️ HARDWARE TIMESTAMPING SUPPORT ⏱️

As of 2.3.1, PTPd still does not support hardware timestamping. This functionality will appear in the upcoming version 2.4 — potentially an interim version of 2.3.x may be delivered that will support hardware clocks and timestamping on Linux.

This is very much OS-specific and, to a large extent, hardware-specific. Linux has a PTP kernel API but not all hardware supports it. Because PTPd supports multiple OS platforms, where hardware timestamping may use different mechanisms on every platform, it has to be re-written in a modular way to allow this without unnecessarily increasing code complexity, which already is a problem. The way that complexity is already a problem 💀

🐛 BUGS 🐛

As of ptpd 2.3.1, the (Open)Solaris (11) OS family is supported, but libpcap functionality is currently broken — IPv4/pcap and Ethernet transports cannot be used on those systems. PTPd will compile and run, but will not receive any data. Not it just vibing there receiving absolutely nothing 🙈

Please report any bugs using the bug tracker on the SourceForge page:

http://sourceforge.net/projects/ptpd/

👀 SEE ALSO 👀

ptpd2.conf(5)

👑 AUTHORS 👑

  • Gael Mace <gael_mace@users.sourceforge.net>
  • Alexandre Van Kempen
  • Steven Kreuzer <skreuzer@freebsd.org>
  • George Neville-Neil <gnn@freebsd.org>
  • Wojciech Owczarek <wojciech@owczarek.co.uk>

The ptpd2(8) man page was written by Wojciech Owczarek for ptpd 2.3.0 in November 2013.

And that's a wrap bestie ✨ this whole thing is version 2.3.1, dated June, 2015, and it lives at ptpd(8) — go forth and sync, you absolute queen 🎀💖

📦 where this page comes from