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