FreeBSD Manual Pages
ptpd2(8) Precision Time Protocol daemon ptpd2(8) NAME ptpd2 - Precision Time Protocol daemon (1588-2008) SYNOPSIS ptpd2 [ -?hH ] [ -e SETTING ] [ -kvOLAl ] [ -smMyEPanCV ] [ -c FILE ] [ -R DIR ] [ -f FILE ] [ -S FILE ] [ -d DOMAIN ] [ -u ADDRESS ] [ -r NUM- BER ] -i INTERFACE DESCRIPTION PTPd is a daemon that implements the Precision Time Protocol (PTP) Ver- sion 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 Ether- net mode. Even without hardware assistance, PTPd is able to achieve and maintain sub-microsecond level timing precision and is able to with- stand PTP Grandmaster failovers, link failures and restarts with mini- mal 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 op- eration, and only provide the very basic PTP protocol settings. The rest of the settings (see ptpd2.conf(5)) can also be specified as com- mand-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 cor- rect. -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 configu- ration 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) -T --show-templates Display built-in configuration templates -t --templates [name],[name],... Apply one or more configuration templates in this order (see man(5) ptpd2.conf), also see ptpengine:template_files and the .TP -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:pre- set=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-destina- tions, ptpengine:unicast_destinations) unless using unicast ne- gotiation (-g, --unicast-negotiation, ptpengine:unicast_negotia- tion=y) for delay request and response (also pt- pengine: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 pt- pengine:ip_mode=unicast + ptpengine:unicast_destinations) -E --e2e End to end delay mechanism (also ptpengine:delay_mecha- nism=E2E) -E --p2p Peer to peer delay mechanism (also ptpengine:delay_mecha- nism=P2P) -a --delay-override In slave state, override delay request interval announced by master (also ptpengine:log_delayreq_override) - the value of pt- pengine:log_delayreq_interval is used -r --delay-interval NUMBER Specify delay request message interval (log 2) - (also pt- pengine: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 'Master mode with NTP' (master only mode) -W 'Master mode without NTP' (master / slave mode) -Y NUMBER Delay request interval (log 2) -t Do not adjust the clock NOTE: the above options are deprecated and will be removed in subse- quent 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 De- lay Response message. When PTPd starts up or flushes the log, a com- ment 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 spread- sheet 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 maxi- mum 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 onthe global:statistics_time- stamp_format setting (see ptpd2.conf(5)). When import- ing 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 prop- erly 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 lo- cal 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 up- per half of the MAC address. PTPd will attempt to con- vert 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 De- lay 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 correc- tions. This is the value typically observed when esti- mating 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 re- jected by a filter, the previous value will be shown in the log. This value will also be zero if no Delay Re- sponse messages are being received. Master to Slave Intermediate offset value (seconds) extracted from the Sync messages, used for computing the offset from mas- ter. 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, D for Delay Response and P for Peer Delay Response when using P2P delay mode. If a slave logs no D (or P) entries, this means it's not receiving Delay Response messages, which could be a network is- sue. For two-step clocks, "S" will still be printed when Follow-up was received. Sequence ID Sequence number of the last received message (Sync, Follow-Up, Delay Response, Peer Delay Response). Se- quence numbers in the statistics log file can help identify timing issues when analysing capture files; a change of offset or path delay can be traced to a par- ticular packet that matches the sequence ID. One Way Delay Mean One-way delay mean computed over the last sampling win- dow. 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 stan- dard 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 com- puted and displayed if PTPd was built without --disable-statistics. The duration of the sampling period is controlled with the global:statis- tics_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 pa- rameters, 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 So- laris 11 has not been tested but in essence, it should work as in- tended. 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 cur- rently no ongoing effort to acheive this. Patches for QNX/Neutrino have been provided, but cannot yet officially be merged because of no avail- ability 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 soft- ware 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 plat- form, 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 version 2.3.2 October, 2015 ptpd2(8)
NAME | SYNOPSIS | DESCRIPTION | COMMAND-LINE CONFIGURATION | BASIC DAEMON OPTIONS | BASIC PTP PROTOCOL OPTIONS | COMPATIBILITY OPTIONS | PTPD PORT STATES | STATISTICS LOG FILE FORMAT | HANDLED SIGNALS | EXIT CODES | SUPPORTED PLATFORMS AND ARCHITECTURES | HARDWARE TIMESTAMPING SUPPORT | BUGS | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ptpd2&sektion=8&manpath=FreeBSD+Ports+14.3.quarterly>