Provided by: ptpd_2.3.1-debian1-4_amd64 
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
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.
COMMAND-LINE CONFIGURATION
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.
BASIC DAEMON OPTIONS
-c --config-file PATH
Path to configuration file (see ptpd2.conf(5))
-k --check-config
Check configuration and exit - return 0 if configuration is correct.
-v --version
Print version string and exit
-h --help
Show 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 default configuration and exit (output usable as a configuration file)
-L --ignore-lock
Skip lock file checks and locking (also global:ignore_lock)
-A --auto-lock
Use preset / port mode specific lock file names - useful when running multiple
instances
-l --lockfile
Specify lock file path (also global:lock_file)
-p --print-lockfile
Print path to lock file and exit (useful for init scripts in combination with auto
lock files)
-R --lock-directory DIR
Directory to store lock files (also global:lock_directory)
-f --log-file PATH
Path to log file (also global:logfile)
-S --statistics-file PATH
Path to 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 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)
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.
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
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)).
HANDLED SIGNALS
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.
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. 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.
SUPPORTED PLATFORMS AND ARCHITECTURES
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.
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.
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.
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>
ptpd2(8) man page was written by Wojciech Owczarek for ptpd 2.3.0 in November 2013