1ptpd2(8) Precision Time Protocol daemon ptpd2(8)
2
6 ptpd2 - Precision Time Protocol daemon (1588-2008)
7
9 ptpd2 [ -?hH ] [ -e SETTING ] [ -kvOLAl ] [ -smMyEPanCV ] [ -c FILE ] [
10 -R DIR ] [ -f FILE ] [ -S FILE ] [ -d DOMAIN ] [ -u ADDRESS ] [ -r NUM‐
11 BER ] -i INTERFACE
12
14 PTPd is a daemon that implements the Precision Time Protocol (PTP) Ver‐
15 sion 2 as defined by the IEEE 1588-2008 standard. PTP was developed to
16 provide very precise time coordination of LAN connected computers. The
17 daemon must run as root in order to be able to manipluate the system
18 clock and use low port numbers. PTPd is feature rich, supports IPv4
19 multicast, unicast and hybrid mode (mixed) operation, as well as Ether‐
20 net mode. Even without hardware assistance, PTPd is able to achieve and
21 maintain sub-microsecond level timing precision and is able to with‐
22 stand PTP Grandmaster failovers, link failures and restarts with mini‐
23 mal impact to timing performance. PTPd is lightweight, portable and
24 currently supports Linux, FreeBSD and Mac OS X and runs on multiple CPU
25 architectures, 32-bit and 64-bit, including x86 and ARM.
26
28 As of version 2.3.0, configuration file is the preferred mechanism for
29 configuring PTPd, therefore the options available as short (-x) and
30 long options (--xxxxx) mostly provide basic control over the daemon
31 operation, and only provide the very basic PTP protocol settings. The
32 rest of the settings (see ptpd2.conf(5)) can also be specified as com‐
33 mand-line options, but they take the long --key:section="value" form.
34
37 -c --config-file PATH
38 Path to configuration file (see ptpd2.conf(5))
39 -k --check-config
41 Check configuration and exit - return 0 if configuration is cor‐
42 rect.
43 -v --version
45 Print version string and exit
46 -h --help
48 Show help screen
49 -H --long-help
51 Show detailed help for all settings and behaviours
52 -e --explain SETTING
54 Show help for a single setting (section:key)
55 -O --default-config
57 Show default configuration and exit (output usable as a configu‐
58 ration file)
59 -L --ignore-lock
61 Skip lock file checks and locking (also global:ignore_lock)
62 -A --auto-lock
64 Use preset / port mode specific lock file names - useful when
65 running multiple instances
66 -l --lockfile
68 Specify lock file path (also global:lock_file)
69 -p --print-lockfile
71 Print path to lock file and exit (useful for init scripts in
72 combination with auto lock files)
73 -R --lock-directory DIR
75 Directory to store lock files (also global:lock_directory)
76 -f --log-file PATH
78 Path to log file (also global:logfile)
79 -S --statistics-file PATH
81 Path to statistics file (also global:statistics_file)
82 -T --show-templates
84 Display built-in configuration templates
85 -t --templates [name],[name],...
87 Apply one or more configuration templates in this order (see
88 man(5) ptpd2.conf), also see ptpengine:template_files and the
89 .TP -S --statistics-file PATH Path to statistics file (also
90 global:statistics_file)
91
94 -i --interface DEV
95 REQUIRED:Interface to use - eth0, etc (also ptpengine:interface)
96 -d --domain NUMBER
98 PTP domain number to become part of (also ptpengine:domain)
99 -s --slaveonly
101 Slave only mode (also ptpengine:preset=slaveonly)
102 -m --masterslave
104 Full IEEE 1588 implementation: master, slave when not best GM
105 (also ptpengine:preset=masterslave)
106 -M --masteronly
108 Master only mode: passive when not best GM (also ptpengine:pre‐
109 set=masteronly)
110 -y --hybrid
112 Hybrid mode - mixed multicast and unicast operation (multicast
113 for sync and announce, unicast for delay request and response
114 (also ptpengine:ip_mode=hybrid)
115 -U --unicast
117 Unicast operation - (also ptpengine:ip_mode=unicast). For a GM,
118 unicast destinations must be specified (-u, --unicast-destina‐
119 tions, ptpengine:unicast_destinations) unless using unicast
120 negotiation (-g, --unicast-negotiation, ptpengine:unicast_nego‐
121 tiation=y) for delay request and response (also
122 ptpengine:ip_mode=hybrid). For a slave, unicast destinations
123 must be specified if not using unicast negotiation.
124 -g --unicast-negotiation
126 Enable unicast message delivery and interval negotiation usin
127 signaling messages, as used by the Telecom profile (also enables
128 ptpengine:ip_mode=unicast)
129 -u --unicast-destinations ip/host, ip/host, ...
131 List of unicast destinations - see --unicast (also
132 ptpengine:ip_mode=unicast + ptpengine:unicast_destinations) -E
133 --e2e End to end delay mechanism (also ptpengine:delay_mecha‐
134 nism=E2E)
135 -E --p2p
137 Peer to peer delay mechanism (also ptpengine:delay_mecha‐
138 nism=P2P)
139 -a --delay-override
141 In slave state, override delay request interval announced by
142 master (also ptpengine:log_delayreq_override) - the value of
143 ptpengine:log_delayreq_interval is used
144 -r --delay-interval NUMBER
146 Specify delay request message interval (log 2) - (also
147 ptpengine:log_delayreq_interval)
148 -n --clock:no_adjust
150 Do not adjust the clock (also clock:no_adjust)
151 -D<DD...> --debug
153 Debug level (also global:debug_level) - only if compiled with
154 RUNTIME_DEBUG
155 -C --foreground
157 Don't run in background (also global:foreground=Y)
158 -V --verbose
160 Run in foreground, log all the messages to standard output (also
161 global:verbose_foreground=Y)
162
165 PTPd supports the following options compatible with versions before
166 2.3.0:
167 -b DEV Network interface to use
169 -i NUMBER
171 PTP domain number
172 -G ´Master mode with NTP´ (master only mode)
174 -W ´Master mode without NTP´ (master / slave mode)
176 -Y NUMBER
178 Delay request interval (log 2)
179 -t Do not adjust the clock
181 NOTE: the above options are deprecated and will be removed in subse‐
183 quent versions. Until then, their use will issue a warning.
184
188 init INITIALIZING
189 flt FAULTY
191 lstn_init
193 LISTENING (first time)
194 lstn_reset
196 LISTENING (subsequent reset)
197 pass PASSIVE (not best master, not announcing)
199 uncl UNCALIBRATED
201 slv SLAVE
203 pmst PRE-MASTER
205 mst MASTER (active)
207 dsbl DISABLED
209 ? (unk)
211 UNKNOWN state
212
215 When the statistics log is enabled (ptpengine:log_statistics, verbose
216 foreground mode or log file - ptpengine:statistics_file), a PTPd slave
217 will log clock sync information upon the receipt of every Sync and
218 Delay Response message. When PTPd starts up or flushes the log, a com‐
219 ment line (starting with #) will be logged, containing the names of all
220 columns. The format of this log is a series of comma-separated values
221 (CSV) and can be easily imported into statistics tools and most spread‐
222 sheet software packages for analysis and graphing. This log can get
223 very large when running PTPd for longer periods of time and with high
224 message rates, therefore to reduce the number of messages logged, the
225 global:statistics_log_interval setting can be used, to limit the log
226 output to one message per configured interval only. The size and maxi‐
227 mum number of the statistics log can also be controlled - (see
228 ptpd2.conf(5)).
229 The meaning of the columns is as follows:
231 Timestamp
233 Time when message received. This can take the form of
234 text date / time or Unix timestamp (with fractional
235 seconds), or both (in which case an exra field is
236 added), depending onthe global:statistics_time‐
237 stamp_format setting (see ptpd2.conf(5)). When import‐
238 ing the log into plotting software, if the software can
239 understand Unix time, it is best to set the timestamp
240 format to unix or both, as some software will not prop‐
241 erly deal with the fractional part of the second when
242 converting the date and time from text.
243 State Port state (see PTP PORT STATES).
245 Clock ID
247 Port identity of the current best master, as defined by
248 IEEE 1588. This will be the local clock's ID if the
249 local clock is the best master. Displayed as
250 clock_id/port(host) Port is the PTP clock port number,
251 not to be confused with UDP ports. The clock ID is an
252 EUI-64 64-bit ID, usually converted from the 48-bit MAC
253 address, by inserting 0xfffe between the lower and
254 upper half of the MAC address. PTPd will attempt to
255 convert the clock ID back to MAC address and look up
256 the hostname from /etc/ethers (see ethers(5)). Populat‐
257 ing the ethers file will help the administrator recog‐
258 nise the masters by familiar hostnames.
259 One Way Delay
261 Current value of one-way delay (or mean path delay) in
262 seconds, calculated by PTPd in slave state from the
263 Delay Request - Delay Response message exchange. Note:
264 if this value remains at zero, this usually means that
265 no Delay Response messages are being received, likely
266 due to a network issue.
267 Offset From Master
269 Current value of offset from master in seconds - this
270 is the main output of the PTP engine in slave state,
271 which is the input of the clock servo for clock correc‐
272 tions. This is the value typically observed when esti‐
273 mating the slave performance.
274 Slave to Master
276 Intermediate offset value (seconds) extracted from the
277 Delay Request - Delay Response message exchange, used
278 for computing one-way delay. If the last value was
279 rejected by a filter, the previous value will be shown
280 in the log. This value will also be zero if no Delay
281 Response messages are being received.
282 Master to Slave
284 Intermediate offset value (seconds) extracted from the
285 Sync messages, used for computing the offset from mas‐
286 ter. If the last value was rejected by a filter, the
287 previous value will be shown in the log.
288 Observed Drift
290 The integral accumulator of the clock control PI servo
291 model - frequency difference between the slave clock
292 and master clock. This value becomes stable when the
293 clock offset has stabilised, and can be used (and is)
294 to detect clock stability.
295 Last Packet Received
297 This field shows what message was received last - this
298 will be S for Sync, D for Delay Response and P for Peer
299 Delay Response when using P2P delay mode. If a slave
300 logs no D (or P) entries, this means it's not receiving
301 Delay Response messages, which could be a network
302 issue. For two-step clocks, "S" will still be printed
303 when Follow-up was received.
304 Sequence ID
306 Sequence number of the last received message (Sync,
307 Follow-Up, Delay Response, Peer Delay Response).
308 Sequence numbers in the statistics log file can help
309 identify timing issues when analysing capture files; a
310 change of offset or path delay can be traced to a par‐
311 ticular packet that matches the sequence ID.
312 One Way Delay Mean
314 One-way delay mean computed over the last sampling win‐
315 dow.
316 One Way Delay Std Dev
318 One-way delay standard deviation computed over the last
319 sampling window.
320 Offset From Master Mean
322 Offset from master mean computed over the last sampling
323 window.
324 Offset From Master Std Dev
326 Offset from master standard deviation computed over the
327 last sampling window.
328 Observed Drift Mean
330 Observed drift / local clock frequency adjustment mean
331 computed over the last sampling window.
332 Observed Drift Std Dev
334 Observed drift / local clock frequency adjustment stan‐
335 dard deviation computed over the last sampling window.
336 The lower the value, the less aggressively the clock is
337 being controlled and therefore the more stable it is.
338 raw delayMS
340 Raw (unfiltered) delayMS value - useful for evaluating
341 outliers and filter performance.
342 raw delaySM
344 Raw (unfiltered) delaySM value - useful for evaluating
345 outliers and filter performance.
346 NOTE: All the statistical measures (mean and std dev) will only be com‐
348 puted and displayed if PTPd was built without --disable-statistics. The
349 duration of the sampling period is controlled with the global:statis‐
350 tics_update_interval setting - (see ptpd2.conf(5)).
351
354 PTPd handles the following signals:
355 SIGHUP Reload configuration file (if used) and reopen log
357 files
358 SIGUSR1 When in slave state, force clock step to current Offset
360 from Master value
361 SIGUSR2 Dump all PTP protocol counters to current log target
363 (and clear if ptpengine:sigusr2_clears_counters set)
364 SIGINT|SIGTERM
366 Clean exit - close logs and other open files, clean up
367 lock file and exit.
368 SIGKILL Force an unclean exit.
370
372 Upon exit, ptpd2 returns 0 on success - either successfully started in
373 daemon mode, or otherwise exited cleanly. 0 is also returned when the
374 -k (--check-config) option is used and the configuration was correct. A
375 non-zero exit code is returned on errors. 3 is returned on lock file
376 errors and when ptpd2 could not be started as daemon. 2 is returned on
377 memory allocation errors during startup. For all other error conditions
378 such as configuration errors, running ptpd2 in help mode or with no
379 parameters, on self shutdown, network startup errors and when attempt‐
380 ing to run ptpd2 as non-root - 1 is returned.
381
384 PTPd is fully supported on Linux and FreeBSD as this is what the core
385 developers focus on. OpenBSD and NetBSD are also supported, but get
386 less developers' attention. So is Max OS X, and as of PTPd 2.3.1 also
387 OpenSolaris (11) derivatives (tested on OmniOS). Sun's / Oracle's
388 Solaris 11 has not been tested but in essence, it should work as
389 intended. Solaris 10 is NOT supported because it does not provide the
390 SO_TIMESTAMP socket option. It should theoretically be possible to use
391 Solaris 10 using the pf facility as used by snoop, but there is cur‐
392 rently no ongoing effort to acheive this. Patches for QNX/Neutrino have
393 been provided, but cannot yet officially be merged because of no avail‐
394 ability of QNX to the developers. Some users have ported PTPd to other
395 RTOS, but this has not been merged either.
396 As of 2.3.1, PTPd runs entirely in software and only relies on kernel
398 and OS APIs, so there are no hardware dependencies. Any little-endian
399 or big-endian port of modern versions of the supported OSes should
400 work, but only x86 and ARM are actively tested. The only dependencies
401 close to hardware can be NIC drivers and how and if they impact soft‐
402 ware timestamping.
403
406 As of 2.3.1, PTPd still does not support hardware timestamping. This
407 functionality will appear in the upcoming version 2.4 - potentially an
408 interim version of 2.3.x may be delivered that will support hardware
409 clocks and timestamping on Linux. This is very much OS-specific and to
410 a large extent, hardware-specific. Linux has a PTP kernel API but not
411 all hardware supports it. Because PTPd supports multiple OS platforms,
412 where hardware timestamping may use different mechanisms on every plat‐
413 form, it has to be re-written in a modular way to allow this without
414 unnecessarily increasing code complexity, which already is a problem.
415
418 As of ptpd 2.3.1, the (Open)Solaris (11) OS family is supported, but
419 libpcap functionality is currently broken - IPv4/pcap and Ethernet
420 transports cannot be used on those systems. PTPd will compile and run,
421 but will not receive any data.
422 Please report any bugs using the bug tracker on the SourceForge page:
424 http://sourceforge.net/projects/ptpd/
425
428 ptpd2.conf(5)
429
431 Gael Mace <gael_mace@users.sourceforge.net>
432 Alexandre Van Kempen
434 Steven Kreuzer <skreuzer@freebsd.org>
436 George Neville-Neil <gnn@freebsd.org>
438 Wojciech Owczarek <wojciech@owczarek.co.uk>
440 ptpd2(8) man page was written by Wojciech Owczarek for ptpd 2.3.0 in
442 November 2013
443version 2.3.2 October, 2015 ptpd2(8)