.\" -*- nroff -*"
.TH ptpd 8 "November, 2013" "version 2.3.0" "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 \fBptpd.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 \fII PATH\fR
Path to statistics file (also \fIglobal:statistics_file\fR)
.SH BASIC PTP PROTOCOL OPTIONS
.TP
\fB-i --interface \fDEV\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 \fIIP\fR
Unicast mode (no unicast negotiation) - send all messages to \fIIP\fR
(also \fIptpengine:ip_mode=unicast\fR + \fIptpengine:unicast_address\fR)
\fB-E --e2e\fR
End to end delay detection (also \fIptpengine:delay_mechanism=E2E\fR)
.TP
\fB-E --p2p\fR
Peer to peer delay detection (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 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
Bahaviour based on \fIconfigure --enable-sigusr2=[value]\fR. Options:
\fIdomain\fR: swap domain between current and current +1;
\fIdebug\fR: cycle runtime debug level;
\fIcounters\fR:Dump all PTP protocol counters to current log targer.
.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 SEE ALSO
.Xr ptpd2.conf 5
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