1PTP4l(8)                    System Manager's Manual                   PTP4l(8)
2
3
4

NAME

6       ptp4l - PTP Boundary/Ordinary Clock
7
8

SYNOPSIS

10       ptp4l  [  -AEP246HSLmqsv  ] [ -f config ] [ -p phc-device ] [ -l print-
11       level ] [ -i interface ] [ long-options ] ...
12
13

DESCRIPTION

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
19

OPTIONS

21       -A     Select the delay mechanism automatically.  Start  with  E2E  and
22              switch to P2P when a peer delay request is received.
23
24       -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
29       -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
33       -2     Select the IEEE 802.3 network transport.
34
35       -4     Select the UDP IPv4  network  transport.  This  is  the  default
36              transport.
37
38       -6     Select the UDP IPv6 network transport.
39
40       -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
45       -S     Select the software time stamping.
46
47       -L     Select the legacy hardware time stamping.
48
49       -f config
50              Read configuration from the  specified  file.  No  configuration
51              file is read by default.
52
53       -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
58       -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
64       -s     Enable the slaveOnly mode.
65
66       -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
70       -m     Print messages to the standard output.
71
72       -q     Don't send messages to the system logger.
73
74       -v     Prints the software version and exits.
75
76       -h     Display a help message.
77
78

LONG OPTIONS

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
84              --slaveOnly 1   --slaveOnly=1
85
86       Option  values  given on the command line override values in the global
87       section of the configuration file.
88
89

CONFIGURATION FILE

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
97       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
105

PORT OPTIONS

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
113       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
120       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
125       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
131       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
136       announceReceiptTimeout
137              The number of missed Announce messages before the last  Announce
138              messages expires.  The default is 3.
139
140       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
147       transportSpecific
148              The  transport  specific  field.  Must be in the range 0 to 255.
149              The default is 0.
150
151       path_trace_enabled
152              Enable the mechanism used to trace the  route  of  the  Announce
153              messages.  The default is 0 (disabled).
154
155       follow_up_info
156              Include  the  802.1AS data in the Follow_Up messages if enabled.
157              The default is 0 (disabled).
158
159       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
166       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
173       delay_mechanism
174              Select the delay mechanism. Possible values  are  E2E,  P2P  and
175              Auto.  The default is E2E.
176
177       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
186       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
190       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
195       network_transport
196              Select the network transport. Possible values are  UDPv4,  UDPv6
197              and L2.  The default is UDPv4.
198
199       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
204       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
209       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
218       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
223       delay_filter_length
224              The length of the delay filter in samples.  The default is 10.
225
226       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
232       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
238       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
248       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
255

PROGRAM AND CLOCK OPTIONS

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
262       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
267       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
272       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
277       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
282       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
287       clockAccuracy
288              The clockAccuracy attribute of the local clock. It  is  used  in
289              the best master selection algorithm.  The default is 0xFE.
290
291       offsetScaledLogVariance
292              The  offsetScaledLogVariance  attribute  of  the local clock. It
293              characterizes the  stability  of  the  clock.   The  default  is
294              0xFFFF.
295
296       domainNumber
297              The domain attribute of the local clock.  The default is 0.
298
299       utc_offset
300              The current offset between TAI and UTC.  The default is 37.
301
302       free_running
303              Don't adjust the local clock if enabled.  The default is 0 (dis‐
304              abled).
305
306       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
311       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
316       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
321       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
333       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
342       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
347              kp = min(kp_scale * sync^kp_exponent, kp_norm_max / sync)
348
349       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
354              ki = min(ki_scale * sync^ki_exponent, ki_norm_max / sync)
355
356       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
363       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
368       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
373       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
380       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
385       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
390       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
397       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
405       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
412       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
420       ntpshm_segment
421              The number of the SHM segment used by ntpshm servo.  The default
422              is 0.
423
424       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
430       uds_address
431              Specifies  the  address  of the UNIX domain socket for receiving
432              local management messages. The default is /var/run/ptp4l.
433
434       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
441       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
448       logging_level
449              The maximum logging level of messages which should  be  printed.
450              The default is 6 (LOG_INFO).
451
452       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
458       verbose
459              Print messages to the standard output if enabled.   The  default
460              is 0 (disabled).
461
462       use_syslog
463              Print  messages  to the system log if enabled.  The default is 1
464              (enabled).
465
466       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
477       time_stamping
478              The time stamping method. The allowed values are hardware, soft‐
479              ware and legacy.  The default is hardware.
480
481       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
486       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
492       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
497       manufacturerIdentity
498              The manufacturer id which should be an OUI owned by the manufac‐
499              turer.  The default is 00:00:00.
500
501       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
509       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
515

TIME SCALE USAGE

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
522       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
526

SEE ALSO

528       pmc(8), phc2sys(8)
529
530
531
532linuxptp                         December 2016                        PTP4l(8)
Impressum