1PTP4l(8) System Manager's Manual PTP4l(8)
2
6 ptp4l - PTP Boundary/Ordinary 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 and Ordinary Clock (OC).
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 The global section (indicated as [global]) sets the program options,
98 clock options and default port options. Other sections are port spe‐
99 cific sections and they override the default port options. The name of
100 the section is the name of the configured port (e.g. [eth0]). Ports
101 specified in the configuration file don't need to be specified by the
102 -i option. An empty port section can be used to replace the command
103 line option.
104
107 delayAsymmetry
108 The time difference in nanoseconds of the transmit and receive
109 paths. This value should be positive when the master-to-slave
110 propagation time is longer and negative when the slave-to-master
111 time is longer. The default is 0 nanoseconds.
112 logAnnounceInterval
114 The mean time interval between Announce messages. A shorter
115 interval makes ptp4l react faster to the changes in the master-
116 slave hierarchy. The interval should be the same in the whole
117 domain. It's specified as a power of two in seconds. The
118 default is 1 (2 seconds).
119 logSyncInterval
121 The mean time interval between Sync messages. A shorter interval
122 may improve accuracy of the local clock. It's specified as a
123 power of two in seconds. The default is 0 (1 second).
124 logMinDelayReqInterval
126 The minimum permitted mean time interval between Delay_Req mes‐
127 sages. A shorter interval makes ptp4l react faster to the
128 changes in the path delay. It's specified as a power of two in
129 seconds. The default is 0 (1 second).
130 logMinPdelayReqInterval
132 The minimum permitted mean time interval between Pdelay_Req mes‐
133 sages. It's specified as a power of two in seconds. The default
134 is 0 (1 second).
135 announceReceiptTimeout
137 The number of missed Announce messages before the last Announce
138 messages expires. The default is 3.
139 syncReceiptTimeout
141 The number of sync/follow up messages that may go missing before
142 triggering a Best Master Clock election. This option is used for
143 running in gPTP mode according to the 802.1AS-2011 standard.
144 Setting this option to zero will disable the sync message time‐
145 out. The default is 0 or disabled.
146 transportSpecific
148 The transport specific field. Must be in the range 0 to 255.
149 The default is 0.
150 path_trace_enabled
152 Enable the mechanism used to trace the route of the Announce
153 messages. The default is 0 (disabled).
154 follow_up_info
156 Include the 802.1AS data in the Follow_Up messages if enabled.
157 The default is 0 (disabled).
158 fault_reset_interval
160 The time in seconds between the detection of a port's fault and
161 the fault being reset. This value is expressed as a power of
162 two. Setting this value to -128 or to the special key word
163 "ASAP" will let the fault be reset immediately. The default is
164 4 (16 seconds).
165 fault_badpeernet_interval
167 The time in seconds between the detection of a peer network mis‐
168 configuration and the fault being reset. The port is disabled
169 for the duration of the interval. The value is in seconds and
170 the special key word ASAP will let the fault be reset immedi‐
171 ately. The default is 16 seconds.
172 delay_mechanism
174 Select the delay mechanism. Possible values are E2E, P2P and
175 Auto. The default is E2E.
176 hybrid_e2e
178 Enables the "hybrid" delay mechanism from the draft Enterprise
179 Profile. When enabled, ports in the slave state send their delay
180 request messages to the unicast address taken from the master's
181 announce message. Ports in the master state will reply to uni‐
182 cast delay requests using unicast delay responses. This option
183 has no effect if the delay_mechanism is set to P2P. The default
184 is 0 (disabled).
185 ptp_dst_mac
187 The MAC address to which PTP messages should be sent. Relevant
188 only with L2 transport. The default is 01:1B:19:00:00:00.
189 p2p_dst_mac
191 The MAC address to which peer delay messages should be sent.
192 Relevant only with L2 transport. The default is
193 01:80:C2:00:00:0E.
194 network_transport
196 Select the network transport. Possible values are UDPv4, UDPv6
197 and L2. The default is UDPv4.
198 neighborPropDelayThresh
200 Upper limit for peer delay in nanoseconds. If the estimated peer
201 delay is greater than this value the port is marked as not
202 802.1AS capable.
203 min_neighbor_prop_delay
205 Lower limit for peer delay in nanoseconds. If the estimated peer
206 delay is smaller than this value the port is marked as not
207 802.1AS capable.
208 tsproc_mode
210 Select the time stamp processing mode used to calculate offset
211 and delay. Possible values are filter, raw, filter_weight,
212 raw_weight. Raw modes perform well when the rate of sync mes‐
213 sages (logSyncInterval) is similar to the rate of delay messages
214 (logMinDelayReqInterval or logMinPdelayReqInterval). Weighting
215 is useful with larger network jitters (e.g. software time stamp‐
216 ing). The default is filter.
217 delay_filter
219 Select the algorithm used to filter the measured delay and peer
220 delay. Possible values are moving_average and moving_median.
221 The default is moving_median.
222 delay_filter_length
224 The length of the delay filter in samples. The default is 10.
225 egressLatency
227 Specifies the difference in nanoseconds between the actual
228 transmission time at the reference plane and the reported trans‐
229 mit time stamp. This value will be added to egress time stamps
230 obtained from the hardware. The default is 0.
231 ingressLatency
233 Specifies the difference in nanoseconds between the reported
234 receive time stamp and the actual reception time at reference
235 plane. This value will be subtracted from ingress time stamps
236 obtained from the hardware. The default is 0.
237 boundary_clock_jbod
239 When running as a boundary clock (that is, when more than one
240 network interface is configured), ptp4l performs a sanity check
241 to make sure that all of the ports share the same hardware clock
242 device. This option allows ptp4l to work as a boundary clock
243 using "just a bunch of devices" that are not synchronized to
244 each other. For this mode, the collection of clocks must be syn‐
245 chronized by an external program, for example phc2sys(8) in
246 "automatic" mode. The default is 0 (disabled).
247 udp_ttl
249 Specifies the Time to live (TTL) value for IPv4 multicast mes‐
250 sages and the hop limit for IPv6 multicast messages. This option
251 is only relevant with the IPv4 and IPv6 UDP transports. The
252 default is 1 to restrict the messages sent by ptp4l to the same
253 subnet.
254
257 twoStepFlag
258 Enable two-step mode for sync messages. One-step mode can be
259 used only with hardware time stamping. The default is 1
260 (enabled).
261 slaveOnly
263 The local clock is a slave-only clock if enabled. This option
264 is only for use with 1588 clocks and should not be enabled for
265 802.1AS clocks. The default is 0 (disabled).
266 gmCapable
268 If this option is enabled, then the local clock is able to
269 become grand master. This is only for use with 802.1AS clocks
270 and has no effect on 1588 clocks. The default is 1 (enabled).
271 priority1
273 The priority1 attribute of the local clock. It is used in the
274 best master selection algorithm, lower values take precedence.
275 Must be in the range 0 to 255. The default is 128.
276 priority2
278 The priority2 attribute of the local clock. It is used in the
279 best master selection algorithm, lower values take precedence.
280 Must be in the range 0 to 255. The default is 128.
281 clockClass
283 The clockClass attribute of the local clock. It denotes the
284 traceability of the time distributed by the grandmaster clock.
285 The default is 248.
286 clockAccuracy
288 The clockAccuracy attribute of the local clock. It is used in
289 the best master selection algorithm. The default is 0xFE.
290 offsetScaledLogVariance
292 The offsetScaledLogVariance attribute of the local clock. It
293 characterizes the stability of the clock. The default is
294 0xFFFF.
295 domainNumber
297 The domain attribute of the local clock. The default is 0.
298 utc_offset
300 The current offset between TAI and UTC. The default is 37.
301 free_running
303 Don't adjust the local clock if enabled. The default is 0 (dis‐
304 abled).
305 freq_est_interval
307 The time interval over which is estimated the ratio of the local
308 and peer clock frequencies. It is specified as a power of two in
309 seconds. The default is 1 (2 seconds).
310 assume_two_step
312 Treat one-step responses as two-step if enabled. It is used to
313 work around buggy 802.1AS switches. The default is 0 (dis‐
314 abled).
315 tx_timestamp_timeout
317 The number of milliseconds to poll waiting for the tx time stamp
318 from the kernel when a message has recently been sent. The
319 default is 1.
320 check_fup_sync
322 Because of packet reordering that can occur in the network, in
323 the hardware, or in the networking stack, a follow up message
324 can appear to arrive in the application before the matching sync
325 message. As this is a normal occurrence, and the sequenceID mes‐
326 sage field ensures proper matching, the ptp4l program accepts
327 out of order packets. This option adds an additional check using
328 the software time stamps from the networking stack to verify
329 that the sync message did arrive first. This option is only use‐
330 ful if you do not trust the sequence IDs generated by the mas‐
331 ter. The default is 0 (disabled).
332 clock_servo
334 The servo which is used to synchronize the local clock. Valid
335 values are "pi" for a PI controller, "linreg" for an adaptive
336 controller using linear regression, "ntpshm" for the NTP SHM
337 reference clock to allow another process to synchronize the
338 local clock (the SHM segment number is set to the domain num‐
339 ber), and "nullf" for a servo that always dials frequency offset
340 zero (for use in SyncE nodes). The default is "pi."
341 pi_proportional_const
343 The proportional constant of the PI controller. When set to 0.0,
344 the proportional constant will be set by the following formula
345 from the current sync interval. The default is 0.0.
346 kp = min(kp_scale * sync^kp_exponent, kp_norm_max / sync)
348 pi_integral_const
350 The integral constant of the PI controller. When set to 0.0, the
351 integral constant will be set by the following formula from the
352 current sync interval. The default is 0.0.
353 ki = min(ki_scale * sync^ki_exponent, ki_norm_max / sync)
355 pi_proportional_scale
357 The kp_scale constant in the formula used to set the propor‐
358 tional constant of the PI controller from the sync interval.
359 When set to 0.0, the value will be selected from 0.7 and 0.1 for
360 the hardware and software time stamping respectively. The
361 default is 0.0.
362 pi_proportional_exponent
364 The kp_exponent constant in the formula used to set the propor‐
365 tional constant of the PI controller from the sync interval.
366 The default is -0.3.
367 pi_proportional_norm_max
369 The kp_norm_max constant in the formula used to set the propor‐
370 tional constant of the PI controller from the sync interval.
371 The default is 0.7
372 pi_integral_scale
374 The ki_scale constant in the formula used to set the integral
375 constant of the PI controller from the sync interval. When set
376 to 0.0, the value will be selected from 0.3 and 0.001 for the
377 hardware and software time stamping respectively. The default
378 is 0.0.
379 pi_integral_exponent
381 The ki_exponent constant in the formula used to set the integral
382 constant of the PI controller from the sync interval. The
383 default is 0.4.
384 pi_integral_norm_max
386 The ki_norm_max constant in the formula used to set the integral
387 constant of the PI controller from the sync interval. The
388 default is 0.3.
389 step_threshold
391 The maximum offset the servo will correct by changing the clock
392 frequency instead of stepping the clock. When set to 0.0, the
393 servo will never step the clock except on start. It's specified
394 in seconds. The default is 0.0. This option used to be called
395 pi_offset_const.
396 first_step_threshold
398 The maximum offset the servo will correct by changing the clock
399 frequency instead of stepping the clock. This is only applied on
400 the first update. It's specified in seconds. When set to 0.0,
401 the servo won't step the clock on start. The default is 0.00002
402 (20 microseconds). This option used to be called pi_f_off‐
403 set_const.
404 max_frequency
406 The maximum allowed frequency adjustment of the clock in parts
407 per billion (ppb). This is an additional limit to the maximum
408 allowed by the hardware. When set to 0, the hardware limit will
409 be used. The default is 900000000 (90%). This option used to
410 be called pi_max_frequency.
411 sanity_freq_limit
413 The maximum allowed frequency offset between uncorrected clock
414 and the system monotonic clock in parts per billion (ppb). This
415 is used as a sanity check of the synchronized clock. When a
416 larger offset is measured, a warning message will be printed and
417 the servo will be reset. When set to 0, the sanity check is dis‐
418 abled. The default is 200000000 (20%).
419 ntpshm_segment
421 The number of the SHM segment used by ntpshm servo. The default
422 is 0.
423 udp6_scope
425 Specifies the desired scope for the IPv6 multicast messages.
426 This will be used as the second byte of the primary address.
427 This option is only relevant with IPv6 transport. See RFC 4291.
428 The default is 0x0E for the global scope.
429 uds_address
431 Specifies the address of the UNIX domain socket for receiving
432 local management messages. The default is /var/run/ptp4l.
433 dscp_event
435 Defines the Differentiated Services Codepoint (DSCP) to be used
436 for PTP event messages. Must be a value between 0 and 63. There
437 are several media streaming standards out there that require
438 specific values for this option. For example 46 (EF PHB) in
439 AES67 or 48 (CS6 PHB) in RAVENNA. The default is 0.
440 dscp_general
442 Defines the Differentiated Services Codepoint (DSCP) to be used
443 for PTP general messages. Must be a value between 0 and 63.
444 There are several media streaming standards out there that rec‐
445 ommend specific values for this option. For example 34 (AF41
446 PHB) in AES67 or 46 (EF PHB) in RAVENNA. The default is 0.
447 logging_level
449 The maximum logging level of messages which should be printed.
450 The default is 6 (LOG_INFO).
451 message_tag
453 The tag which is added to all messages printed to the standard
454 output or system log. The default is an empty string (which
455 cannot be set in the configuration file as the option requires
456 an argument).
457 verbose
459 Print messages to the standard output if enabled. The default
460 is 0 (disabled).
461 use_syslog
463 Print messages to the system log if enabled. The default is 1
464 (enabled).
465 summary_interval
467 The time interval in which are printed summary statistics of the
468 clock. It is specified as a power of two in seconds. The statis‐
469 tics include offset root mean square (RMS), maximum absolute
470 offset, frequency offset mean and standard deviation, and path
471 delay mean and standard deviation. The units are nanoseconds and
472 parts per billion (ppb). If there is only one clock update in
473 the interval, the sample will be printed instead of the statis‐
474 tics. The messages are printed at the LOG_INFO level. The
475 default is 0 (1 second).
476 time_stamping
478 The time stamping method. The allowed values are hardware, soft‐
479 ware and legacy. The default is hardware.
480 productDescription
482 The product description string. Allowed values must be of the
483 form manufacturerName;modelNumber;instanceIdentifier and contain
484 at most 64 utf8 symbols. The default is ";;".
485 revisionData
487 The revision description string which contains the revisions for
488 node hardware (HW), firmware (FW), and software (SW). Allowed
489 values are of the form HW;FW;SW and contain at most 32 utf8 sym‐
490 bols. The default is an ";;".
491 userDescription
493 The user description string. Allowed values are of the form
494 name;location and contain at most 128 utf8 symbols. The default
495 is an empty string.
496 manufacturerIdentity
498 The manufacturer id which should be an OUI owned by the manufac‐
499 turer. The default is 00:00:00.
500 kernel_leap
502 When a leap second is announced, let the kernel apply it by
503 stepping the clock instead of correcting the one-second offset
504 with servo, which would correct the one-second offset slowly by
505 changing the clock frequency (unless the step_threshold option
506 is set to correct such offset by stepping). Relevant only with
507 software time stamping. The default is 1 (enabled).
508 timeSource
510 The time source is a single byte code that gives an idea of the
511 kind of local clock in use. The value is purely informational,
512 having no effect on the outcome of the Best Master Clock algo‐
513 rithm, and is advertised when the clock becomes grand master.
514
517 ptp4l as domain master either uses PTP or UTC time scale depending on
518 time stamping mode. In software and legacy time stamping modes it
519 announces Arbitrary time scale mode, which is effectively UTC here, in
520 hardware time stamping mode it announces use of PTP time scale.
521 When ptp4l is the domain master using hardware time stamping, it is up
523 to phc2sys to maintain the correct offset between UTC and PTP times.
524 See phc2sys(8) manual page for more details.
525
528 pmc(8), phc2sys(8)
529linuxptp December 2016 PTP4l(8)