.\" -*- nroff -*"
.TH ptpd 8 "June, 2015" "version 2.3.1" "Precision Time Protocol daemon"
.SH NAME
ptpd \- Precision Time Protocol daemon (1588-2008)
.SH SYNOPSIS
.B ptpd
\fB[ -?hH ]\fR
\fB[ -e \fISETTING\fB ]\fR
\fB[ -kvOLAl ]\fR
\fB[ -smMyEPanCV ]\fR
\fB[ -c \fIFILE\fB ]\fR
\fB[ -R \fIDIR\fB ]\fR
\fB[ -f \fIFILE\fB ]\fR
\fB[ -S \fIFILE\fB ]\fR
\fB[ -d \fIDOMAIN\fB ]\fR
\fB[ -u \fIADDRESS\fB ]\fR
\fB[ -r \fINUMBER\fB ]\fR
\fB-i \fIINTERFACE\fB\fR
.SH 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
.B 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.
.SH COMMAND-LINE CONFIGURATION
As of version 2.3.0, configuration file is the preferred mechanism for configuring PTPd, therefore
the options available as short (\fI-x\fR) and long options (\fI--xxxxx\fR) mostly provide basic control
over the daemon operation, and only provide the very basic PTP protocol settings. The rest of the settings (see \fBptpd2.conf(5)\fR)
can also be specified as command-line options, but they take the long \fI--key:section="value"\fR form.

.SH BASIC DAEMON OPTIONS
.TP
\fB-c --config-file \fIPATH\fR
Path to configuration file (see \fBptpd2.conf(5)\fR)
.TP
\fB-k --check-config\fR
Check configuration and exit - return 0 if configuration is correct.
.TP
\fB-v --version\fR
Print version string and exit
.TP
\fB-h --help\fR
Show help screen
.TP
\fB-H --long-help\fR
Show detailed help for all settings and behaviours
.TP
\fB-e --explain \fISETTING\fR
Show help for a single setting (\fIsection:key\fR)
.TP
\fB-O --default-config\fR
Show default configuration and exit (output usable as a configuration file)
.TP
\fB-L --ignore-lock\fR
Skip lock file checks and locking (also \fIglobal:ignore_lock\fR)
.TP
\fB-A --auto-lock\fR
Use preset / port mode specific lock file names - useful when running multiple instances
.TP
\fB-l --lockfile\fR
Specify lock file path (also \fIglobal:lock_file\fR)
.TP
\fB-p --print-lockfile\fR
Print path to lock file and exit (useful for init scripts in combination with auto lock files)
.TP
\fB-R --lock-directory \fIDIR\fR
Directory to store lock files (also \fIglobal:lock_directory\fR)
.TP
\fB-f --log-file \fIPATH\fR
Path to log file (also \fIglobal:logfile\fR)
.TP
\fB-S --statistics-file \fIPATH\fR
Path to statistics file (also \fIglobal:statistics_file\fR)
.SH BASIC PTP PROTOCOL OPTIONS
.TP
\fB-i --interface \fIDEV\fR
\fIREQUIRED:\fRInterface to use - eth0, etc (also \fIptpengine:interface\fR)
.TP
\fB-d --domain \fINUMBER\fR
PTP domain number to become part of (also \fIptpengine:domain\fR)
.TP
\fB-s --slaveonly\fR
Slave only mode (also \fIptpengine:preset=slaveonly\fR)
.TP
\fB-m --masterslave\fR
Full IEEE 1588 implementation: master, slave when not best GM (also \fIptpengine:preset=masterslave\fR)
.TP
\fB-M --masteronly\fR
Master only mode: passive when not best GM (also \fIptpengine:preset=masteronly\fR)
.TP
\fB-y --hybrid\fR
Hybrid mode - mixed multicast and unicast operation (multicast for sync and announce, unicast
for delay request and response (also \fIptpengine:ip_mode=hybrid\fR)
.TP
\fB-U --unicast\fR
Unicast operation - (\fIalso ptpengine:ip_mode=unicast\fR). For a GM, unicast destinations
must be specified (\fI-u, --unicast-destinations, ptpengine:unicast_destinations\fR) unless
using unicast negotiation (\fI-g, --unicast-negotiation, ptpengine:unicast_negotiation=y\fR)
for delay request and response (also \fIptpengine:ip_mode=hybrid\fR). For a slave, unicast
destinations must be specified if not using unicast negotiation.
.TP
\fB-g --unicast-negotiation\fR
Enable unicast message delivery and interval negotiation usin signaling messages, as used
by the Telecom profile (also enables \fIptpengine:ip_mode=unicast\fR)
.TP
\fB-u --unicast-destinations \fIip/host, ip/host, ...\fR
List of unicast destinations - see \fI--unicast\fR
(also \fIptpengine:ip_mode=unicast\fR + \fIptpengine:unicast_destinations\fR)
\fB-E --e2e\fR
End to end delay mechanism (also \fIptpengine:delay_mechanism=E2E\fR)
.TP
\fB-E --p2p\fR
Peer to peer delay mechanism (also \fIptpengine:delay_mechanism=P2P\fR)
.TP
\fB-a --delay-override\fR
In slave state, override delay request interval announced by master (also \fIptpengine:log_delayreq_override\fR) - the value
of \fIptpengine:log_delayreq_interval\fR is used
.TP
\fB-r --delay-interval \fINUMBER\fR
Specify delay request message interval (log 2) - (also \fIptpengine:log_delayreq_interval\fR)
.TP
\fB-n --clock:no_adjust\fR
Do not adjust the clock (also \fIclock:no_adjust\fR)
.TP
\fB-D<DD...> --debug\fR
Debug level (also \fIglobal:debug_level\fR) - only if compiled with RUNTIME_DEBUG
.TP
\fB-C --foreground\fR
Don't run in background (also \fIglobal:foreground=Y\fR)
.TP
\fB-V --verbose\fR
Run in foreground, log all the messages to standard output (also \fIglobal:verbose_foreground=Y\fR)

.SH COMPATIBILITY OPTIONS

.TP
PTPd supports the following options compatible with versions before 2.3.0:
.RS 8
.TP 8
\fB-b \fIDEV\fR
Network interface to use
.TP 8
\fB-i \fINUMBER\fR
PTP domain number
.TP 8
\fB-g\fR
Slave only mode
.TP 8
\fB-G\fR
\'Master mode with NTP\' (master only mode)
.TP 8
\fB-W\fR
\'Master mode without NTP\' (master / slave mode)
.TP 8
\fB-U\fR
Hybrid mode (mixed unicast + multicast operation)
.TP 8
\fB-Y \fINUMBER\fR
Delay request interval (log 2)
.TP 8
\fB-t\fR
Do not adjust the clock
.RE
.TP
\fBNOTE:\fR the above options are deprecated and will be removed in subsequent versions. Until then, their use will issue a warning.


.SH PTPD PORT STATES

.RS 8
.TP
\fIinit\fR
INITIALIZING
.TP
\fIflt\fR
FAULTY
.TP
\fIlstn_init\fR
LISTENING (first time)
.TP
\fIlstn_reset\fR
LISTENING (subsequent reset)
.TP
\fIpass\fR
PASSIVE (not best master, not announcing)
.TP
\fIuncl\fR
UNCALIBRATED
.TP
\fIslv\fR
SLAVE
.TP
\fIpmst\fR
PRE-MASTER
.TP
\fImst\fR
MASTER (active)
.TP
\fIdsbl\fR
DISABLED
.TP
\fI? (unk)\fR
UNKNOWN state
.RE

.SH STATISTICS LOG FILE FORMAT

When the statistics log is enabled (\fIptpengine:log_statistics\fR, verbose foreground mode or log file - \fIptpengine:statistics_file\fR),
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 \fIglobal:statistics_log_interval\fR 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 \fBptpd2.conf(5)\fR).
.TP
The meaning of the columns is as follows:
.RS 8
.TP 8
\fBTimestamp\fR
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 \fIglobal:statistics_timestamp_format\fR setting (see \fBptpd2.conf(5)\fR).
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.
.TP 8
\fBState\fR
Port state (see \fBPTP PORT STATES\fR).
.TP 8
\fBClock ID\fR
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 \fIclock_id/port(host)\fR 
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 \fI/etc/ethers\fR (see \fBethers(5)\fR). Populating the ethers file will help the
administrator recognise the masters by familiar hostnames.
.TP 8
\fBOne Way Delay\fR
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. \fINote:\fR if this value remains at zero,
this usually means that no Delay Response messages are being received, likely due to a network issue.
.TP 8
\fBOffset From Master\fR
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.
.TP 8
\fBSlave to Master\fR
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.
.TP 8
\fBMaster to Slave\fR
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.
.TP 8
\fBObserved Drift\fR
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.
.TP 8
\fBLast Packet Received\fR
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.
.TP 8
\fBOne Way Delay Mean\fR
One-way delay mean computed over the last sampling window.
.TP 8
\fBOne Way Delay Std Dev\fR
One-way delay standard deviation computed over the last sampling window.
.TP 8
\fBOffset From Master Mean\fR
Offset from master mean computed over the last sampling window.
.TP 8
\fBOffset From Master Std Dev\fR
Offset from master standard deviation computed over the last sampling window.
.TP 8
\fBObserved Drift Mean\fR
Observed drift / local clock frequency adjustment mean computed over the last sampling window.
.TP 8
\fBObserved Drift Std Dev\fR
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.
.TP 8
\fBraw delayMS\fR
Raw (unfiltered) delayMS value - useful for evaluating outliers and filter performance.
.TP 8
\fBraw delaySM\fR
Raw (unfiltered) delaySM value - useful for evaluating outliers and filter performance.
.RE

\fBNOTE:\fR 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
\fIglobal:statistics_update_interval\fR setting - (see \fBptpd2.conf(5)\fR).

.SH HANDLED SIGNALS
.TP
\fBPTPd handles the following signals:\fR
.RS 8
.TP 8
\fISIGHUP\fR
Reload configuration file (if used) and reopen log files
.TP 8
\fISIGUSR1\fR
When in slave state, force clock step to current Offset from Master value
.TP 8
\fISIGUSR2\fR
Dump all PTP protocol counters to current log target
(and clear if \fIptpengine:sigusr2_clears_counters\fR set)
.TP 8
\fISIGINT|SIGTERM\fR
Clean exit - close logs and other open files, clean up lock file and exit.
.TP 8
\fISIGKILL\fR
Force an unclean exit.
.RE
.SH EXIT CODES
Upon exit, ptpd2 returns \fB0\fR on success - either successfully started in daemon mode, or otherwise exited cleanly.
\fB0\fR is  also returned when the \fI-k\fR (\fI--check-config\fR)
option is used and the configuration was correct. A non-zero exit code is returned on errors.
\fB3\fR is returned on lock file errors and when ptpd2 could not be started as daemon.
\fB2\fR 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 -  \fB1\fR is returned.

.SH 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 \fIpf\fR facility as used by \fIsnoop\fR,
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.

.SH 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. 

.SH 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/

.SH SEE ALSO
ptpd2.conf(5)
.SH AUTHORS
.P
Gael Mace <gael_mace@users.sourceforge.net>
.P
Alexandre Van Kempen
.P
Steven Kreuzer <skreuzer@freebsd.org> 
.P
George Neville-Neil <gnn@freebsd.org>
.P
Wojciech Owczarek <wojciech@owczarek.co.uk>

\fBptpd2(8)\fR man page was written by Wojciech Owczarek for ptpd 2.3.0 in November 2013