Scroll to navigation

ptpd(8) Precision Time Protocol daemon ptpd(8)

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 ptpd.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 I PATH
Path to statistics file (also global:statistics_file)

BASIC PTP PROTOCOL OPTIONS

-i --interface EV
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 IP
Unicast mode (no unicast negotiation) - send all messages to IP (also ptpengine:ip_mode=unicast + ptpengine:unicast_address) -E --e2e End to end delay detection (also ptpengine:delay_mechanism=E2E)
-E --p2p
Peer to peer delay detection (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

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
Bahaviour based on configure --enable-sigusr2=[value]. Options: domain: swap domain between current and current +1; debug: cycle runtime debug level; counters:Dump all PTP protocol counters to current log targer.
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.

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
November, 2013 version 2.3.0