ptpd - Precision Time Protocol daemon (1588-2008)
ptpd [ -?hH ] [ -e SETTING ]
[ -kvOLAl ] [ -smMyEPanCV ] [ -c FILE ]
[ -R DIR ] [ -f FILE ] [ -S
FILE ] [ -d DOMAIN ] [ -u
ADDRESS ] [ -r NUMBER ] -i
INTERFACE
PTPd is a daemon that implements the Precision Time Protocol (PTP)
Version 2 as defined by the IEEE 1588-2008 standard. PTP was developed to
provide very precise time coordination of LAN connected computers. The
daemon must run as root in order to be able to manipluate the system
clock and use low port numbers. PTPd is feature rich, supports IPv4
multicast, unicast and hybrid mode (mixed) operation, as well as Ethernet
mode. Even without hardware assistance, PTPd is able to achieve and maintain
sub-microsecond level timing precision and is able to withstand PTP
Grandmaster failovers, link failures and restarts with minimal impact to
timing performance. PTPd is lightweight, portable and currently supports
Linux, FreeBSD and Mac OS X and runs on multiple CPU architectures, 32-bit
and 64-bit, including x86 and ARM.
As of version 2.3.0, configuration file is the preferred mechanism
for configuring PTPd, therefore the options available as short (-x)
and long options (--xxxxx) mostly provide basic control over the
daemon operation, and only provide the very basic PTP protocol settings. The
rest of the settings (see ptpd2.conf(5)) can also be specified as
command-line options, but they take the long
--key:section="value" form.
- -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 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 usin signaling
messages, as used by the Telecom profile (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 delay request interval announced by master (also
ptpengine:log_delayreq_override) - the value of
ptpengine:log_delayreq_interval is used
- -r --delay-interval
NUMBER
- Specify 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 background (also global:foreground=Y)
- -V --verbose
- Run in foreground, log all the messages to standard output (also
global:verbose_foreground=Y)
- 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
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
information upon the receipt of every Sync and Delay Response message. When
PTPd starts up or flushes the log, a comment line (starting with #) will be
logged, containing the names of all columns. The format of this log is a
series of comma-separated values (CSV) and can be easily imported into
statistics tools and most spreadsheet software packages for analysis and
graphing. This log can get very large when running PTPd for longer periods
of time and with high message rates, therefore to reduce the number of
messages logged, the global:statistics_log_interval setting can be
used, to limit the log output to one message per configured interval only.
The size and maximum number of the statistics log can also be controlled -
(see ptpd2.conf(5)).
- The meaning of the columns is as
follows:
- Timestamp
- Time when message received. This can take the form of text date / time or
Unix timestamp (with fractional seconds), or both (in which case an exra
field is added), depending on the
global:statistics_timestamp_format setting (see
ptpd2.conf(5)). When importing the log into plotting software, if
the software can understand Unix time, it is best to set the timestamp
format to unix or both, as some software will not properly deal with the
fractional part of the second when converting the date and time from
text.
- 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.
- 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.
- 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.
- 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)).
- PTPd handles the
following signals:
- SIGHUP
- Reload configuration file (if used) and reopen log files
- SIGUSR1
- When in slave state, force clock step to current Offset from Master
value
- 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.
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.
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 - 1 is returned.
PTPd is fully supported on Linux and FreeBSD as this is what the
core developers focus on. OpenBSD and NetBSD are also supported, but get
less developers' attention. So is Max 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.
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.
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.
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.
Please report any bugs using the bug tracker on the SourceForge
page: http://sourceforge.net/projects/ptpd/
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>
ptpd2(8) man page was written by Wojciech Owczarek for ptpd
2.3.0 in November 2013