1PTP4l(8) System Manager's Manual PTP4l(8)
2
6 ptp4l - PTP Boundary/Ordinary/Transparent Clock
7
10 ptp4l [ -AEP246HSLmqsv ] [ -f config ] [ -p phc-device ] [ -l print-
11 level ] [ -i interface ] [ long-options ] ...
12
15 ptp4l is an implementation of the Precision Time Protocol (PTP) accord‐
16 ing to IEEE standard 1588 for Linux. It implements Boundary Clock (BC),
17 Ordinary Clock (OC), and Transparent Clock (TC).
18
21 -A Select the delay mechanism automatically. Start with E2E and
22 switch to P2P when a peer delay request is received.
23 -E Select the delay request-response (E2E) mechanism. This is the
25 default mechanism. All clocks on single PTP communication path
26 must use the same mechanism. A warning will be printed when a
27 peer delay request is received on port using the E2E mechanism.
28 -P Select the peer delay (P2P) mechanism. A warning will be printed
30 when a delay request is received on port using the P2P mecha‐
31 nism.
32 -2 Select the IEEE 802.3 network transport.
34 -4 Select the UDP IPv4 network transport. This is the default
36 transport.
37 -6 Select the UDP IPv6 network transport.
39 -H Select the hardware time stamping. All ports specified by the -i
41 option and in the configuration file must be attached to the
42 same PTP hardware clock (PHC). This is the default time stamp‐
43 ing.
44 -S Select the software time stamping.
46 -L Select the legacy hardware time stamping.
48 -f config
50 Read configuration from the specified file. No configuration
51 file is read by default.
52 -i interface
54 Specify a PTP port, it may be used multiple times. At least one
55 port must be specified by this option or in the configuration
56 file.
57 -p phc-device
59 (This option is deprecated.) Before Linux kernel v3.5 there was
60 no way to discover the PHC device associated with a network
61 interface. This option specifies the PHC device (e.g.
62 /dev/ptp0) to be used when running on legacy kernels.
63 -s Enable the slaveOnly mode.
65 -l print-level
67 Set the maximum syslog level of messages which should be printed
68 or sent to the system logger. The default is 6 (LOG_INFO).
69 -m Print messages to the standard output.
71 -q Don't send messages to the system logger.
73 -v Prints the software version and exits.
75 -h Display a help message.
77
80 Each and every configuration file option (see below) may also appear as
81 a "long" style command line argument. For example, the slaveOnly
82 option may be set using either of these two forms.
83 --slaveOnly 1 --slaveOnly=1
85 Option values given on the command line override values in the global
87 section of the configuration file.
88
91 The configuration file is divided into sections. Each section starts
92 with a line containing its name enclosed in brackets and it follows
93 with settings. Each setting is placed on a separate line, it contains
94 the name of the option and the value separated by whitespace charac‐
95 ters. Empty lines and lines starting with # are ignored.
96 There are three different section types.
98 1. The global section (indicated as [global]) sets the program
101 options, clock options and default port options. Other sections
102 are port specific sections and they override the default port
103 options.
104 2. Port sections give the name of the configured port (e.g.
106 [eth0]). Ports specified in the configuration file don't need
107 to be specified by the -i option. An empty port section can be
108 used to replace the command line option.
109 3. Tables for configuring unicast discovery begin with
111 [unicast_master_table].
112 See UNICAST DISCOVERY OPTIONS, below.
114
117 delayAsymmetry
118 The time difference in nanoseconds of the transmit and receive
119 paths. This value should be positive when the master-to-slave
120 propagation time is longer and negative when the slave-to-master
121 time is longer. The default is 0 nanoseconds.
122 logAnnounceInterval
124 The mean time interval between Announce messages. A shorter
125 interval makes ptp4l react faster to the changes in the master-
126 slave hierarchy. The interval should be the same in the whole
127 domain. It's specified as a power of two in seconds. The
128 default is 1 (2 seconds).
129 logSyncInterval
131 The mean time interval between Sync messages. A shorter interval
132 may improve accuracy of the local clock. It's specified as a
133 power of two in seconds. The default is 0 (1 second).
134 logMinDelayReqInterval
136 The minimum permitted mean time interval between Delay_Req mes‐
137 sages. A shorter interval makes ptp4l react faster to the
138 changes in the path delay. It's specified as a power of two in
139 seconds. The default is 0 (1 second).
140 logMinPdelayReqInterval
142 The minimum permitted mean time interval between Pdelay_Req mes‐
143 sages. It's specified as a power of two in seconds. The default
144 is 0 (1 second).
145 announceReceiptTimeout
147 The number of missed Announce messages before the last Announce
148 messages expires. The default is 3.
149 syncReceiptTimeout
151 The number of sync/follow up messages that may go missing before
152 triggering a Best Master Clock election. This option is used for
153 running in gPTP mode according to the 802.1AS-2011 standard.
154 Setting this option to zero will disable the sync message time‐
155 out. The default is 0 or disabled.
156 transportSpecific
158 The transport specific field. Must be in the range 0 to 255.
159 The default is 0.
160 ignore_transport_specific
162 By default, incoming messages are dropped if their transportSpe‐
163 cific field does not match the configured value. However, many
164 of transports specified in the 1588 standard mandate ignoring
165 this field. Moreover, some equipment is known to set the
166 reserved bits. Configuring this option as 1 causes this field
167 to be ignored completely on receive. The default is 0.
168 path_trace_enabled
170 Enable the mechanism used to trace the route of the Announce
171 messages. The default is 0 (disabled).
172 follow_up_info
174 Include the 802.1AS data in the Follow_Up messages if enabled.
175 The default is 0 (disabled).
176 fault_reset_interval
178 The time in seconds between the detection of a port's fault and
179 the fault being reset. This value is expressed as a power of
180 two. Setting this value to -128 or to the special key word
181 "ASAP" will let the fault be reset immediately. The default is
182 4 (16 seconds).
183 fault_badpeernet_interval
185 The time in seconds between the detection of a peer network mis‐
186 configuration and the fault being reset. The port is disabled
187 for the duration of the interval. The value is in seconds and
188 the special key word ASAP will let the fault be reset immedi‐
189 ately. The default is 16 seconds.
190 delay_mechanism
192 Select the delay mechanism. Possible values are E2E, P2P and
193 Auto. The default is E2E.
194 hybrid_e2e
196 Enables the "hybrid" delay mechanism from the draft Enterprise
197 Profile. When enabled, ports in the slave state send their delay
198 request messages to the unicast address taken from the master's
199 announce message. Ports in the master state will reply to uni‐
200 cast delay requests using unicast delay responses. This option
201 has no effect if the delay_mechanism is set to P2P. The default
202 is 0 (disabled).
203 inhibit_multicast_service
205 Some unicast mode profiles insist that no multicast message are
206 ever transmitted. Setting this option inhibits multicast trans‐
207 mission. The default is 0 (mutlicast enabled).
208 net_sync_monitor
210 Enables the NetSync Monitor (NSM) protocol. The NSM protocol
211 allows a station to measure how well another node is synchro‐
212 nized. The monitor sends a unicast delay request to the node,
213 which replies unconditionally with unicast delay response, sync,
214 and follow up messages. If the monitor is synchronized to the
215 GM, it can use the time stamps in the message to estimate the
216 node's offset. This option requires that the 'hybrid_e2e'
217 option be enabled as well. The default is 0 (disabled).
218 unicast_listen
220 When enabled, this option allows the port to grant unicast mes‐
221 sage contracts. Incoming requests for will be granted limited
222 only by the amount of memory available. The default is 0 (dis‐
223 abled).
224 unicast_master_table
226 When set to a positive integer, this option specifies the table
227 id to be used for unicast discovery. Each table lives in its
228 own section and has a unique, positive numerical ID. Entries in
229 the table are a pair of transport type and protocol address.
230 Tables may not be shared between ports, but nothing prevents ta‐
231 ble entries from appearing in more than table. The default is 0
232 (unicast discovery disabled).
233 unicast_req_duration
235 The service time in seconds to be requested during unicast dis‐
236 covery. Note that the remote node is free to grant a different
237 duration. The default is 3600 seconds or one hour.
238 ptp_dst_mac
240 The MAC address to which PTP messages should be sent. Relevant
241 only with L2 transport. The default is 01:1B:19:00:00:00.
242 p2p_dst_mac
244 The MAC address to which peer delay messages should be sent.
245 Relevant only with L2 transport. The default is
246 01:80:C2:00:00:0E.
247 network_transport
249 Select the network transport. Possible values are UDPv4, UDPv6
250 and L2. The default is UDPv4.
251 neighborPropDelayThresh
253 Upper limit for peer delay in nanoseconds. If the estimated peer
254 delay is greater than this value the port is marked as not
255 802.1AS capable.
256 masterOnly
258 Setting this option to one (1) prevents the port from entering
259 the SLAVE state. In addition, the local clock will ignore
260 Announce messages received on this port. This option's intended
261 use is to support the Telecom Profiles according to ITU-T
262 G.8265.1, G.8275.1, and G.8275.2. The default value is zero or
263 false.
264 G.8275.portDS.localPriority
266 The Telecom Profiles (ITU-T G.8275.1 and G.8275.2) specify an
267 alternate Best Master Clock Algorithm (BMCA) with a unique data
268 set comparison algorithm. The value of this option is associ‐
269 ated with Announce messages arriving on a particular port and is
270 used as a tie breaker whenever clockClass, clockAccuracy, off‐
271 setScaledLogVariance, and priority2 are equal. This option is
272 only used when "dataset_comparison" is set to "telecom". The
273 default value is 128.
274 Warning: the BMCA is guaranteed to produce a spanning tree (that
276 is, a timing network without loops) only when using the default
277 values of G.8275.defaultDS.localPriority and
278 G.8275.portDS.localPriority. Careful network engineering is
279 needed when using non-default values.
280 min_neighbor_prop_delay
282 Lower limit for peer delay in nanoseconds. If the estimated peer
283 delay is smaller than this value the port is marked as not
284 802.1AS capable.
285 tsproc_mode
287 Select the time stamp processing mode used to calculate offset
288 and delay. Possible values are filter, raw, filter_weight,
289 raw_weight. Raw modes perform well when the rate of sync mes‐
290 sages (logSyncInterval) is similar to the rate of delay messages
291 (logMinDelayReqInterval or logMinPdelayReqInterval). Weighting
292 is useful with larger network jitters (e.g. software time stamp‐
293 ing). The default is filter.
294 delay_filter
296 Select the algorithm used to filter the measured delay and peer
297 delay. Possible values are moving_average and moving_median.
298 The default is moving_median.
299 delay_filter_length
301 The length of the delay filter in samples. The default is 10.
302 egressLatency
304 Specifies the difference in nanoseconds between the actual
305 transmission time at the reference plane and the reported trans‐
306 mit time stamp. This value will be added to egress time stamps
307 obtained from the hardware. The default is 0.
308 ingressLatency
310 Specifies the difference in nanoseconds between the reported
311 receive time stamp and the actual reception time at reference
312 plane. This value will be subtracted from ingress time stamps
313 obtained from the hardware. The default is 0.
314 boundary_clock_jbod
316 When running as a boundary clock (that is, when more than one
317 network interface is configured), ptp4l performs a sanity check
318 to make sure that all of the ports share the same hardware clock
319 device. This option allows ptp4l to work as a boundary clock
320 using "just a bunch of devices" that are not synchronized to
321 each other. For this mode, the collection of clocks must be syn‐
322 chronized by an external program, for example phc2sys(8) in
323 "automatic" mode. The default is 0 (disabled).
324 udp_ttl
326 Specifies the Time to live (TTL) value for IPv4 multicast mes‐
327 sages and the hop limit for IPv6 multicast messages. This option
328 is only relevant with the IPv4 and IPv6 UDP transports. The
329 default is 1 to restrict the messages sent by ptp4l to the same
330 subnet.
331
334 twoStepFlag
335 Enable two-step mode for sync messages. One-step mode can be
336 used only with hardware time stamping. The default is 1
337 (enabled).
338 slaveOnly
340 The local clock is a slave-only clock if enabled. This option
341 is only for use with 1588 clocks and should not be enabled for
342 802.1AS clocks. The default is 0 (disabled).
343 gmCapable
345 If this option is enabled, then the local clock is able to
346 become grand master. This is only for use with 802.1AS clocks
347 and has no effect on 1588 clocks. The default is 1 (enabled).
348 priority1
350 The priority1 attribute of the local clock. It is used in the
351 best master selection algorithm, lower values take precedence.
352 Must be in the range 0 to 255. The default is 128.
353 priority2
355 The priority2 attribute of the local clock. It is used in the
356 best master selection algorithm, lower values take precedence.
357 Must be in the range 0 to 255. The default is 128.
358 clockClass
360 The clockClass attribute of the local clock. It denotes the
361 traceability of the time distributed by the grandmaster clock.
362 The default is 248.
363 clockAccuracy
365 The clockAccuracy attribute of the local clock. It is used in
366 the best master selection algorithm. The default is 0xFE.
367 offsetScaledLogVariance
369 The offsetScaledLogVariance attribute of the local clock. It
370 characterizes the stability of the clock. The default is
371 0xFFFF.
372 G.8275.defaultDS.localPriority
374 The Telecom Profiles (ITU-T G.8275.1 and G.8275.2) specify an
375 alternate Best Master Clock Algorithm (BMCA) with a unique data
376 set comparison algorithm. The value of this option is associ‐
377 ated with the local clock and is used as a tie breaker whenever
378 clockClass, clockAccuracy, offsetScaledLogVariance, and prior‐
379 ity2 are equal. This option is only used when "dataset_compari‐
380 son" is set to "telecom". The default value is 128.
381 Warning: the BMCA is guaranteed to produce a spanning tree (that
383 is, a timing network without loops) only when using the default
384 values of G.8275.defaultDS.localPriority and
385 G.8275.portDS.localPriority. Careful network engineering is
386 needed when using non-default values.
387 domainNumber
389 The domain attribute of the local clock. The default is 0.
390 utc_offset
392 The current offset between TAI and UTC. The default is 37.
393 free_running
395 Don't adjust the local clock if enabled. The default is 0 (dis‐
396 abled).
397 freq_est_interval
399 The time interval over which is estimated the ratio of the local
400 and peer clock frequencies. It is specified as a power of two in
401 seconds. The default is 1 (2 seconds).
402 assume_two_step
404 Treat one-step responses as two-step if enabled. It is used to
405 work around buggy 802.1AS switches. The default is 0 (dis‐
406 abled).
407 tc_spanning_tree
409 When running as a Transparent Clock, increment the "stepsRe‐
410 moved" field of Announce messages that pass through the switch.
411 Enabling this option ensures that PTP message loops never form,
412 provided the switches all implement this option together with
413 the BMCA.
414 tx_timestamp_timeout
416 The number of milliseconds to poll waiting for the tx time stamp
417 from the kernel when a message has recently been sent. The
418 default is 1.
419 check_fup_sync
421 Because of packet reordering that can occur in the network, in
422 the hardware, or in the networking stack, a follow up message
423 can appear to arrive in the application before the matching sync
424 message. As this is a normal occurrence, and the sequenceID mes‐
425 sage field ensures proper matching, the ptp4l program accepts
426 out of order packets. This option adds an additional check using
427 the software time stamps from the networking stack to verify
428 that the sync message did arrive first. This option is only use‐
429 ful if you do not trust the sequence IDs generated by the mas‐
430 ter. The default is 0 (disabled).
431 clock_servo
433 The servo which is used to synchronize the local clock. Valid
434 values are "pi" for a PI controller, "linreg" for an adaptive
435 controller using linear regression, "ntpshm" for the NTP SHM
436 reference clock to allow another process to synchronize the
437 local clock (the SHM segment number is set to the domain num‐
438 ber), and "nullf" for a servo that always dials frequency offset
439 zero (for use in SyncE nodes). The default is "pi."
440 clock_type
442 Specifies the kind of PTP clock. Valid values are "OC" for
443 ordinary clock, "BC" for boundary clock, "P2P_TC" for peer to
444 peer transparent clock, and "E2E_TC" for end to end transparent
445 clock. An multi-port ordinary clock will automatically be con‐
446 figured as a boundary clock. The default is "OC".
447 pi_proportional_const
449 The proportional constant of the PI controller. When set to 0.0,
450 the proportional constant will be set by the following formula
451 from the current sync interval. The default is 0.0.
452 kp = min(kp_scale * sync^kp_exponent, kp_norm_max / sync)
454 pi_integral_const
456 The integral constant of the PI controller. When set to 0.0, the
457 integral constant will be set by the following formula from the
458 current sync interval. The default is 0.0.
459 ki = min(ki_scale * sync^ki_exponent, ki_norm_max / sync)
461 pi_proportional_scale
463 The kp_scale constant in the formula used to set the propor‐
464 tional constant of the PI controller from the sync interval.
465 When set to 0.0, the value will be selected from 0.7 and 0.1 for
466 the hardware and software time stamping respectively. The
467 default is 0.0.
468 pi_proportional_exponent
470 The kp_exponent constant in the formula used to set the propor‐
471 tional constant of the PI controller from the sync interval.
472 The default is -0.3.
473 pi_proportional_norm_max
475 The kp_norm_max constant in the formula used to set the propor‐
476 tional constant of the PI controller from the sync interval.
477 The default is 0.7
478 pi_integral_scale
480 The ki_scale constant in the formula used to set the integral
481 constant of the PI controller from the sync interval. When set
482 to 0.0, the value will be selected from 0.3 and 0.001 for the
483 hardware and software time stamping respectively. The default
484 is 0.0.
485 pi_integral_exponent
487 The ki_exponent constant in the formula used to set the integral
488 constant of the PI controller from the sync interval. The
489 default is 0.4.
490 pi_integral_norm_max
492 The ki_norm_max constant in the formula used to set the integral
493 constant of the PI controller from the sync interval. The
494 default is 0.3.
495 step_threshold
497 The maximum offset the servo will correct by changing the clock
498 frequency instead of stepping the clock. When set to 0.0, the
499 servo will never step the clock except on start. It's specified
500 in seconds. The default is 0.0. This option used to be called
501 pi_offset_const.
502 first_step_threshold
504 The maximum offset the servo will correct by changing the clock
505 frequency instead of stepping the clock. This is only applied on
506 the first update. It's specified in seconds. When set to 0.0,
507 the servo won't step the clock on start. The default is 0.00002
508 (20 microseconds). This option used to be called pi_f_off‐
509 set_const.
510 max_frequency
512 The maximum allowed frequency adjustment of the clock in parts
513 per billion (ppb). This is an additional limit to the maximum
514 allowed by the hardware. When set to 0, the hardware limit will
515 be used. The default is 900000000 (90%). This option used to
516 be called pi_max_frequency.
517 sanity_freq_limit
519 The maximum allowed frequency offset between uncorrected clock
520 and the system monotonic clock in parts per billion (ppb). This
521 is used as a sanity check of the synchronized clock. When a
522 larger offset is measured, a warning message will be printed and
523 the servo will be reset. When set to 0, the sanity check is dis‐
524 abled. The default is 200000000 (20%).
525 initial_delay
527 The initial path delay of the clock in nanoseconds used for syn‐
528 chronization of the clock before the delay is measured using the
529 E2E or P2P delay mechanism. If set to 0, the clock will not be
530 updated until the delay is measured. The default is 0.
531 ntpshm_segment
533 The number of the SHM segment used by ntpshm servo. The default
534 is 0.
535 udp6_scope
537 Specifies the desired scope for the IPv6 multicast messages.
538 This will be used as the second byte of the primary address.
539 This option is only relevant with IPv6 transport. See RFC 4291.
540 The default is 0x0E for the global scope.
541 uds_address
543 Specifies the address of the UNIX domain socket for receiving
544 local management messages. The default is /var/run/ptp4l.
545 dscp_event
547 Defines the Differentiated Services Codepoint (DSCP) to be used
548 for PTP event messages. Must be a value between 0 and 63. There
549 are several media streaming standards out there that require
550 specific values for this option. For example 46 (EF PHB) in
551 AES67 or 48 (CS6 PHB) in RAVENNA. The default is 0.
552 dscp_general
554 Defines the Differentiated Services Codepoint (DSCP) to be used
555 for PTP general messages. Must be a value between 0 and 63.
556 There are several media streaming standards out there that rec‐
557 ommend specific values for this option. For example 34 (AF41
558 PHB) in AES67 or 46 (EF PHB) in RAVENNA. The default is 0.
559 dataset_comparison
561 Specifies the method to be used when comparing data sets during
562 the Best Master Clock Algorithm. The possible values are
563 "ieee1588" and "G.8275.x". The default is "ieee1588".
564 logging_level
566 The maximum logging level of messages which should be printed.
567 The default is 6 (LOG_INFO).
568 message_tag
570 The tag which is added to all messages printed to the standard
571 output or system log. The default is an empty string (which
572 cannot be set in the configuration file as the option requires
573 an argument).
574 verbose
576 Print messages to the standard output if enabled. The default
577 is 0 (disabled).
578 use_syslog
580 Print messages to the system log if enabled. The default is 1
581 (enabled).
582 summary_interval
584 The time interval in which are printed summary statistics of the
585 clock. It is specified as a power of two in seconds. The statis‐
586 tics include offset root mean square (RMS), maximum absolute
587 offset, frequency offset mean and standard deviation, and path
588 delay mean and standard deviation. The units are nanoseconds and
589 parts per billion (ppb). If there is only one clock update in
590 the interval, the sample will be printed instead of the statis‐
591 tics. The messages are printed at the LOG_INFO level. The
592 default is 0 (1 second).
593 time_stamping
595 The time stamping method. The allowed values are hardware, soft‐
596 ware and legacy. The default is hardware.
597 productDescription
599 The product description string. Allowed values must be of the
600 form manufacturerName;modelNumber;instanceIdentifier and contain
601 at most 64 utf8 symbols. The default is ";;".
602 revisionData
604 The revision description string which contains the revisions for
605 node hardware (HW), firmware (FW), and software (SW). Allowed
606 values are of the form HW;FW;SW and contain at most 32 utf8 sym‐
607 bols. The default is an ";;".
608 userDescription
610 The user description string. Allowed values are of the form
611 name;location and contain at most 128 utf8 symbols. The default
612 is an empty string.
613 manufacturerIdentity
615 The manufacturer id which should be an OUI owned by the manufac‐
616 turer. The default is 00:00:00.
617 kernel_leap
619 When a leap second is announced, let the kernel apply it by
620 stepping the clock instead of correcting the one-second offset
621 with servo, which would correct the one-second offset slowly by
622 changing the clock frequency (unless the step_threshold option
623 is set to correct such offset by stepping). Relevant only with
624 software time stamping. The default is 1 (enabled).
625 timeSource
627 The time source is a single byte code that gives an idea of the
628 kind of local clock in use. The value is purely informational,
629 having no effect on the outcome of the Best Master Clock algo‐
630 rithm, and is advertised when the clock becomes grand master.
631
634 table_id
635 Each table must begin with a unique, positive table ID. The
636 port that claims a given table does so by including the ID as
637 the value of its 'unicast_master_table' option.
638 logQueryInterval
640 This option configures the time to wait between unicast negotia‐
641 tion attempts. It is specified as a power of two in seconds.
642 The default is 0 (1 second).
643 peer_address
645 This option specifies the unicast address of the peer for use
646 with the peer to peer delay mechanism. If specified, the port
647 owning the table will negotiate unicast peer delay responses
648 from the machine at the given remote address, otherwise the port
649 will send multicast peer delay requests.
650 L2|UDPv4
652 Each table entry specifies the transport type and network
653 address of a potential remote master. If multiple masters are
654 specified, then unicast negotiation will be performed with each
655 if them.
656
659 ptp4l as domain master either uses PTP or UTC time scale depending on
660 time stamping mode. In software and legacy time stamping modes it
661 announces Arbitrary time scale mode, which is effectively UTC here, in
662 hardware time stamping mode it announces use of PTP time scale.
663 When ptp4l is the domain master using hardware time stamping, it is up
665 to phc2sys to maintain the correct offset between UTC and PTP times.
666 See phc2sys(8) manual page for more details.
667
670 pmc(8), phc2sys(8)
671linuxptp April 2018 PTP4l(8)