-
Notifications
You must be signed in to change notification settings - Fork 147
/
ptp4l.8
1241 lines (1065 loc) · 42.2 KB
/
ptp4l.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.TH PTP4l 8 "March 2024" "linuxptp"
.SH NAME
ptp4l - PTP Boundary/Ordinary/Transparent Clock
.SH SYNOPSIS
.B ptp4l
[
.B \-AEP246HSLmqsv
] [
.BI \-f " config"
] [
.BI \-p " phc-device"
] [
.BI \-l " print-level"
]
[
.BI \-i " interface"
] [
.I long-options
]
.I .\|.\|.
.SH DESCRIPTION
.B ptp4l
is an implementation of the Precision Time Protocol (PTP) according to IEEE
standard 1588 for Linux. It implements Boundary Clock (BC), Ordinary Clock
(OC), and Transparent Clock (TC).
.SH OPTIONS
.TP
.B \-A
Select the delay mechanism automatically. Start with E2E and switch to P2P when
a peer delay request is received.
.TP
.B \-E
Select the delay request-response (E2E) mechanism. This is the default
mechanism. All clocks on single PTP communication path must use the same
mechanism. A warning will be printed when a peer delay request is received on
port using the E2E mechanism.
.TP
.B \-P
Select the peer delay (P2P) mechanism. A warning will be printed when a delay
request is received on port using the P2P mechanism.
.TP
.B \-2
Select the IEEE 802.3 network transport.
.TP
.B \-4
Select the UDP IPv4 network transport. This is the default transport.
.TP
.B \-6
Select the UDP IPv6 network transport.
.TP
.B \-H
Select the hardware time stamping. All ports specified by the
.B \-i
option and in the configuration file must be attached to the same PTP hardware
clock (PHC). This is the default time stamping.
.TP
.B \-S
Select the software time stamping.
.TP
.B \-L
Select the legacy hardware time stamping.
.TP
.BI \-f " config"
Read configuration from the specified file. No configuration file is read by
default.
.TP
.BI \-i " interface"
Specify a PTP port, it may be used multiple times. At least one port must be
specified by this option or in the configuration file.
.TP
.BI \-p " phc-device"
(This option is deprecated.)
Before Linux kernel v3.5 there was no way to discover the PHC device
associated with a network interface. This option specifies the PHC
device (e.g. /dev/ptp0) to be used when running on legacy kernels.
.TP
.B \-s
Enable the clientOnly mode.
.TP
.BI \-l " print-level"
Set the maximum syslog level of messages which should be printed or sent to
the system logger. The default is 6 (LOG_INFO).
.TP
.B \-m
Print messages to the standard output.
.TP
.B \-q
Don't send messages to the system logger.
.TP
.B \-v
Prints the software version and exits.
.TP
.BI \-h
Display a help message.
.SH LONG OPTIONS
Each and every configuration file option (see below) may also appear
as a "long" style command line argument. For example, the clientOnly
option may be set using either of these two forms.
.RS
\f(CW\-\-clientOnly 1 \-\-clientOnly=1\fP
.RE
Option values given on the command line override values in the global
section of the configuration file.
.SH CONFIGURATION FILE
The configuration file is divided into sections. Each section starts with a
line containing its name enclosed in brackets and it follows with settings.
Each setting is placed on a separate line, it contains the name of the
option and the value separated by whitespace characters. Empty lines and lines
starting with # are ignored.
There are three different section types.
.TP
.B 1.
The global section (indicated as
.BR [global] )
sets the program options, clock options and default port options. Other
sections are port specific sections and they override the default port options.
.TP
.B 2.
Port sections give the name of the configured port (e.g.
.BR [eth0] ).
Ports specified in the configuration file don't need to be
specified by the
.B \-i
option. An empty port section can be used to replace the command line option.
.TP
.B 3.
Tables for configuring unicast discovery begin with
.B \%[unicast_master_table].
See UNICAST DISCOVERY OPTIONS, below.
.SH PORT OPTIONS
.TP
.B active_key_id
Used in conjunction with \fBspp\fR and \fBsa_file\fR directives to
specify which key from the \fBspp\fR defined Security Association
should be used for outbound icv calculations. All Security Assocations
are read from the file specified by \fBsa_file\fR. Requires \fBspp\fR
and \fBsa_file\fR directives. Must be in the range of 1 to 2^32-1,
inclusive. The default is 0 (disabled).
.TP
.B allowedLostResponses
The number of missed peer delay responses before the asCapable variable is
reset.
The default is 3.
.TP
.B announceReceiptTimeout
The number of missed Announce messages before the last Announce messages
expires.
The default is 3.
.TP
.B boundary_clock_jbod
When running as a boundary clock (that is, when more than one network
interface is configured), ptp4l performs a sanity check to make sure
that all of the ports share the same hardware clock device. This
option allows ptp4l to work as a boundary clock using "just a bunch of
devices" that are not synchronized to each other. For this mode, the
collection of clocks must be synchronized by an external program, for
example phc2sys(8) in "automatic" mode.
The default is 0 (disabled).
.TP
.B cmlds.client_address
Specifies the source address for the UNIX domain socket that receives
peer delay measurement when using the "COMMON_P2P" delay mechanism.
The default is /var/run/cmlds_client.
.TP
.B cmlds.domainNumber
Specifies the domainNumber message field for communications with the
local Common Mean Link Delay Service, used with the "COMMON_P2P" delay
mechanism.
The default is 0.
.TP
.B cmlds.majorSdoId
Specifies the transportSpecific message field for communications with
the local Common Mean Link Delay Service, used with the "COMMON_P2P"
delay mechanism.
The default is 2.
.TP
.B cmlds.port
Specifies the port number of local Common Mean Link Delay Service from
which to accept delay measurements. The range of valid port numbers
is one to 65535, but the special value zero configures the port number
of the port requesting the measurements.
The default is 0, meaning the requesting port number.
.TP
.B
cmlds.server_address
Specifies the UNIX domain socket address of the local Common Mean Link
Delay Service, for use with the "COMMON_P2P" delay mechanism.
The default is /var/run/cmlds_server.
.TP
.B delayAsymmetry
The time difference in nanoseconds of the transmit and receive
paths. This value should be positive when the server-to-client
propagation time is longer and negative when the client-to-server time
is longer. The default is 0 nanoseconds.
.TP
.B delay_filter
Select the algorithm used to filter the measured delay and peer delay. Possible
values are moving_average and moving_median.
The default is moving_median.
.TP
.B delay_filter_length
The length of the delay filter in samples.
The default is 10.
.TP
.B delay_mechanism
Select the delay mechanism. Possible values are Auto, COMMON_P2P, E2E,
P2P, and NONE.
The default is E2E.
.TP
.B delay_response_timeout
The number of delay response messages that may go missing before
triggering a synchronization fault. Setting this option to zero will
disable the delay response timeout.
The default is 0 or disabled.
.TP
.B egressLatency
Specifies the difference in nanoseconds between the actual transmission
time at the reference plane and the reported transmit time stamp. This
value will be added to egress time stamps obtained from the hardware.
The default is 0.
.TP
.B fault_badpeernet_interval
The time in seconds between the detection of a peer network misconfiguration
and the fault being reset. The port is disabled for the duration of the
interval. The value is in seconds and the special key word ASAP will let
the fault be reset immediately.
The default is 16 seconds.
.TP
.B fault_reset_interval
The time in seconds between the detection of a port's fault and the fault
being reset. This value is expressed as a power of two. Setting this
value to \-128 or to the special key word "ASAP" will let the fault be
reset immediately.
The default is 4 (16 seconds).
.TP
.B follow_up_info
Include the 802.1AS data in the Follow_Up messages if enabled.
The default is 0 (disabled).
.TP
.B G.8275.portDS.localPriority
The Telecom Profiles (ITU-T G.8275.1 and G.8275.2) specify an
alternate Best Master Clock Algorithm (BMCA) with a unique data set
comparison algorithm. The value of this option is associated with
Announce messages arriving on a particular port and is used as a tie
breaker whenever clockClass, clockAccuracy, offsetScaledLogVariance,
and priority2 are equal. This option is only used when
"dataset_comparison" is set to "G.8275.x".
The default value is 128.
Warning: the BMCA is guaranteed to produce a spanning tree (that is, a
timing network without loops) only when using the default values of
G.8275.defaultDS.localPriority and G.8275.portDS.localPriority.
Careful network engineering is needed when using non-default values.
.TP
.B hybrid_e2e
Enables the "hybrid" delay mechanism from the draft Enterprise
Profile. When enabled, ports in the client state send their delay
request messages to the unicast address taken from the server's
announce message. Ports in the server state will reply to unicast
delay requests using unicast delay responses. This option has no
effect if the delay_mechanism is set to P2P.
The default is 0 (disabled).
.TP
.B ignore_transport_specific
By default, incoming messages are dropped if their transportSpecific
field does not match the configured value. However, many of
transports specified in the 1588 standard mandate ignoring this field.
Moreover, some equipment is known to set the reserved bits.
Configuring this option as 1 causes this field to be ignored
completely on receive. The default is 0.
.TP
.B ingressLatency
Specifies the difference in nanoseconds between the reported receive
time stamp and the actual reception time at reference plane. This value
will be subtracted from ingress time stamps obtained from the hardware.
The default is 0.
.TP
.B inhibit_delay_req
Don't send any delay requests. This will need the asCapable config option to be
set to 'true'. This is useful when running as a designated server who does not
need to calculate offset from client. The default is 0 (disabled).
.TP
.B inhibit_multicast_service
Some unicast mode profiles insist that no multicast message are ever
transmitted. Setting this option inhibits multicast transmission.
The default is 0 (mutlicast enabled).
.TP
.B logAnnounceInterval
The mean time interval between Announce messages. A shorter interval makes
ptp4l react faster to the changes in the client/server hierarchy. The interval
should be the same in the whole domain. It's specified as a power of two in
seconds.
The default is 1 (2 seconds).
.TP
.B logMinDelayReqInterval
The minimum permitted mean time interval between Delay_Req messages. A shorter
interval makes ptp4l react faster to the changes in the path delay. It's
specified as a power of two in seconds.
The default is 0 (1 second).
.TP
.B logMinPdelayReqInterval
The minimum permitted mean time interval between Pdelay_Req messages. It's
specified as a power of two in seconds.
The default is 0 (1 second).
.TP
.B logSyncInterval
The mean time interval between Sync messages. A shorter interval may improve
accuracy of the local clock. It's specified as a power of two in seconds.
The default is 0 (1 second).
.TP
.B masterOnly
This option is deprecated and will be removed in a future release.
Use "serverOnly" instead.
.TP
.B min_neighbor_prop_delay
Lower limit for peer delay in nanoseconds. If the estimated peer delay is
smaller than this value the port is marked as not 802.1AS capable.
.TP
.B neighborPropDelayThresh
Upper limit for peer delay in nanoseconds. If the estimated peer delay is
greater than this value the port is marked as not 802.1AS capable.
.TP
.B network_transport
Select the network transport. Possible values are UDPv4, UDPv6 and L2.
The default is UDPv4.
.TP
.B net_sync_monitor
Enables the NetSync Monitor (NSM) protocol. The NSM protocol allows a
station to measure how well another node is synchronized. The monitor
sends a unicast delay request to the node, which replies
unconditionally with unicast delay response, sync, and follow up
messages. If the monitor is synchronized to the GM, it can use the
time stamps in the message to estimate the node's offset. This option
requires that the 'hybrid_e2e' option be enabled as well.
The default is 0 (disabled).
.TP
.B operLogPdelayReqInterval
The Pdelay Request messages interval to be used once the clock enters
the SERVO_LOCKED_STABLE state. If the 'msg_interval_request' option
is set, then the local client port will adopt this rate when the local
clock enters the "locked stable" state. This option is specified as a
power of two in seconds, and the default value is 0 (1 second).
.TP
.B operLogSyncInterval
The Sync message interval to be requested once the clock enters the
SERVO_LOCKED_STABLE state. If the 'msg_interval_request' option is
set, then the local client port will request the remote server to
switch to the given message rate via a signaling message containing a
Message interval request TLV. This option is specified as a power of
two in seconds, and default value is 0 (1 second).
.TP
.B path_trace_enabled
Enable the mechanism used to trace the route of the Announce messages.
The default is 0 (disabled).
.TP
.B phc_index
Specifies the index of the PHC to be used for synchronization with hardware
timestamping. This option is useful with virtual clocks running on top of a
free-running physical clock (created by writing to
/sys/class/ptp/ptp*/n_vclocks).
The default is -1, which means the index will be set to the PHC associated with
the interface, or the device specified by the \fB-p\fP option.
.TP
.B power_profile.2011.grandmasterTimeInaccuracy
Specifies the time inaccuracy of the GM in nanoseconds. Relevant only
when power_profile.version is 2011. This value may be changed
dynamically using the POWER_PROFILE_SETTINGS_NP management message.
The default is -1 meaning unknown inaccuracy.
.TP
.B power_profile.2011.networkTimeInaccuracy
Specifies the time inaccuracy of the network in nanoseconds. Relevant
only when power_profile.version is 2011. This value may be changed
dynamically using the POWER_PROFILE_SETTINGS_NP management message.
The default is -1 meaning unknown inaccuracy.
.TP
.B power_profile.2017.totalTimeInaccuracy
Specifies the sum of the GM, network, and local node inaccuracies in
nanoseconds. Relevant only when power_profile.version is 2017. This
value may be changed dynamically using the POWER_PROFILE_SETTINGS_NP
management message. The default is -1 meaning unknown inaccuracy.
.TP
.B power_profile.grandmasterID
Specifies an optional, non-zero identification code for the GM. Note
that the code is an arbitrary, power profile specific integer, not
necessarily related to the clockIdentity in any way. This value may
be changed dynamically using the POWER_PROFILE_SETTINGS_NP management
message. The default is 0 meaning unused.
.TP
.B power_profile.version
Specifies the power profile version to be used. Valid values are
"none", "2011", or "2017".
This value may be changed dynamically using the
POWER_PROFILE_SETTINGS_NP management message.
The default is "none".
.TP
.B ptp_dst_ipv4
The IPv4 address to which PTP messages should be sent.
Relevant only with UDPv4 transport. The default is 224.0.1.129.
.TP
.B p2p_dst_ipv4
The IPv4 address to which peer delay messages should be sent.
Relevant only with UDPv4 transport. The default is 224.0.0.107.
.TP
.B ptp_dst_ipv6
The IPv6 address to which PTP messages should be sent.
The second byte of the address is substituted with udp6_scope.
Relevant only with UDPv6 transport. The default is FF0E:0:0:0:0:0:0:181.
.TP
.B p2p_dst_ipv6
The IPv6 address to which peer delay messages should be sent.
Relevant only with UDPv6 transport. The default is FF02:0:0:0:0:0:0:6B.
.TP
.B ptp_dst_mac
The MAC address to which PTP messages should be sent.
Relevant only with L2 transport. The default is 01:1B:19:00:00:00.
.TP
.B p2p_dst_mac
The MAC address to which peer delay messages should be sent.
Relevant only with L2 transport. The default is 01:80:C2:00:00:0E.
.TP
.B serverOnly
Setting this option to one (1) prevents the port from entering the
client state. In addition, the local clock will ignore Announce
messages received on this port. This option's intended use is to
support the Telecom Profiles according to ITU-T G.8265.1, G.8275.1,
and G.8275.2. The default value is zero or false.
.TP
.B spp
Specifies the Security Parameters Pointer of the desired Security
Association to be used for Authentication TLV support for a given port.
Any port with an assigned spp will attach Authentication TLVs to all
outbound messages and check for Authentication TLVs on all inbound
messages in accordance to the corresponding security association
sourced via the \fBsa_file\fR directive. Outbound Authentication TLVs
are generated using the key specified by \fBactive_key_id\fR. Not
compatible with one step ports or advertised versions less then
PTPv2.1. Requires \fBsa_file\fR and \fBactive_key_id\fR directives.
Must be in the range of 0 to 255, inclusive.
The default is -1 (disabled).
.TP
.B syncReceiptTimeout
The number of sync/follow up messages that may go missing before
triggering a Best Master Clock election. This option is used for
running in gPTP mode according to the 802.1AS-2011 standard. Setting
this option to zero will disable the sync message timeout.
The default is 0 or disabled.
.TP
.B transportSpecific
The transport specific field. Must be in the range 0 to 255.
The default is 0.
.TP
.B tsproc_mode
Select the time stamp processing mode used to calculate offset and delay.
Possible values are filter, raw, filter_weight, raw_weight. Raw modes perform
well when the rate of sync messages (logSyncInterval) is similar to the rate of
delay messages (logMinDelayReqInterval or logMinPdelayReqInterval). Weighting
is useful with larger network jitters (e.g. software time stamping).
The default is filter.
.TP
.B udp_ttl
Specifies the Time to live (TTL) value for IPv4 multicast messages and the hop
limit for IPv6 multicast messages. This option is only relevant with the IPv4
and IPv6 UDP transports. The default is 1 to restrict the messages sent by
.B ptp4l
to the same subnet.
.TP
.B unicast_listen
When enabled, this option allows the port to grant unicast message
contracts. Incoming requests for will be granted limited only by the
amount of memory available.
The default is 0 (disabled).
.TP
.B unicast_master_table
When set to a positive integer, this option specifies the table id to
be used for unicast discovery. Each table lives in its own section
and has a unique, positive numerical ID. Entries in the table are a
pair of transport type and protocol address.
The default is 0 (unicast discovery disabled).
.TP
.B unicast_req_duration
The service time in seconds to be requested during unicast discovery.
Note that the remote node is free to grant a different duration.
The default is 3600 seconds or one hour.
.SH PROGRAM AND CLOCK OPTIONS
.TP
.B asCapable
If set to 'true', all the checks which can unset asCapable variable (as
described in Section 10.2.4.1 of 802.1AS) are skipped. If set to 'auto',
asCapable is initialized to 'false' and will be set to 'true' after the
relevant checks have passed. The default value is 'auto'.
.TP
.B assume_two_step
Treat one-step responses as two-step if enabled. It is used to work around
buggy 802.1AS switches.
The default is 0 (disabled).
.TP
.B BMCA
This option enables use of static roles for server and client devices
instead of running the best master clock algorithm (BMCA) described in
1588 profile. This can be used to speed up the start time for servers
and clients when you know the roles of the devices in advance. When set to
\'noop', the traditional BMCA algorithm used by 1588 is skipped. masterOnly and
clientOnly will be used to determine the server or client role for the device. In a
bridge, clientOnly (which is a global option) can be set to make all ports
assume the client role. masterOnly (which is a per-port config option) can then
be used to set individual ports to take on the server role.
The default value is 'ptp' which runs the BMCA related state machines.
.TP
.B check_fup_sync
Because of packet reordering that can occur in the network, in the
hardware, or in the networking stack, a follow up message can appear
to arrive in the application before the matching sync message. As this
is a normal occurrence, and the sequenceID message field ensures
proper matching, the ptp4l program accepts out of order packets. This
option adds an additional check using the software time stamps from
the networking stack to verify that the sync message did arrive
first. This option is only useful if you do not trust the sequence IDs
generated by the server.
The default is 0 (disabled).
.TP
.B clientOnly
The local clock is a client-only clock if enabled. The default is 0 (disabled).
.TP
.B clockAccuracy
The clockAccuracy attribute of the local clock. It is used in the PTP server
selection algorithm.
The default is 0xFE.
.TP
.B clockClass
The clockClass attribute of the local clock. It denotes the traceability of the
time distributed by the grandmaster clock.
The default is 248.
.TP
.B clock_class_threshold
The maximum clock class value from master, acceptible to sub-ordinate
clock beyond which it moves out of lock state.
The default value is 248.
.TP
.B clockIdentity
The clockIdentity attribute of the local clock.
The clockIdentity is an 8-octet array and should in this configuration be
written in textual form, see default. It should be unique since it is used to
identify the specific clock.
If default is used or if not set at all, the clockIdentity will be automtically
generated.
The default is "000000.0000.000000"
.TP
.B clock_servo
The servo which is used to synchronize the local clock. Valid values
are "pi" for a PI controller, "linreg" for an adaptive controller
using linear regression, "ntpshm" and "refclock_sock" for the NTP SHM and
chrony SOCK reference clocks respectively to allow another process to
synchronize the local clock, and "nullf" for a servo that always dials
frequency offset zero (for use in SyncE nodes).
The default is "pi."
.TP
.B clock_type
Specifies the kind of PTP clock. Valid values are "OC" for ordinary
clock, "BC" for boundary clock, "P2P_TC" for peer to peer transparent
clock, and "E2E_TC" for end to end transparent clock. An multi-port
ordinary clock will automatically be configured as a boundary clock.
The default is "OC".
.TP
.B dataset_comparison
Specifies the method to be used when comparing data sets during the
Best Master Clock Algorithm. The possible values are "ieee1588" and
"G.8275.x". The default is "ieee1588".
.TP
.B domainNumber
The domain attribute of the local clock.
The default is 0.
.TP
.B dscp_event
Defines the Differentiated Services Codepoint (DSCP) to be used for PTP
event messages. Must be a value between 0 and 63. There are several media
streaming standards out there that require specific values for this option.
For example 46 (EF PHB) in AES67 or 48 (CS6 PHB) in RAVENNA. The default
is 0.
.TP
.B dscp_general
Defines the Differentiated Services Codepoint (DSCP) to be used for PTP
general messages. Must be a value between 0 and 63. There are several media
streaming standards out there that recommend specific values for this option.
For example 34 (AF41 PHB) in AES67 or 46 (EF PHB) in RAVENNA. The default
is 0.
.TP
.B first_step_threshold
The maximum offset the servo will correct by changing the clock frequency (phase
when using nullf servo) instead of stepping the clock. This is only applied on
the first update. It's specified in seconds. When set to 0.0, the servo won't
step the clock on start.
The default is 0.00002 (20 microseconds).
This option used to be called
.BR pi_f_offset_const .
.TP
.B free_running
Don't adjust the local clock if enabled.
The default is 0 (disabled).
.TP
.B freq_est_interval
The time interval over which is estimated the ratio of the local and
peer clock frequencies. It is specified as a power of two in seconds.
The default is 1 (2 seconds).
.TP
.B G.8275.defaultDS.localPriority
The Telecom Profiles (ITU-T G.8275.1 and G.8275.2) specify an
alternate Best Master Clock Algorithm (BMCA) with a unique data set
comparison algorithm. The value of this option is associated with the
local clock and is used as a tie breaker whenever clockClass,
clockAccuracy, offsetScaledLogVariance, and priority2 are equal. This
option is only used when "dataset_comparison" is set to "G.8275.x".
The default value is 128.
Warning: the BMCA is guaranteed to produce a spanning tree (that is, a
timing network without loops) only when using the default values of
G.8275.defaultDS.localPriority and G.8275.portDS.localPriority.
Careful network engineering is needed when using non-default values.
.TP
.B gmCapable
If this option is enabled, then the local clock is able to become grand master.
This is only for use with 802.1AS clocks and has no effect on 1588 clocks.
The default is 1 (enabled).
.TP
.B ignore_source_id
This will disable source port identity checking for Sync and Follow_Up
messages. This is useful when the announce messages are disabled in the server
and the client does not have any way to know the server's identity.
The default is 0 (disabled).
.TP
.B inhibit_announce
This will disable the timer for announce messages (i.e. FD_MANNO_TIMER) and
also the announce message timeout timer (i.e. FD_ANNOUNCE_TIMER). This is used
by the Automotive profile as part of switching over to a static BMCA. If this
option is enabled, ignore_source_id has to be enabled in the client because it
has no way to identify the server in the Sync and Follow_Up messages. The
default is 0 (disabled).
.TP
.B initial_delay
The initial path delay of the clock in nanoseconds used for synchronization of
the clock before the delay is measured using the E2E or P2P delay mechanism. If
set to 0, the clock will not be updated until the delay is measured.
The default is 0.
.TP
.B interface_rate_tlv
When the client and server are operating are operating at different interface rate,
delay asymmetry caused due to different interface rate needs to be compensated.
The server sends its interface rate using interface rate TLV
as per G.8275.2 Annex D.
The default is 0 (does not support interface rate tlv).
.TP
.B hwts_filter
Select the hardware time stamp filter setting mode.
Possible values are normal, check, full.
Normal mode set the filters as needed.
Check mode only check but do not set.
Full mode set the receive filter to mark all packets with hardware time stamp,
so all applications can get them.
The default is normal.
.TP
.B kernel_leap
When a leap second is announced, let the kernel apply it by stepping the clock
instead of correcting the one-second offset with servo, which would correct the
one-second offset slowly by changing the clock frequency (unless the
.B step_threshold
option is set to correct such offset by stepping).
Relevant only with software time stamping. The default is 1 (enabled).
.TP
.B logging_level
The maximum logging level of messages which should be printed.
The default is 6 (LOG_INFO).
.TP
.B manufacturerIdentity
The manufacturer id which should be an OUI owned by the manufacturer.
The default is 00:00:00.
.TP
.B max_frequency
The maximum allowed frequency adjustment of the clock in parts per billion
(ppb). This is an additional limit to the maximum allowed by the hardware. When
set to 0, the hardware limit will be used.
The default is 900000000 (90%).
This option used to be called
.BR pi_max_frequency .
.TP
.B maxStepsRemoved
When using this option, if the value of stepsRemoved of an Announce
message is greater than or equal to the value of maxStepsRemoved the
Announce message is not considered in the operation of the BMCA.
The default value is 255.
.TP
.B message_tag
The tag which is added to all messages printed to the standard output or system
log. If the tag contains the string "{level}", it will be replaced with the log
level of the message as a number.
The default is an empty string (which cannot be set in the configuration file
as the option requires an argument).
.TP
.B msg_interval_request
This option, when set, will trigger an adjustment to the Sync and peer
delay request message intervals when the clock servo transitions into
the SERVO_LOCKED_STABLE state. The Sync interval will be adjusted via
the signaling mechanism while the pdelay request interval is simply
adjusted locally. The values to use for the new Sync and peer delay
request intervals are specified by the operLogSyncInterval and
operLogPdelayReqInterval options, respectively.
The default value of msg_interval_request is 0 (disabled).
.TP
.B ntpshm_segment
The number of the SHM segment used by ntpshm servo.
The default is 0.
.TP
.B offsetScaledLogVariance
The offsetScaledLogVariance attribute of the local clock. It characterizes the
stability of the clock.
The default is 0xFFFF.
.TP
.B pi_integral_const
The integral constant of the PI controller. When set to 0.0, the
integral constant will be set by the following formula from the current
sync interval.
The default is 0.0.
ki = min(ki_scale * sync^ki_exponent, ki_norm_max / sync)
.TP
.B pi_integral_exponent
The ki_exponent constant in the formula used to set the integral constant of
the PI controller from the sync interval.
The default is 0.4.
.TP
.B pi_integral_norm_max
The ki_norm_max constant in the formula used to set the integral constant of
the PI controller from the sync interval.
The default is 0.3.
.TP
.B pi_integral_scale
The ki_scale constant in the formula used to set the integral constant of
the PI controller from the sync interval. When set to 0.0, the value will be
selected from 0.3 and 0.001 for the hardware and software time stamping
respectively.
The default is 0.0.
.TP
.B pi_proportional_const
The proportional constant of the PI controller. When set to 0.0, the
proportional constant will be set by the following formula from the current
sync interval.
The default is 0.0.
kp = min(kp_scale * sync^kp_exponent, kp_norm_max / sync)
.TP
.B pi_proportional_exponent
The kp_exponent constant in the formula used to set the proportional constant of
the PI controller from the sync interval.
The default is \-0.3.
.TP
.B pi_proportional_norm_max
The kp_norm_max constant in the formula used to set the proportional constant of
the PI controller from the sync interval.
The default is 0.7
.TP
.B pi_proportional_scale
The kp_scale constant in the formula used to set the proportional constant of
the PI controller from the sync interval. When set to 0.0, the value will be
selected from 0.7 and 0.1 for the hardware and software time stamping
respectively.
The default is 0.0.
.TP
.B productDescription
The product description string. Allowed values must be of the form
manufacturerName;modelNumber;instanceIdentifier and contain at most 64
utf8 symbols. The default is ";;".
.TP
.B priority1
The priority1 attribute of the local clock. It is used in the PTP server
selection algorithm, lower values take precedence. Must be in the range 0 to
255.
The default is 128.
.TP
.B priority2
The priority2 attribute of the local clock. It is used in the PTP server
selection algorithm, lower values take precedence. Must be in the range 0 to
255.
The default is 128.
.TP
.B ptp_minor_version
This option sets the minorVersionPTP in the common PTP message header.
The default is 1.
.TP
.B refclock_sock_address
The address of the UNIX domain socket to be used by the refclock_sock servo.
The default is /var/run/refclock.ptp.sock.
.TP
.B revisionData
The revision description string which contains the revisions for node
hardware (HW), firmware (FW), and software (SW). Allowed values are of
the form HW;FW;SW and contain at most 32 utf8 symbols. The default is
an ";;".
.TP
.B sa_file
Specifies the location of the file containing Security Associations
used for immediate security processing of the Authentication TLV in
support of the optional security mechanism defined in ieee1588-2019
ch 14.16. See \fBSECURITY ASSOCIATION OPTIONS\fR for information on how
this file should be formatted. \fBspp\fR and \fBactive_key_id\fR should
be specifed for each port to indicate which Security Association from
the /fBsa_file/fR should be used. The default is an empty string.
.TP
.B sanity_freq_limit
The maximum allowed frequency offset between uncorrected clock and the system
monotonic clock in parts per billion (ppb). This is used as a sanity check of
the synchronized clock. When a larger offset is measured, a warning message
will be printed and the servo will be reset. If the frequency correction set by
ptp4l changes unexpectedly between updates of the clock (e.g. due to another
process trying to control the clock), a warning message will be printed. When
set to 0, the sanity check is disabled. The default is 200000000 (20%).
.TP
.B servo_num_offset_values
The number of offset values considered in order to transition from the
SERVO_LOCKED to the SERVO_LOCKED_STABLE state.
The transition occurs once the last 'servo_num_offset_values' offsets
are all below the 'servo_offset_threshold' value.
The default value is 10.
.TP
.B servo_offset_threshold
The offset threshold used in order to transition from the SERVO_LOCKED
to the SERVO_LOCKED_STABLE state. The transition occurs once the
last 'servo_num_offset_values' offsets are all below the threshold value.
The default value of offset_threshold is 0 (disabled).
.TP
.B slave_event_monitor
Specifies the address of a UNIX domain socket for event
monitoring. A local monitoring client bound to this address will receive
SLAVE_RX_SYNC_TIMING_DATA and SLAVE_DELAY_TIMING_DATA_NP TLVs.
The default is the empty string (disabled).
.TP
.B slaveOnly
This option is deprecated and will be removed in a future release.
Use "clientOnly" instead.
.TP
.B socket_priority
Configure the SO_PRIORITY of sockets. This is to support cases where a user
wants to route ptp4l traffic using Linux qdiscs for the purpose of traffic
shaping. This option is only available with the IEEE 802.3 transport (the
\fB-2\fP option) and is silently ignored when using the UDP IPv4/6 network
transports. Must be in the range of 0 to 15, inclusive. The default is 0.
.TP
.B step_threshold
The maximum offset the servo will correct by changing the clock frequency (phase
when using nullf servo) instead of stepping the clock. When set to 0.0, the
servo will never step the clock except on start. It's specified in seconds.
The default is 0.0.
This option used to be called
.BR pi_offset_const .
.TP
.B step_window
When set, indicates the number of Sync events after a clock step that
the clock will not do any frequency or step adjustments.
This is used in situations where clock stepping is unable to happen
instantaneously so there is a lag before the timestamps can settle
properly to reflect the clock step.
The default is 0 (disabled).
.TP
.B summary_interval
The time interval in which are printed summary statistics of the clock. It is
specified as a power of two in seconds. The statistics include offset root mean
square (RMS), maximum absolute offset, frequency offset mean and standard
deviation, and path delay mean and standard deviation. The units are
nanoseconds and parts per billion (ppb). If there is only one clock update in
the interval, the sample will be printed instead of the statistics. The
messages are printed at the LOG_INFO level.
The default is 0 (1 second).